deploy-ability

Programmatic deployment library for KADI - Deploy applications to Akash Network, local Docker, or other platforms with a delightful TypeScript API

Why deploy-ability?

deploy-ability extracts the core deployment logic from kadi-deploy into a pure TypeScript library with zero CLI dependencies. This enables:

Programmatic Deployments - Use from Node.js, APIs, agents, anywhere Type-Safe - Complete TypeScript support with zero any types Delightful API - Simple for common tasks, powerful for advanced use cases Flexible Wallet Support - Human approval (WalletConnect) or autonomous signing (agents) Autonomous Mode - Fully automated deployments with secure secrets integration Well-Documented - Comprehensive JSDoc with IntelliSense Production-Ready - Handles Akash Network complexity elegantly

Before: kadi-deploy (CLI Only)

# Can only deploy via CLI
kadi deploy --profile production

After: deploy-ability (Programmatic!)

import { deployToAkash } from 'deploy-ability';

// Deploy from your code!
const result = await deployToAkash({
  projectRoot: process.cwd(),
  profile: 'production',
  network: 'mainnet'
});

console.log(`Deployed! DSEQ: ${result.dseq}`);

Architecture

The Big Picture

graph TD
    subgraph "Core Library Layer"
        DA[deploy-ability]
        DA --> AK[Akash Deployment]
        DA --> LC[Local Deployment]
        DA --> WL[Wallet Management]
        DA --> CT[Certificate Management]
        DA --> MN[Monitoring & Queries]
    end

    subgraph "CLI Layer"
        CLI[kadi deploy command]
        KD[kadi-deploy plugin]
        CLI --> KD
        KD --> DA
    end

    subgraph "Programmatic Usage"
        AG[Custom Agents]
        SC[Scripts]
        API[API Servers]
        CI[CI/CD Pipelines]

        AG --> DA
        SC --> DA
        API --> DA
        CI --> DA
    end

    style DA fill:#6c6,stroke:#333,stroke-width:3px
    style KD fill:#69f,stroke:#333

Key Benefits:

• Single Source of Truth - One library, many entry points
• Pluggable - CLI, programmatic, or custom integrations
• Reusable - Share deployment logic across your entire stack
• Testable - Core logic independent of CLI

Deployment Flow (Akash Network)

sequenceDiagram
    participant User as Your Code
    participant DA as deploy-ability
    participant Wallet as Wallet/Signer
    participant Akash as Akash Blockchain
    participant Provider as Akash Provider

    User->>DA: deployToAkash(options)

    Note over DA,Wallet: Step 1: Wallet Connection
    DA->>Wallet: Connect (WalletConnect or Signer)
    Wallet-->>DA: WalletContext with signer

    Note over DA,Akash: Step 2: Certificate Setup
    DA->>Akash: Query/Create mTLS certificate
    Akash-->>DA: Certificate for provider communication

    Note over DA,Akash: Step 3: Create Deployment
    DA->>Wallet: Sign deployment transaction
    Wallet-->>DA: Signed transaction
    DA->>Akash: Broadcast deployment
    Akash-->>DA: DSEQ (deployment ID)

    Note over DA,Akash: Step 4: Wait for Bids
    DA->>Akash: Query bids from providers
    Akash-->>DA: Provider bids

    Note over DA,Akash: Step 5: Create Lease
    DA->>Wallet: Sign lease transaction
    Wallet-->>DA: Signed transaction
    DA->>Akash: Accept bid, create lease

    Note over DA,Provider: Step 6: Send Manifest
    DA->>Provider: Send deployment manifest (mTLS)
    Provider-->>DA: Manifest accepted

    Note over DA,Provider: Step 7: Monitor Deployment
    DA->>Provider: Poll container status
    Provider-->>DA: Containers running!

    DA-->>User: DeploymentResult { dseq, provider, endpoints }

Installation

npm install deploy-ability

Requirements:

• Node.js >= 18
• TypeScript >= 5.0 (optional, but recommended)

