How the Akash Console Enables Docker Container Deployment on the Akash Network

The Akash Console converts a user-supplied Docker image into a running container on the Akash Network by validating the image reference, parsing it into a Stack Definition Language (SDL) manifest, constructing a signed MsgCreateDeployment transaction, and coordinating with providers to pull and execute the workload.

The Akash Console serves as the primary web interface for deploying containerized workloads on the Akash Network, transforming simple Docker image inputs into fully orchestrated blockchain deployments. By bridging the SDL Builder UI with the Akash blockchain's provider marketplace, the console eliminates manual manifest crafting while maintaining the decentralized, permissionless nature of the network. This article examines the complete technical pipeline—from client-side validation to provider manifest delivery—that enables seamless Docker container deployment on Akash.

SDL Builder: Capturing and Validating Docker Images

The deployment process begins in the SDL Builder interface, where users input a fully-qualified Docker image reference (e.g., nginx:1.21-alpine). According to the source code in apps/deploy-web/src/utils/templates.ts, the UI stores this value in the service.image field of the SDL template, ensuring the image is explicitly declared before any blockchain interaction occurs.

Before submission, the console enforces strict client-side validation using a comprehensive regex pattern defined in apps/deploy-web/src/types/sdlBuilder/sdlBuilder.ts. The VALID_IMAGE_NAME regex guarantees that users provide version-pinned, fully-qualified references rather than mutable tags, preventing deployment failures from ambiguous image resolutions.

const VALID_IMAGE_NAME =
  /^(?:(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])(?:(?:\.(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]))+)?(?::[0-9]+)?\/)?[a-z0-9]+(?:(?:(?:[._]|__|[-]*)[a-z0-9]+)+)?(?:\/[a-z0-9]+(?:(?:(?:[._]|__|[-]*)[a-z0-9]+)+)?)*(?::[a-zA-Z0-9_.-]+)?(?:@[a-zA-Z0-9_.:+-]+)?$/;

// Zod schema enforcement
image: z.string().min(1, { message: "Docker image name is required." })
      .refine(v => VALID_IMAGE_NAME.test(v), { message: "Invalid docker image name." })

This validation layer ensures that only properly formatted container references reach the backend, reducing failed transactions and provider pull errors.

SDL Service: Converting Definitions to Deployment Manifests

Once validated, the SDL document flows to the backend's SdlService (apps/api/src/deployment/services/sdl/sdl.service.ts), which parses the YAML structure into blockchain-compatible formats. The service extracts deployment groups containing resource requirements, placement constraints, and the Docker image reference through the getDeploymentGroups method.

Simultaneously, getManifest generates the v2 or v3 JSON manifest that providers will consume. This manifest includes the Docker image alongside compute profiles, storage allocations, and endpoint configurations. The service also calculates a manifest hash using getManifestVersion, creating a deterministic fingerprint that ensures providers receive the exact container specification intended by the user.

# Example SDL structure accepted by the console

version: "2.0"
services:
  web:
    image: nginx:1.21-alpine  # Validated Docker image

    expose:
      - port: 80
        as: 80
        to:
          - global: true
profiles:
  compute:
    web:
      resources:
        cpu: { units: 0.5 }
        memory: { size: 512Mi }
        storage: { size: 512Mi }

Transaction Pipeline: Building and Broadcasting Deployment Messages

With the manifest prepared, the console constructs the blockchain transaction through a coordinated sequence of services. First, TransactionMessageData.getCreateDeploymentMsg (located in apps/deploy-web/src/utils/TransactionMessageData.ts) assembles the protobuf MsgCreateDeployment structure, embedding the deployment ID, resource groups, manifest hash, and escrow deposit.

The RpcMessageService (apps/api/src/billing/services/rpc-message-service/rpc-message.service.ts) acts as a thin wrapper, forwarding these parameters to the protobuf builder at lines 138-149. Finally, the DeploymentWriterService (apps/api/src/deployment/services/deployment-writer/deployment-writer.service.ts) orchestrates the on-chain submission:

