This page covers the purpose and high-level structure of the akash-network/node repository (Go module path: pkg.akt.dev/node). It describes what the repository contains, how the major subsystems relate, and what technology it builds on. For detailed treatment of individual subsystems, follow the links in each section to the relevant child pages.
The akash-network/node repository is the reference implementation of the Akash Protocol — a decentralized, permissionless cloud computing marketplace. It connects two parties:
| Role | Description |
|---|---|
| Tenant | A user who authors a workload specification (SDL) and creates a deployment on the Akash blockchain |
| Provider | An operator with spare compute capacity who bids on tenant orders and runs workloads on Kubernetes |
The repository produces a single binary, akash, which serves two distinct operational roles simultaneously:
For more detail on the two-sided marketplace model and core terminology, see What is Akash Node and Key Terminology.
Sources: README.md1-38
The top-level directories and their roles:
| Directory | Role |
|---|---|
app/ | AkashApp: the Cosmos SDK application struct wiring all modules together |
cmd/akash/ | Entry point; cobra-based CLI; appCreator interface binding CLI to AkashApp |
x/ | Custom on-chain Cosmos SDK modules (deployment, market, provider, escrow, audit, cert) |
provider/ | Off-chain provider daemon: bid engine, Kubernetes cluster client, manifest handler |
sdl/ | Service Definition Language parser: converts user YAML to on-chain GroupSpec/ResourceSpec |
make/ | Sub-Makefiles for lint, test, codegen, release, tools |
upgrades/ | Chain upgrade handlers registered into AkashApp |
tests/ | End-to-end and upgrade integration tests |
_build/ | Dockerfiles and build output staging |
script/ | Shell helpers for CI, release checks, upgrade orchestration |
For the full directory walkthrough see Repository Structure. For build system details see Build System and Release.
Sources: README.md86-110 Makefile1-80 go.mod1-51
The diagram below maps natural-language system names to the actual code packages and types.
Top-Level Component Map
Sources: go.mod53-84 Makefile42-54 README.md36-38
| Component | Library / Package | Notes |
|---|---|---|
| Blockchain framework | github.com/cosmos/cosmos-sdk → Akash fork github.com/akash-network/cosmos-sdk | v0.53.3 upstream, v0.53.5-akash.1 fork |
| Consensus engine | github.com/cometbft/cometbft → Akash fork github.com/akash-network/cometbft | v0.38.21 upstream, v0.38.21-akash.1 fork |
| IBC | github.com/cosmos/ibc-go/v10 | v10.3.0 standard upstream |
| Protobuf | github.com/cosmos/gogoproto → Akash fork github.com/akash-network/gogoproto | v1.7.0-akash.2 fork |
| CLI framework | github.com/spf13/cobra | Command structure and execution |
| Configuration | github.com/spf13/viper | Config file loading and flag binding |
| Key-value store | cosmossdk.io/store, github.com/cosmos/cosmos-db | Pebble / LevelDB backends |
| Collections / indexes | cosmossdk.io/collections | Used in market/deployment queriers |
| Kubernetes client | k8s.io/api, k8s.io/apimachinery | Provider-side workload management |
| Cryptography | go.step.sm/crypto | TLS certificate handling in x/cert |
| REST/gRPC gateway | github.com/grpc-ecosystem/grpc-gateway | Serves REST API from gRPC definitions |
| Logging | github.com/rs/zerolog | Structured logging via custom wrapper |
Sources: go.mod5-51 go.mod53-84 go.mod86-297
Akash maintains forks of several upstream libraries. The replace directives in go.mod53-84 wire these in transparently. This allows Akash-specific patches and customizations while maintaining compatibility with the broader Cosmos ecosystem.
Fork Dependency Graph
Key Fork Reasons:
Sources: go.mod53-84
The akash binary is designed to operate in two distinct modes that can run on the same machine or separately:
1. Validator / Full Node mode
Runs AkashApp backed by CometBFT. Processes blocks, validates transactions, and maintains chain state. The key entry points are:
NewRootCmd() creates the root CLI commandNewApp() constructor initializes AkashApp (extends baseapp.BaseApp)InitChainer() processes genesis stateBeginBlocker() and EndBlocker() execute module logic per block26656 (P2P), 26657 (RPC), 26658 (ABCI)2. Provider Daemon mode
Runs the off-chain provider services. Watches on-chain events, bids on orders, and manages Kubernetes workloads. Key packages:
provider/bidengine/ — Service that watches x/market orders and submits bidsprovider/cluster/kube/ — Kubernetes Client that creates and manages workload resourcesprovider/manifest/ — Handler that receives and validates deployment manifests from tenantsFor deep dives, see Core Application Architecture and Provider Infrastructure.
Sources: cmd/akash/cmd/root.go29-131 app/app.go92-262 README.md36-38
| Branch | Purpose | Minor version parity |
|---|---|---|
main | Active development, new features | Odd (e.g., v0.9.x, unstable) |
mainnet/main | Current stable release | Even (e.g., v0.8.x, stable) |
The IS_STABLE, IS_PREREL, and IS_MAINNET flags in the Makefile Makefile23-36 encode this convention into the build and release system. See Build System and Release for how these flags affect artifact naming and release workflows.
Sources: README.md27-31 Makefile23-36
| OS | Architecture | Status |
|---|---|---|
| Linux | amd64 | ✅ Supported |
| Linux | arm64 | ✅ Supported |
| macOS | amd64 | ✅ Supported |
| macOS | arm64 | ✅ Supported |
| Windows | amd64 | ⚠️ Experimental |
Sources: README.md56-65