Quick Start

Deploy to Akash Network

import { deployToAkash } from 'deploy-ability';

const result = await deployToAkash({
  projectRoot: process.cwd(),
  profile: 'production',
  network: 'mainnet'
});

if (result.success) {
  console.log(`Deployed! DSEQ: ${result.data.dseq}`);
  console.log(`Provider: ${result.data.providerUri}`);
  console.log(`Endpoints:`, result.data.endpoints);
}

Autonomous Deployment (Agent-Controlled)

For fully automated deployments with secrets integration:

import { createSecretsProvider, deployToAkash } from 'deploy-ability';

// In a KADI agent:
const secrets = createSecretsProvider(this.secrets);

const result = await deployToAkash({
  autonomous: { secrets, bidStrategy: 'cheapest' },
  projectRoot: process.cwd(),
  profile: 'production',
  network: 'mainnet',
});

if (result.success) {
  console.log(`Deployed! DSEQ: ${result.data.dseq}`);
}

See Autonomous Deployment with Secrets Integration for full details.

Deploy to Local Docker

import { deployToLocal } from 'deploy-ability';

const result = await deployToLocal({
  projectRoot: process.cwd(),
  profile: 'local-dev',
  engine: 'docker'
});

if (result.success) {
  console.log('Deployed locally!');
  console.log('Services:', result.data.services);
}

Core Concepts

Storage Configuration

Understand the difference between memory (RAM), ephemeralStorage (temporary disk), and persistentVolumes (permanent disk) when configuring your deployments.

Quick summary:

• memory: Application runtime RAM (cleared on crash)
• ephemeralStorage: Container root filesystem (cleared on restart)
• persistentVolumes: Data that survives restarts (databases, uploads, models)

Read the full Storage Configuration Guide →

Placement Attributes

Control where your deployment runs geographically using placement attributes like region, datacenter type, timezone, and country.

Common use cases:

• Data residency (GDPR compliance)
• Latency optimization (deploy close to users)
• Infrastructure quality (datacenter vs home providers)

Read the full Placement Attributes Guide →

Understanding Signers

A signer is an interface that can sign blockchain transactions without exposing private keys. Think of it as a secure API to your wallet.

Two wallet patterns:

1. Human Approval (WalletConnect) - User scans QR code and approves each transaction 2. Autonomous Signing (Agents) - Agent has signer and signs automatically

// Signer interface (simplified)
interface OfflineSigner {
  getAccounts(): Promise<Account[]>;
  signDirect(address: string, signDoc: SignDoc): Promise<Signature>;
}

Why "Offline"? The term "OfflineSigner" from Cosmos means the private keys stay in the wallet (hardware or software) and never travel over the network. It can sign "offline" without broadcasting.

Basic Usage

Human Users (WalletConnect)

For applications where users approve deployments from their mobile Keplr wallet:

import { connectWallet, deployToAkash } from 'deploy-ability';
import QRCode from 'qrcode-terminal';

// Step 1: Connect wallet via WalletConnect
const walletResult = await connectWallet(
  'your-walletconnect-project-id',
  'mainnet',
  {
    onUriGenerated: (uri) => {
      QRCode.generate(uri, { small: true });
      console.log('Scan this QR code with Keplr mobile');
    },
    timeoutMs: 120000 // 2 minutes
  }
);

if (!walletResult.success) {
  console.error('Connection failed:', walletResult.error.message);
  process.exit(1);
}

// Step 2: Deploy (user approves each transaction on their phone)
const result = await deployToAkash({
  wallet: walletResult.data,
  projectRoot: './my-app',
  profile: 'production',
  network: 'mainnet'
});

if (result.success) {
  console.log(`Deployed! DSEQ: ${result.data.dseq}`);
}

Agent-Controlled Wallets

For autonomous agents that deploy without human interaction:

import { createWalletContextFromSigner, deployToAkash } from 'deploy-ability';
import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';

class SelfDeployingAgent {
  private signer: OfflineSigner;