// Inside DeploymentWriterService.create()
const wallet = await this.walletReaderService.getWalletByUserId(userId);
const groups = this.sdlService.getDeploymentGroups(sdl, "beta3");
const manifest = this.sdlService.getManifest(sdl, "beta3", true);

const message = this.rpcMessageService.getCreateDeploymentMsg({
  owner: wallet.address,
  dseq: await this.blockHttpService.getCurrentHeight(),
  groups,
  hash: await this.sdlService.getManifestVersion(sdl, "beta3"),
  denom: this.billingConfig.get("DEPLOYMENT_GRANT_DENOM"),
  amount: denomToUdenom(deposit)
});

const result = await this.signerService.executeDerivedDecodedTxByUserId(wallet.userId, [message]);

The executeDerivedDecodedTxByUserId method handles wallet signing through the ManagedSignerService and broadcasts the transaction to Akash validators, establishing the deployment on-chain at a specific block height (dseq).

Provider Execution and Status Monitoring

Once the transaction is confirmed, the DeploymentWriterService invokes sendManifestToProviders (lines 42-60 of the same file) to push the manifest to selected providers via the ProviderService. This gRPC delivery mechanism transmits the container specification—including the Docker image reference—to provider nodes, which subsequently execute docker pull and instantiate the container within the leased resources.

The console maintains real-time visibility into this process through the deployments router at apps/api/src/deployment/routes/deployments/deployments.router.ts. The frontend polls GET /v1/deployments/:dseq to retrieve lease status, container logs, and provider acceptance confirmations, displaying a "Deployment active" badge once the provider successfully pulls and starts the Docker image.

Summary

• The Akash Console bridges user-friendly web interfaces with the Akash blockchain, accepting Docker image references through the SDL Builder UI.
• Strict validation occurs client-side via regex patterns in sdlBuilder.ts, ensuring only properly formatted, version-pinned images proceed to deployment.
• The SdlService transforms YAML definitions into JSON manifests and deployment groups, calculating cryptographic hashes that guarantee manifest integrity.
• Transaction construction combines TransactionMessageData and RpcMessageService to build signed MsgCreateDeployment messages containing resource requirements and escrow deposits.
• Provider orchestration happens automatically through sendManifestToProviders, which delivers container specifications to provider nodes for Docker execution.
• Real-time monitoring via the deployments router keeps users informed of lease status and container lifecycle events.

Frequently Asked Questions

What Docker image formats does the Akash Console support?

The Akash Console supports fully-qualified Docker image references including registry hostnames, repository paths, tags, and digests. According to the validation logic in apps/deploy-web/src/types/sdlBuilder/sdlBuilder.ts, the console requires version-pinned references (explicit tags or SHA digests) and validates against the Docker distribution reference specification regex to prevent deployment failures from mutable tags.

How does the Akash Console validate Docker images before deployment?

Client-side validation occurs through a strict regex pattern (VALID_IMAGE_NAME) enforced by Zod schema validation in the frontend code. This ensures images include proper registry prefixes, repository names, and version identifiers before the SDL ever reaches the backend API, preventing invalid transactions from consuming blockchain fees.

What happens after the deployment transaction is broadcast to the blockchain?

Once broadcast via executeDerivedDecodedTxByUserId in the DeploymentWriterService, the transaction is confirmed on the Akash chain and assigned a unique deployment sequence number (dseq). The service then immediately calls sendManifestToProviders to transmit the container specification to selected providers, which pull the Docker image and start the container in a resource lease.

Can I deploy private Docker images through the Akash Console?

While the console validates image name formats through sdlBuilder.ts, private registry authentication requires additional configuration within the SDL's service definition, typically via registry credential secrets. The console's templates.ts provides the structural framework for declaring these credentials, though users must ensure their SDL includes proper authentication tokens for private repository access.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}