  async initialize() {
    // Agent loads its OWN mnemonic from encrypted storage
    const mnemonic = await this.secrets.getEncryptedMnemonic();

    // Create signer from mnemonic
    this.signer = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic, {
      prefix: 'akash'
    });
  }

  async deploySelf() {
    // Create wallet context from agent's signer
    const walletResult = await createWalletContextFromSigner(
      this.signer,
      'mainnet'
    );

    if (!walletResult.success) {
      throw new Error(`Wallet setup failed: ${walletResult.error.message}`);
    }

    // Deploy autonomously (no human approval needed!)
    const result = await deployToAkash({
      wallet: walletResult.data,
      projectRoot: __dirname,
      profile: 'production',
      network: 'mainnet'
    });

    if (result.success) {
      console.log(`Self-deployed! DSEQ: ${result.data.dseq}`);
    }
  }
}

Security Warning: Only use your OWN mnemonic for agent wallets! Never give your mnemonic to third-party agents.

Autonomous Deployment with Secrets Integration

For fully automated deployments, deploy-ability integrates with KADI's secret-ability to securely retrieve wallet mnemonics from encrypted vaults. This enables agents to deploy without any user interaction while keeping secrets secure.

How It Works

sequenceDiagram
    participant Agent as KADI Agent
    participant Secrets as secret-ability
    participant Keychain as OS Keychain
    participant Deploy as deploy-ability
    participant Akash as Akash Network

    Agent->>Secrets: Get mnemonic from vault
    Secrets->>Keychain: Get master key
    Keychain-->>Secrets: Master key
    Secrets-->>Agent: Decrypted mnemonic
    Agent->>Deploy: deployToAkash({ autonomous: { secrets } })
    Deploy->>Akash: Create deployment (auto-sign)
    Akash-->>Deploy: Deployment result
    Deploy-->>Agent: Success!

Vault Configuration

Secrets are stored in a global vault at the machine level:

| Setting | Value | |---------|-------| | Config Path | ~/.kadi/secrets/config.toml | | Vault Name | global | | Vault Type | age (ChaCha20-Poly1305 encryption) | | Master Key | Stored in OS Keychain (macOS Keychain, GNOME Keyring, etc.) |

Secret Keys

| Key | Description | |-----|-------------| | AKASH_WALLET | BIP39 mnemonic phrase (12 or 24 words) | | akash-tls-certificate | Cached TLS certificate for provider communication | | akash-wallet-password | Optional BIP39 passphrase |

Setup: Store Your Mnemonic

Before using autonomous deployment, store your mnemonic in the global vault:

# Store Akash wallet mnemonic (encrypted, OS keychain protects master key)
kadi secret set AKASH_WALLET "your twelve or twenty four word mnemonic phrase here" -v global

If the global vault doesn't exist yet:

# Create the global vault at ~/.kadi/secrets/config.toml (one-time)
kadi secret create global -g

Or programmatically with secret-ability:

// 1. Create the global vault (one-time)
await secrets.invoke('config.createVault', {
  configPath: '~/.kadi/secrets/config.toml',
  name: 'global',
  type: 'age'
});

// 2. Store the mnemonic
await secrets.invoke('set', {
  configPath: '~/.kadi/secrets/config.toml',
  vault: 'global',
  key: 'AKASH_WALLET',
  value: 'your 12 or 24 word mnemonic phrase here'
});

Usage: Autonomous Deployment

Option 1: Using createSecretsProvider (Recommended)

Integrates directly with KADI's secret-ability:

import { 
  createSecretsProvider, 
  deployToAkash 
} from 'deploy-ability';

// In a KADI agent context:
class DeploymentAgent {
  async deploy(profile: string) {
    // Create secrets provider from secret-ability client
    const secrets = createSecretsProvider(this.secrets);

    // Deploy autonomously - no user interaction needed!
    const result = await deployToAkash({
      autonomous: {
        secrets,
        bidStrategy: 'cheapest',  // or 'most-reliable'
      },
      projectRoot: process.cwd(),
      profile,
      network: 'mainnet',
    });

    if (result.success) {
      console.log(`Deployed! DSEQ: ${result.data.dseq}`);
      console.log(`Provider: ${result.data.providerUri}`);
    }

    return result;
  }
}

Option 2: Using createSimpleMnemonicProvider (Testing)

For testing or when secret-ability is not available:

import { 
  createSimpleMnemonicProvider, 
  deployToAkash 
} from 'deploy-ability';

// ⚠️ For testing only - mnemonic stored in memory
const secrets = createSimpleMnemonicProvider(
  'test test test test test test test test test test test junk'
);

const result = await deployToAkash({
  autonomous: {
    secrets,
    bidStrategy: 'cheapest',
  },
  projectRoot: './my-app',
  profile: 'production',
  network: 'testnet',  // Use testnet for testing!
});

Option 3: Custom SecretsProvider

Implement the SecretsProvider interface for custom secret backends:

import { deployToAkash, SecretsProvider } from 'deploy-ability';

// Custom provider (e.g., AWS Secrets Manager, HashiCorp Vault)
const customSecrets: SecretsProvider = {
  async getMnemonic() {
    // Fetch from your secret backend
    return await mySecretManager.getSecret('akash-wallet-mnemonic');
  },

  async getCertificate() {
    // Optional: return cached certificate
    const cert = await mySecretManager.getSecret('akash-certificate');
    return cert ? JSON.parse(cert) : null;
  },

  async storeCertificate(cert) {
    // Optional: cache the certificate
    await mySecretManager.setSecret('akash-certificate', JSON.stringify(cert));
  },
};

const result = await deployToAkash({
  autonomous: { secrets: customSecrets, bidStrategy: 'cheapest' },
  projectRoot: './my-app',
  profile: 'production',
  network: 'mainnet',
});

Bid Selection Strategies

When deploying autonomously, you must specify a bid selection strategy:

| Strategy | Description | |----------|-------------| | 'cheapest' | Select the lowest price bid | | 'most-reliable' | Select the bid with highest provider uptime | | 'balanced' | Balance between price and provider reliability |

You can also add filters:

autonomous: {
  secrets,
  bidStrategy: 'cheapest',
  bidFilter: {
    maxPricePerMonth: { uakt: 5_000_000 },  // Max 5 AKT/month
    requireAudited: true,                    // Only audited providers
    requireOnline: true,                     // Only reachable providers (default: true)
    minUptime: { value: 0.95, period: '7d' }, // 95% uptime over 7 days
  },
}

Note: requireOnline defaults to true for all strategies, filtering out providers that fail a reachability pre-check before lease creation. Set requireOnline: false to disable this.

Provider Resilience

Autonomous deployments include built-in provider resilience to handle intermittent provider connectivity issues:

• Reachability Pre-Check — Before committing to a lease, the deployer verifies the provider is reachable via an HTTPS /status probe on port 8443.
• Automatic Retry — If manifest delivery fails with a PROVIDER_UNREACHABLE error, the deployer retries (with exponential back-off) before giving up on that provider.
• Provider Fallback — Bids are ranked, and if the top provider is unreachable, the deployer automatically falls back to the next-best bid (up to 3 attempts).
• Escrow Cleanup — If all provider attempts fail, any created lease is closed to prevent AKT escrow leaks.

This means transient provider outages no longer cause hard deployment failures — the system finds an available provider automatically.

Exported Constants

For programmatic access to configuration:

import {
  AKASH_VAULT_NAME,      // 'global'
  GLOBAL_CONFIG_PATH,    // '~/.kadi/secrets/config.toml'
  AKASH_SECRET_KEYS,     // { WALLET_MNEMONIC: 'AKASH_WALLET', ... }
} from 'deploy-ability';

Security Model

1. Encrypted at Rest: Secrets are encrypted with ChaCha20-Poly1305 in config.toml
2. Master Key in Keychain: The encryption key is stored in the OS keychain (never in files)
3. No Plaintext: Mnemonics are never written to disk in plaintext
4. Per-Machine: Secrets are tied to the machine's keychain - can't be copied

Configuration (config.yml)

deploy-ability resolves infrastructure settings from config.yml using walk-up discovery (searching from CWD up through parent directories) with a global fallback at ~/.kadi/config.yml.

Config Sections

deploy: section — deployment-specific settings:

deploy:
  registry_port: 3000            # Local registry port for image pushing
  container_engine: docker       # docker | podman
  auto_shutdown: true            # Shut down registry after deploy
  registry_duration: 600000      # Registry timeout in ms (10 min)

tunnel: section — tunnel infrastructure (used when deploying local images to Akash):

tunnel:
  server_addr: broker.kadi.build
  tunnel_domain: tunnel.kadi.build
  server_port: 7000
  ssh_port: 2200
  mode: frpc
  transport: wss
  wss_control_host: tunnel-control.kadi.build

See tunnel-services config.sample.yml and deploy-ability config.sample.yml for full reference.

All values have sensible defaults — you only need config.yml to override something.

Secrets Setup

| Secret | Vault | Scope | Setup Command | |--------|-------|-------|---------------| | AKASH_WALLET | global | Global (~/.kadi/) | kadi secret set AKASH_WALLET "mnemonic..." -v global | | KADI_TUNNEL_TOKEN | tunnel | Global (~/.kadi/) | kadi secret set KADI_TUNNEL_TOKEN "token" -v tunnel | | NGROK_AUTH_TOKEN | tunnel | Global (~/.kadi/) | kadi secret set NGROK_AUTH_TOKEN "token" -v tunnel |

Global vs Project — Infrastructure secrets (wallet, tunnel tokens) live at ~/.kadi/secrets/config.toml so they're available from any project directory. Agent-specific secrets (API keys, DB passwords) stay in the project-level secrets.toml.

# One-time setup for the tunnel vault at global level
kadi secret create tunnel -g
kadi secret set KADI_TUNNEL_TOKEN "your-token" -v tunnel

Resolution Priority

Each setting resolves from highest to lowest priority:

1. Function arguments — options passed to deployToAkash() / deployToLocal()
2. Environment variables — KADI_TUNNEL_SERVER, KADI_TUNNEL_TOKEN, etc.
3. Encrypted vault — secrets.toml via secret-ability
4. Project config.yml — walk-up from CWD
5. Global ~/.kadi/config.yml — machine-wide defaults
6. Built-in defaults

Error Handling

deploy-ability uses a Result type pattern for predictable error handling:

type Result<T, E> =
  | { success: true; data: T }
  | { success: false; error: E };

Pattern 1: Check Success

const result = await deployToAkash(options);

if (result.success) {
  console.log('Deployed:', result.data.dseq);
} else {
  console.error('Failed:', result.error.message);
  console.error('Code:', result.error.code);
  console.error('Context:', result.error.context);
}

Pattern 2: Throw on Failure

const result = await deployToAkash(options);

if (!result.success) {
  throw result.error; // DeploymentError
}

const deployment = result.data; // TypeScript knows this is safe!

Common Error Codes

| Code | Type | Meaning | |------|------|---------| | WALLET_NOT_FOUND | WalletError | Keplr not installed | | CONNECTION_REJECTED | WalletError | User rejected connection | | APPROVAL_TIMEOUT | WalletError | User didn't approve in time | | INSUFFICIENT_FUNDS | WalletError | Not enough AKT for deployment | | CERTIFICATE_NOT_FOUND | CertificateError | No certificate on-chain | | CERTIFICATE_EXPIRED | CertificateError | Certificate needs regeneration | | NO_BIDS_RECEIVED | DeploymentError | No providers bid on deployment | | PROVIDER_UNREACHABLE | ProviderError | Provider failed reachability check or manifest delivery | | ALL_PROVIDERS_UNREACHABLE | DeploymentError | All ranked providers were unreachable; leases cleaned up | | RPC_ERROR | DeploymentError | Blockchain RPC failure |

Security Best Practices

Safe Patterns

1. WalletConnect for Third-Party Services

// GOOD - User approves each transaction
const wallet = await connectWallet(projectId, 'mainnet', { ... });
await thirdPartyService.deploy({ wallet: wallet.data });
// User sees and approves every transaction on their phone

2. Agent Uses Its Own Wallet

// GOOD - Agent uses its own funds
class DeploymentAgent {
  async deploy(userProject) {
    const mnemonic = await this.secrets.getOwnMnemonic(); // Agent's wallet!
    const wallet = await createWalletFromMnemonic(mnemonic, 'mainnet');
    await deployToAkash({ wallet: wallet.data, ...userProject });
    // Agent pays, user pays agent separately (credit card, etc.)
  }
}

3. CI/CD from Secure Secrets

// GOOD - Mnemonic in GitHub Secrets
const mnemonic = process.env.DEPLOYMENT_WALLET_MNEMONIC; // GitHub Secret
const wallet = await createWalletFromMnemonic(mnemonic, 'mainnet');

Dangerous Patterns

1. Never Give Mnemonic to Third Parties

// DANGEROUS - They can steal all your funds!
const thirdPartyAgent = new SomeoneElsesAgent();
await thirdPartyAgent.deploy({
  mnemonic: myMnemonic,  // They now control your wallet!
  project: './my-app'
});

2. Never Hardcode Mnemonics

// DANGEROUS - Committed to git!
const mnemonic = "word1 word2 word3..."; // In source code!

Migration from kadi-deploy

Before (kadi-deploy internals)

// Was never meant to be public API
import { AkashDeployer } from 'kadi-deploy/src/targets/akash/akash.js';

After (deploy-ability)

// Clean public API
import { deployToAkash } from 'deploy-ability';

Migration Steps

1. Replace imports

   // Before
   import { checkWallet } from 'kadi-deploy/src/targets/akash/wallet.js';
   
   // After
   import { connectWallet } from 'deploy-ability';

2. Update function signatures

   // Before (kadi-deploy - CLI context required)
   const wallet = await checkWallet(logger, 'mainnet', projectId);
   
   // After (deploy-ability - pure functions)
   const wallet = await connectWallet(projectId, 'mainnet', {
     onUriGenerated: (uri) => console.log(uri)
   });

3. Handle Result types

   // deploy-ability uses Result<T, E> pattern
   if (!wallet.success) {
     console.error(wallet.error.message);
     return;
   }
   
   const myWallet = wallet.data;

Documentation

• Storage Configuration Guide - Understanding memory, ephemeral storage, and persistent volumes
• Placement Attributes Guide - Geographic placement and provider selection
• Detailed Examples - CI/CD integration, API servers, and more
• API Reference - Complete TypeScript API documentation

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Changelog

0.0.16

• Fix: Escrow account parsing updated for chain-sdk v1 Account type. The escrowAccount field from QueryDeploymentResponse now uses the v1 structure (Account → AccountState with funds: Balance[], transferred: DecCoin[]) instead of the old v1beta3 flat format. This fixes escrow balance/transferred/time-left displaying as zero in the deploy-agent dashboard.
• Added findCoinAmount() helper for extracting amounts from coin arrays by denom.
• Legacy v1beta3 escrow format retained as fallback.

0.0.15

• Single SDK instance optimization, autonomous deployment support, secrets provider integration.

License

MIT © KADI Framework

Resources

• Akash Network: https://akash.network/
• Akash Console: https://console.akash.network/
• KADI Framework: https://github.com/kadi-framework
• Keplr Wallet: https://www.keplr.app/
• WalletConnect: https://walletconnect.com/
• CosmJS Documentation: https://cosmos.github.io/cosmjs/

Built with ❤️ by the KADI team