kadi-deploy 0.19.0 → 0.19.3

package/README.md

@@ -21,8 +21,13 @@ kadi install kadi-deploy
 | `kadi deploy` | Deploy using first available profile |
 | `kadi deploy --profile production` | Deploy using a specific profile |
 | `kadi deploy --autonomous` | Fully autonomous deployment (no human interaction) |
-| `kadi deploy --dry-run` | Preview deployment without executing || `kadi deploy down` | Tear down an active deployment |
+| `kadi deploy --dry-run` | Preview deployment without executing |
+| `kadi deploy list` | List all active deployments |
+| `kadi deploy list --json` | List deployments as JSON |
+| `kadi deploy down` | Tear down an active deployment |
 | `kadi deploy down --profile <name>` | Tear down a specific profile's deployment |
+| `kadi deploy down --instance <id>` | Tear down a specific instance by ID |
+| `kadi deploy down --label <label>` | Tear down a deployment by its label |
 | `kadi deploy down --autonomous` | Tear down Akash deployment without human interaction |
 | `kadi deploy down --yes` | Tear down without confirmation prompt |
 ---
@@ -60,6 +65,103 @@ That's it. For Akash Network deployment, see [Deploying to Akash](#deploying-to-
 
 ---
 
+## Configuration & Secrets
+
+`kadi deploy` uses three configuration sources — **agent.json** for deploy profiles, **config.yml** for infrastructure settings, and **encrypted vaults** for secrets. No `.env` files needed.
+
+### Where Things Live
+
+| What | Where | Purpose |
+|------|-------|---------|
+| Deploy profiles | `agent.json` (project root) | Service definitions, target, network, secrets delivery |
+| Infrastructure config | `config.yml` (project or ancestor) | Tunnel server, registry port, container engine |
+| Global infrastructure config | `~/.kadi/config.yml` | Machine-wide defaults (shared across all projects) |
+| Project secrets | `secrets.toml` (project or ancestor) | Agent-specific API keys, DB passwords — encrypted |
+| Infrastructure secrets | `~/.kadi/secrets/config.toml` | Tunnel tokens, Akash wallet — encrypted, machine-scoped |
+
+Configuration resolves with walk-up discovery — `kadi deploy` searches from your CWD upward through parent directories until it finds `config.yml` or `secrets.toml`. Global `~/.kadi/` is the final fallback.
+
+### Setting Up Secrets
+
+**Tunnel token** (required for deploying local images to Akash):
+
+```bash
+# Create the global tunnel vault (one-time)
+kadi secret create tunnel -g
+
+# Store the token
+kadi secret set KADI_TUNNEL_TOKEN "your-token" -v tunnel
+```
+
+The tunnel vault lives at `~/.kadi/secrets/config.toml` (user-level) so it works from any project directory.
+
+**Akash wallet** (required for autonomous deployment):
+
+```bash
+# Store in the global vault (already exists by default)
+kadi secret set AKASH_WALLET "your twelve or twenty four word mnemonic" -v global
+```
+
+**Deployment secrets** (shared with deployed containers):
+
+```bash
+# Create a project-level vault for your agent
+kadi secret create my-agent
+
+# Store secrets the deployed container will receive
+kadi secret set API_KEY "sk-..." -v my-agent
+kadi secret set DB_URL "postgres://..." -v my-agent
+```
+
+Then reference it in your deploy profile's `secrets` block (see [Sharing Secrets with Deployments](#sharing-secrets-with-deployments)).
+
+### Setting Up config.yml
+
+Create a `config.yml` in your project root (or any ancestor directory):
+
+```yaml
+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
+
+deploy:
+  registry_port: 3000
+  container_engine: docker        # docker | podman
+  auto_shutdown: true
+  registry_duration: 600000       # 10 minutes
+```
+
+All values have sensible defaults — you only need `config.yml` if you want to override something. See `config.sample.yml` in [tunnel-services](../abilities/tunnel-services/config.sample.yml) and [deploy-ability](../abilities/deploy-ability/config.sample.yml) for full reference.
+
+### Resolution Priority
+
+Each setting resolves independently from highest to lowest priority:
+
+1. **CLI flags** — `--engine podman`, `--network testnet`
+2. **Environment variables** — `KADI_TUNNEL_SERVER`, `KADI_TUNNEL_TOKEN`
+3. **Encrypted vault** — `secrets.toml` via `kadi secret`
+4. **Project config.yml** — walk-up from CWD
+5. **Global `~/.kadi/config.yml`** — machine-wide defaults
+6. **Built-in defaults** — e.g. `docker`, `broker.kadi.build`
+
+### Project-Level vs Global (User-Level)
+
+| Setting | Scope | Location |
+|---------|-------|----------|
+| `KADI_TUNNEL_TOKEN` | **Global** — same token for all projects | `~/.kadi/secrets/config.toml` → `tunnel` vault |
+| `AKASH_WALLET` | **Global** — your wallet, not project-specific | `~/.kadi/secrets/config.toml` → `global` vault |
+| `tunnel:` config | **Global or Project** — usually same infrastructure | `~/.kadi/config.yml` or project `config.yml` |
+| `deploy:` config | **Project** — may differ per project | Project `config.yml` |
+| Agent secrets (API keys, DB creds) | **Project** — specific to one agent | Project `secrets.toml` → custom vault |
+| Deploy profiles | **Project** — specific to one agent | `agent.json` |
+
+---
+
 ## Deploying Locally
 
 Local deployment uses Docker or Podman to run your services via docker-compose.
@@ -94,6 +196,19 @@ kadi deploy --profile local
 | `network` | Docker network name (optional) |
 | `services` | Service definitions (see below) |
 
+### Container Engine Resolution
+
+The container engine is resolved using the following priority (highest wins):
+
+1. **CLI `--engine` flag** — explicit per-command override
+2. **Profile `engine`** — set in the deploy profile in `agent.json`
+3. **Global config `preferences.containerEngine`** — user default set via `kadi config set preferences.containerEngine podman`
+4. **Default** — `docker`
+
+This matches the resolution pattern used by `kadi broker`.
+
+When using Podman, compose commands automatically prefer `podman-compose` (the standalone Python tool) over `podman compose`, which avoids issues on systems where `podman compose` delegates to a broken Docker Desktop shim.
+
 ---
 
 ## Deploying to Akash
@@ -228,28 +343,92 @@ The entire flow completes without any human interaction.
 
 ---
 
+## Listing Active Deployments
+
+The `kadi deploy list` command (alias `kadi deploy ls`) shows all active deployments from the `.kadi-deploy.lock` file without needing to open it manually.
+
+```bash
+$ kadi deploy list
+
+Active Deployments (2)
+──────────────────────────────────────────────────────────────────────
+
+INSTANCE  PROFILE     TARGET  LABEL         DETAILS          DEPLOYED
+02f5      production  akash   broker-east   dseq=19234567    Mar 10, 2026, 02:15 PM
+a3f7      dev         local   —             engine=docker    Mar 11, 2026, 09:30 AM
+
+Use `kadi deploy down --instance <id>` or `kadi deploy down --label <label>` to tear down a deployment.
+```
+
+### List Flags
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --project <path>` | Path to project with `.kadi-deploy.lock` | Current directory |
+| `--profile <profile>` | Filter by profile name | Show all |
+| `--json` | Output as JSON (for scripting / automation) | `false` |
+| `--verbose` | Show additional details (provider address, services, network) | `false` |
+
+### JSON Output
+
+Use `--json` for machine-readable output, useful in scripts and CI pipelines:
+
+```bash
+$ kadi deploy list --json
+[
+  {
+    "instanceId": "02f5",
+    "profile": "production",
+    "target": "akash",
+    "label": "broker-east",
+    "deployedAt": "2026-03-10T14:15:00.000Z",
+    "dseq": 19234567,
+    "owner": "akash1abc...",
+    "provider": "akash1xyz...",
+    "providerUri": "https://provider.example.com",
+    "network": "mainnet"
+  }
+]
+```
+
+---
+
 ## Tearing Down Deployments
 
 The `kadi deploy down` command tears down an active deployment launched by `kadi deploy`. It works for both local (Docker/Podman) and Akash deployments.
 
 After a successful deployment, kadi-deploy writes a `.kadi-deploy.lock` file to the project root that records everything needed to tear it down. The lock file supports **multiple simultaneous deployments** — you can have a local dev deployment and an Akash production deployment active at the same time.
 
-### Multi-Profile Support
+### Multi-Instance Support
+
+Each deployment gets a unique 4-character instance ID (e.g. `a3f7`) and an optional human-readable label. Use `kadi deploy list` to see all active deployments.
 
-When multiple deployments are active:
+When multiple deployments are active, you can identify which one to tear down using `--profile`, `--instance`, or `--label`:
 
 ```bash
 # Specify which profile to tear down
 kadi deploy down --profile dev
 kadi deploy down --profile production
 
+# Tear down by instance ID (4-char hex shown in deploy output and `deploy list`)
+kadi deploy down --instance a3f7
+
+# Tear down by label (set during deploy with --label)
+kadi deploy down --label my-broker
+
 # If only one deployment is active, it's auto-selected
 kadi deploy down
 
-# If multiple are active and no --profile, you'll be prompted to choose
+# If multiple are active and no selector given, you'll be prompted to choose
 kadi deploy down --yes
 ```
 
+> **Tip:** When deploying, use `--label` to give your deployment a memorable name:
+> ```bash
+> kadi deploy --profile production --label broker-east
+> ```
+> Then tear it down easily: `kadi deploy down --label broker-east`
+
 ### Local Teardown
 
 ```bash
@@ -263,7 +442,7 @@ kadi deploy down --yes
 kadi deploy down --engine podman
 ```
 
-This runs `docker compose down --remove-orphans` (or `podman compose`) against the compose file recorded in the lock.
+This runs `docker compose down --remove-orphans` (or `podman-compose` for Podman) against the compose file recorded in the lock. Engine resolution follows the same priority as deploy (see [Container Engine Resolution](#container-engine-resolution)).
 
 ### Akash Teardown (Interactive)
 
@@ -297,7 +476,7 @@ kadi deploy down --autonomous --profile production
 
 The autonomous path skips all interactive prompts (confirmation and profile selection), reads the wallet mnemonic from the secrets vault (same as `kadi deploy --autonomous`), signs the close transaction directly, and refunds the remaining escrow to your wallet.
 
-> **Note:** If multiple deployments are active, `--autonomous` requires `--profile` to specify which one to tear down (it cannot prompt for selection).
+> **Note:** If multiple deployments are active, `--autonomous` requires `--profile`, `--instance`, or `--label` to specify which one to tear down (it cannot prompt for selection).
 
 ### Down Flags
 
@@ -305,6 +484,9 @@ The autonomous path skips all interactive prompts (confirmation and profile sele
 |------|-------------|----------|
 | `-p, --project <path>` | Path to project with `.kadi-deploy.lock` | Current directory |
 | `--profile <profile>` | Profile name to tear down (prompts if multiple; **required** in autonomous mode with multiple deployments) | Auto-select |
+| `--instance <id>` | Instance ID to tear down (4-char hex from deploy output or `deploy list`) | — |
+| `--label <label>` | Tear down the deployment matching this label | — |
+| `--all` | Tear down all active deployments | `false` |
 | `--engine <engine>` | Override container engine (`docker`/`podman`) | From lock file |
 | `--network <network>` | Override Akash network (`mainnet`/`testnet`) | From lock file |
 | `--autonomous` | No human interaction — skips confirmation, uses vault mnemonic for Akash | `false` |
@@ -312,25 +494,30 @@ The autonomous path skips all interactive prompts (confirmation and profile sele
 | `-y, --yes` | Skip confirmation prompt (implied by `--autonomous`) | `false` |
 | `--verbose` | Detailed output | `false` |
 
+**Resolution priority:** `--instance` > `--label` > `--all` > `--profile` > auto-select (single deployment) > interactive prompt.
+
 ### The Lock File
 
-The `.kadi-deploy.lock` file is written to the project root after every successful deployment. It uses a v2 format that supports multiple simultaneous deployments keyed by profile name:
+The `.kadi-deploy.lock` file is written to the project root after every successful deployment. It uses a v3 format that supports multiple simultaneous deployments — including multiple instances of the same profile — keyed by `{profile}:{instanceId}`:
 
 ```json
 {
-  "version": 2,
+  "version": 3,
   "deployments": {
-    "dev": {
+    "local:a3f7": {
+      "instanceId": "a3f7",
       "target": "local",
-      "profile": "dev",
+      "profile": "local",
       "deployedAt": "2026-02-25T12:00:00.000Z",
-      "local": { "composePath": "...", "engine": "docker", ... }
+      "local": { "composePath": "...", "engine": "docker", "...": "..." }
     },
-    "production": {
+    "akash:b9e2": {
+      "instanceId": "b9e2",
       "target": "akash",
-      "profile": "production",
+      "profile": "akash",
+      "label": "broker-east",
       "deployedAt": "2026-02-25T14:00:00.000Z",
-      "akash": { "dseq": 12345678, "owner": "akash1...", ... }
+      "akash": { "dseq": 12345678, "owner": "akash1...", "...": "..." }
     }
   }
 }
@@ -338,10 +525,14 @@ The `.kadi-deploy.lock` file is written to the project root after every successf
 
 Each entry contains:
 
+- **instanceId**: Unique 4-character hex identifier (e.g. `a3f7`)
+- **label**: Optional human-readable label set at deploy time with `--label`
 - **Local deployments**: compose file path, engine, network, service names, container IDs
 - **Akash deployments**: DSEQ, owner address, provider, network, gseq/oseq
 
-When you tear down a profile, only that entry is removed. The file is deleted entirely when the last deployment is removed. Existing v1 lock files (single deployment) are transparently migrated on read.
+Use `kadi deploy list` to view active deployments without opening the lock file.
+
+When you tear down a deployment, only that entry is removed. The file is deleted entirely when the last deployment is removed. Existing v1/v2 lock files are transparently migrated to v3 on read.
 
 It is safe to add `.kadi-deploy.lock` to `.gitignore`.
 
@@ -538,12 +729,26 @@ kadi deploy --auto-approve-secrets               # Works in interactive mode too
 kadi deploy --secret-timeout 120000              # 2 min timeout for secret handshake
 ```
 
+**List active deployments:**
+
+```bash
+kadi deploy list                                 # Table of all active deployments
+kadi deploy ls                                   # Alias for list
+kadi deploy list --json                          # Machine-readable JSON output
+kadi deploy list --verbose                       # Show provider, services, network details
+kadi deploy list --profile production            # Filter by profile
+```
+
 **Tear down deployments:**
 
 ```bash
 kadi deploy down                                 # Tear down active deployment
+kadi deploy down --label my-broker               # Tear down by label
+kadi deploy down --instance a3f7                 # Tear down by instance ID
+kadi deploy down --all                           # Tear down all deployments
 kadi deploy down --yes                           # Skip confirmation (interactive)
 kadi deploy down --autonomous                    # Fully non-interactive (skips confirmation + QR)
+kadi deploy down --autonomous --label prod-east  # Autonomous teardown by label
 kadi deploy down --autonomous --profile prod     # Required when multiple deployments active
 kadi deploy down --autonomous --secrets-vault v   # Akash: custom vault
 kadi deploy down --engine podman                 # Override container engine
@@ -587,3 +792,114 @@ kadi deploy --profile production --dry-run
 ```bash
 kadi deploy --profile production --verbose
 ```
+
+---
+
+## Migrating from .env to Vaults
+
+**As of kadi-deploy v0.19.0**, secrets are stored in encrypted vaults (`secrets.toml`) and config in `config.yml` — replacing the old `.env` file approach entirely. The `.env` fallback still works but is deprecated and will be removed in a future release.
+
+### Step 1: Update kadi-deploy
+
+```bash
+kadi install kadi-deploy
+```
+
+This pulls `kadi-deploy@0.19.1` (with `kadi-secret@0.11.1` and `secret-ability@0.9.2`).
+
+### Step 2: Move tunnel token to a global vault
+
+Previously you had a `.env` file (often inside `abilities/` or your project root) containing:
+
+```
+KADI_TUNNEL_TOKEN=your-token-here
+NGROK_AUTH_TOKEN=your-ngrok-token
+```
+
+Move these to an encrypted global vault:
+
+```bash
+# Create the tunnel vault at user level (~/.kadi/secrets/config.toml)
+kadi secret create tunnel -g
+
+# Copy your token value from the old .env file, then:
+kadi secret set KADI_TUNNEL_TOKEN "your-token-here" -v tunnel
+
+# If you used ngrok:
+kadi secret set NGROK_AUTH_TOKEN "your-ngrok-token" -v tunnel
+```
+
+The global (`-g`) vault lives at `~/.kadi/secrets/config.toml`, accessible from any project directory. You no longer need to copy `.env` files into ability folders.
+
+### Step 3: Move Akash wallet (autonomous deployments only)
+
+If you had `AKASH_WALLET` in a `.env` or environment variable:
+
+```bash
+# The 'global' vault likely already exists — if not:
+kadi secret create global -g
+
+# Store the mnemonic
+kadi secret set AKASH_WALLET "your twelve or twenty four word mnemonic" -v global
+```
+
+### Step 4: Create config.yml (optional)
+
+If you had non-secret settings in `.env` (tunnel server, ports, etc.), move them to `config.yml` in your project root:
+
+```yaml
+tunnel:
+  server_addr: broker.kadi.build
+  tunnel_domain: tunnel.kadi.build
+  transport: wss
+
+deploy:
+  container_engine: docker
+```
+
+All values have sensible defaults — you only need `config.yml` if you customized something.
+
+### Step 5: Clean up
+
+```bash
+# Delete the old .env file from your kadi abilities folder
+rm ~/.kadi/../abilities/.env  # or wherever your .env lived
+
+# Also remove from your project if you had one there
+rm /path/to/project/.env  # only if it only contained kadi tunnel/deploy secrets
+```
+
+### Step 6: Verify
+
+```bash
+# From any directory — should return your token
+kadi secret get KADI_TUNNEL_TOKEN -v tunnel
+
+# From an agent subdirectory — multi-level discovery finds the global vault
+cd agents/my-agent
+kadi secret get KADI_TUNNEL_TOKEN -v tunnel
+
+# Test a deploy
+kadi deploy --dry-run
+```
+
+### What changed
+
+| Before (.env) | After (vaults + config.yml) |
+|---------------|----------------------------|
+| Plaintext `.env` file in ability folder | Encrypted `secrets.toml` in `~/.kadi/` (age/ChaCha20-Poly1305) |
+| Copy `.env` into each ability that needs it | Global vault — one location, accessible everywhere |
+| Secrets and config mixed in one flat file | Secrets in vault, config in `config.yml` — separated |
+| No encryption, easy to leak | Encrypted at rest, master key in OS keychain |
+| Per-project only | Global (`~/.kadi/`) or per-project — your choice |
+
+### Backwards compatibility
+
+The `.env` fallback is still supported as a **tier-3 fallback** in `configResolver.js`:
+
+1. `process.env` (always wins)
+2. Encrypted vault (`secrets.toml`)
+3. `.env` file walk-up (deprecated — still works)
+4. `config.yml` (for non-secret settings)
+
+If you have an existing `.env` file, it will continue to work. But new setups should use vaults.

package/agent.json

@@ -1,13 +1,13 @@
 {
   "name": "kadi-deploy",
-  "version": "0.19.0",
+  "version": "0.19.3",
   "license": "MIT",
   "type": "plugin",
   "entrypoint": "dist/index.js",
   "commands": ["deploy"],
   "description": "CLI plugin that converts an agent's deploy spec into platform-specific artifacts (Akash SDL, Docker Compose, etc.) and orchestrates the deployment process.",
   "repo": "https://gitlab.com/humin-game-lab/kadi/kadi-deploy.git",
-  "lib": "https://gitlab.com/humin-game-lab/kadi/kadi-deploy/-/archive/v0.19.0/kadi-deploy-v0.19.0.zip",
+  "lib": "https://gitlab.com/humin-game-lab/kadi/kadi-deploy/-/archive/v0.19.3/kadi-deploy-v0.19.3.zip",
   "api": "http://127.0.0.1:8000",
   "brokers": {
     "local": "ws://127.0.0.1:8080",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kadi-deploy",
-  "version": "0.19.0",
+  "version": "0.19.3",
   "type": "module",
   "main": "index.js",
   "scripts": {

package/src/commands/deploy-local.ts

@@ -31,6 +31,7 @@ import { error as errorColor, warning, success as successColor, formatKeyValue,
 import type { DeploymentContext } from '../types.js';
 import type { Ora } from 'ora';
 import { buildLocalLock, writeLockFile } from './lock.js';
+import { resolveEngine } from '../utils/engine.js';
 
 /**
  * Executes local Docker/Podman deployment using deploy-ability
@@ -134,7 +135,7 @@ export async function executeLocalDeployment(ctx: DeploymentContext): Promise<vo
       agent: agentConfig,
       projectRoot,
     },
-    engine: profile.engine || flags.engine || 'docker',
+    engine: resolveEngine(flags.engine, profile.engine, ctx),
     dryRun: flags.dryRun || false,
     verbose: flags.verbose || false,
 

package/src/commands/down.ts

@@ -15,6 +15,7 @@
 
 import path from 'node:path';
 import { execSync } from 'node:child_process';
+import { resolveEngine, composeCmd } from '../utils/engine.js';
 
 import {
   AkashClient,
@@ -55,6 +56,7 @@ export interface DownOptions {
   project?: string;
   profile?: string;
   instance?: string;
+  label?: string;
   all?: boolean;
   engine?: string;
   yes?: boolean;
@@ -125,6 +127,50 @@ export async function executeDown(
       return;
     }
     lock = entry;
+  } else if (options.label) {
+    // Explicit --label flag: find deployments matching the label
+    const labelMatches = entries.filter(([_, d]) => d.label === options.label);
+    if (labelMatches.length === 0) {
+      logger.error(
+        errorColor(`No active deployment found with label "${options.label}".`)
+      );
+      logger.log(
+        dim('Active deployments: ' + entries.map(([k, d]) => {
+          const l = d.label ? ` (${d.label})` : '';
+          return `${d.instanceId}${l}`;
+        }).join(', '))
+      );
+      return;
+    } else if (labelMatches.length === 1) {
+      lock = labelMatches[0][1];
+    } else if (options.autonomous) {
+      logger.error(
+        errorColor(
+          `Multiple deployments found with label "${options.label}". In autonomous mode, specify --instance to disambiguate.`
+        )
+      );
+      logger.log(
+        dim('Instances: ' + labelMatches.map(([_, d]) => `${d.instanceId} (${d.profile})`).join(', '))
+      );
+      return;
+    } else {
+      // Multiple deployments with same label — prompt
+      logger.log('');
+      logger.log(bold(`Multiple deployments with label "${options.label}" found:`));
+      logger.log('');
+      for (const [key, dep] of labelMatches) {
+        logger.log(`  ${highlight(dep.instanceId)}  ${dim(`(${dep.profile}, ${dep.target}, deployed ${dep.deployedAt})`)}`);
+      }
+      logger.log('');
+
+      const selected = await selectPrompt(
+        'Which deployment do you want to tear down?',
+        labelMatches.map(([_, dep]) => `${dep.instanceId} (${dep.profile}, ${dep.target})`)
+      );
+
+      const selectedInstanceId = selected.replace(/ \(.*\)$/, '');
+      lock = labelMatches.find(([_, d]) => d.instanceId === selectedInstanceId)![1];
+    }
   } else if (options.all) {
     // --all flag: tear down everything (handled separately below)
     if (!options.yes && !options.autonomous) {
@@ -314,7 +360,8 @@ async function teardownLocal(
 ): Promise<void> {
   const { logger } = ctx;
   const local = lock.local!;
-  const engine = options.engine || local.engine;
+  const engine = resolveEngine(options.engine, local.engine, ctx);
+  const compose = composeCmd(engine);
 
   const spinner = startSpinner(
     `Stopping ${local.services.length} service(s) with ${engine}...`
@@ -322,7 +369,7 @@ async function teardownLocal(
 
   try {
     const composeFile = local.composePath;
-    const cmd = `${engine} compose -f "${composeFile}" down --remove-orphans`;
+    const cmd = `${compose} -f "${composeFile}" down --remove-orphans`;
 
     if (options.verbose) {
       logger.log(dim(`Running: ${cmd}`));

package/src/commands/list.ts

@@ -0,0 +1,241 @@
+/**
+ * Deploy List Command — Show active deployments
+ *
+ * Reads the `.kadi-deploy.lock` file and displays a table of all active
+ * deployment instances with their key identifiers (instance ID, profile,
+ * target, label, Akash DSEQ / provider, local engine / services, etc.).
+ *
+ * @module commands/list
+ */
+
+import path from 'node:path';
+import {
+  readLockFile,
+  type DeploymentLock,
+  type LockFile,
+} from './lock.js';
+import {
+  error as errorColor,
+  dim,
+  bold,
+  highlight,
+  formatKeyValue,
+} from '../cli/colors.js';
+import type { IKadiContext } from '../types.js';
+
+// ─────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────
+
+export interface ListOptions {
+  project?: string;
+  profile?: string;
+  json?: boolean;
+  verbose?: boolean;
+}
+
+// ─────────────────────────────────────────────────────────
+// Main entry point
+// ─────────────────────────────────────────────────────────
+
+/**
+ * Execute the `kadi deploy list` command.
+ *
+ * Reads the lock file and prints all active deployments.
+ */
+export async function executeList(
+  ctx: IKadiContext,
+  options: ListOptions
+): Promise<void> {
+  const { logger } = ctx;
+  const projectRoot = path.resolve(options.project || process.cwd());
+
+  // ----------------------------------------------------------------
+  // 1. Read lock file
+  // ----------------------------------------------------------------
+  let lockFile: LockFile | null;
+
+  try {
+    lockFile = await readLockFile(projectRoot);
+  } catch (err) {
+    logger.error(
+      errorColor(`Failed to read lock file: ${(err as Error).message}`)
+    );
+    return;
+  }
+
+  if (!lockFile || Object.keys(lockFile.deployments).length === 0) {
+    if (options.json) {
+      logger.log(JSON.stringify([], null, 2));
+    } else {
+      logger.log(dim('No active deployments found.'));
+      logger.log(
+        dim(
+          'Deploy with `kadi deploy` to create a deployment, or specify --project <path>.'
+        )
+      );
+    }
+    return;
+  }
+
+  // ----------------------------------------------------------------
+  // 2. Filter by profile if specified
+  // ----------------------------------------------------------------
+  let entries = Object.entries(lockFile.deployments);
+
+  if (options.profile) {
+    entries = entries.filter(([_, d]) => d.profile === options.profile);
+    if (entries.length === 0) {
+      if (options.json) {
+        logger.log(JSON.stringify([], null, 2));
+      } else {
+        logger.log(
+          dim(`No active deployments found for profile "${options.profile}".`)
+        );
+      }
+      return;
+    }
+  }
+
+  // ----------------------------------------------------------------
+  // 3. JSON output
+  // ----------------------------------------------------------------
+  if (options.json) {
+    const output = entries.map(([key, dep]) => ({
+      instanceId: dep.instanceId,
+      profile: dep.profile,
+      target: dep.target,
+      label: dep.label || null,
+      deployedAt: dep.deployedAt,
+      ...(dep.akash
+        ? {
+            dseq: dep.akash.dseq,
+            owner: dep.akash.owner,
+            provider: dep.akash.provider,
+            providerUri: dep.akash.providerUri,
+            network: dep.akash.network,
+          }
+        : {}),
+      ...(dep.local
+        ? {
+            engine: dep.local.engine,
+            services: dep.local.services,
+            composePath: dep.local.composePath,
+          }
+        : {}),
+    }));
+    logger.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // ----------------------------------------------------------------
+  // 4. Table output
+  // ----------------------------------------------------------------
+  logger.log('');
+  logger.log(bold(`Active Deployments (${entries.length})`));
+  logger.log(dim('─'.repeat(70)));
+  logger.log('');
+
+  // Build column data
+  const rows: string[][] = [];
+  const headers = ['INSTANCE', 'PROFILE', 'TARGET', 'LABEL', 'DETAILS', 'DEPLOYED'];
+
+  for (const [key, dep] of entries) {
+    const label = dep.label || dim('—');
+    const deployed = formatDate(dep.deployedAt);
+    let details: string;
+
+    if (dep.target === 'akash' && dep.akash) {
+      details = `dseq=${dep.akash.dseq}`;
+      if (options.verbose) {
+        details += ` provider=${shortenProvider(dep.akash.provider)}`;
+        details += ` network=${dep.akash.network}`;
+      }
+    } else if (dep.target === 'local' && dep.local) {
+      details = `engine=${dep.local.engine}`;
+      if (options.verbose) {
+        details += ` services=${dep.local.services.join(',')}`;
+      }
+    } else {
+      details = dim('—');
+    }
+
+    rows.push([
+      dep.instanceId,
+      dep.profile,
+      dep.target,
+      label,
+      details,
+      deployed,
+    ]);
+  }
+
+  // Calculate column widths
+  const colWidths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => stripAnsi(r[i]).length))
+  );
+
+  // Print header
+  logger.log(
+    headers
+      .map((h, i) => dim(h.padEnd(colWidths[i] + 2)))
+      .join('')
+  );
+
+  // Print rows
+  for (const row of rows) {
+    const formatted = row.map((cell, i) => {
+      const padded = padWithAnsi(cell, colWidths[i] + 2);
+      if (i === 0) return highlight(padded); // Instance ID in cyan
+      return padded;
+    });
+    logger.log(formatted.join(''));
+  }
+
+  logger.log('');
+  logger.log(
+    dim(
+      'Use `kadi deploy down --instance <id>` or `kadi deploy down --label <label>` to tear down a deployment.'
+    )
+  );
+  logger.log('');
+}
+
+// ─────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────
+
+/** Strip ANSI escape codes for width calculation */
+function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\u001B\[[0-9;]*m/g, '');
+}
+
+/** Pad a string that may contain ANSI codes to a visible width */
+function padWithAnsi(str: string, width: number): string {
+  const visible = stripAnsi(str).length;
+  const padding = Math.max(0, width - visible);
+  return str + ' '.repeat(padding);
+}
+
+/** Format ISO date to a shorter display format */
+function formatDate(iso: string): string {
+  try {
+    const d = new Date(iso);
+    return d.toLocaleDateString('en-US', {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+      hour: '2-digit',
+      minute: '2-digit',
+    });
+  } catch {
+    return iso;
+  }
+}
+
+/** Shorten a provider address for display */
+function shortenProvider(provider: string): string {
+  if (provider.length <= 20) return provider;
+  return provider.slice(0, 10) + '...' + provider.slice(-8);
+}

package/src/index.ts

@@ -15,6 +15,7 @@ import { loadAgentConfig, getFirstProfile, hasProfile, getProfile } from './conf
 import { executeAkashDeployment } from './commands/deploy.js';
 import { executeLocalDeployment } from './commands/deploy-local.js';
 import { executeDown } from './commands/down.js';
+import { executeList } from './commands/list.js';
 import { validateSecretsOrFail } from './secrets/index.js';
 
 /**
@@ -23,6 +24,7 @@ import { validateSecretsOrFail } from './secrets/index.js';
  * Uses Commander subcommands:
  *   kadi deploy [up]   — Deploy agents (default, backward compatible)
  *   kadi deploy down   — Tear down an active deployment
+ *   kadi deploy list   — List active deployments
  *
  * @param ctx - Plugin context injected by the Kadi CLI
  */
@@ -100,8 +102,14 @@ Teardown:
   kadi deploy down                      # Tear down the active deployment
   kadi deploy down --autonomous         # Fully non-interactive (skips confirmation + QR)
   kadi deploy down --autonomous --profile prod  # Required when multiple deployments active
+  kadi deploy down --label my-label     # Tear down deployment by label
   kadi deploy down --yes                # Skip confirmation (interactive mode)
 
+Listing:
+  kadi deploy list                      # Show all active deployments
+  kadi deploy list --json               # Output as JSON
+  kadi deploy list --verbose            # Show additional details
+
 Configuration:
   Profiles are defined in agent.json under the "deploy" field.
   CLI flags override profile settings.
@@ -157,6 +165,7 @@ Supported Targets:
     )
     .option('--profile <profile>', 'Profile name to tear down (prompts if multiple active)')
     .option('--instance <id>', 'Instance ID to tear down (4-char hex from deploy output)')
+    .option('--label <label>', 'Tear down deployment matching this label')
     .option('--all', 'Tear down all active deployments')
     .option('--engine <engine>', 'Override container engine (docker|podman)')
     .option('-y, --yes', 'Skip confirmation prompt')
@@ -172,6 +181,7 @@ Supported Targets:
           project: (flags.project as string) || process.cwd(),
           profile: flags.profile as string | undefined,
           instance: flags.instance as string | undefined,
+          label: flags.label as string | undefined,
           all: flags.all as boolean | undefined,
           engine: flags.engine as string | undefined,
           yes: flags.yes as boolean | undefined,
@@ -190,6 +200,46 @@ Supported Targets:
           console.error(error);
         }
 
+        process.exitCode = 1;
+      }
+    });
+
+  // ─────────────────────────────────────────────────────────────────
+  // Subcommand: deploy list — show active deployments
+  // ─────────────────────────────────────────────────────────────────
+  deploy
+    .command('list')
+    .alias('ls')
+    .description(
+      'List active deployments from .kadi-deploy.lock'
+    )
+    .option(
+      '-p, --project <path>',
+      'Path to project with agent.json / .kadi-deploy.lock'
+    )
+    .option('--profile <profile>', 'Filter by profile name')
+    .option('--json', 'Output as JSON')
+    .option('--verbose, -v', 'Show additional details (provider, services, etc.)')
+    .action(async (...args: unknown[]) => {
+      const flags = args[0] as Record<string, unknown>;
+
+      try {
+        await executeList(ctx, {
+          project: (flags.project as string) || process.cwd(),
+          profile: flags.profile as string | undefined,
+          json: flags.json as boolean | undefined,
+          verbose: flags.verbose as boolean | undefined,
+        });
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        logger.error(`List failed: ${errorMessage}`);
+
+        if (flags.verbose) {
+          logger.error('Full error details:');
+          console.error(error);
+        }
+
         process.exitCode = 1;
       }
     });

package/src/infrastructure/registry.ts

@@ -88,8 +88,12 @@ export async function setupRegistryIfNeeded(
     };
   }
 
+  // Resolve engine early — needed for hasLocalImages + registry
+  const resolvedEngine = options.containerEngine || 'docker';
+  const resolvedTunnel = options.tunnelService || 'kadi';
+
   // Check if any services use local images
-  if (!hasLocalImages(profile)) {
+  if (!hasLocalImages(profile, resolvedEngine)) {
     // All images are remote (docker.io/nginx, ghcr.io/owner/repo, etc.)
     // No registry needed - providers can pull directly
     return {
@@ -99,8 +103,6 @@ export async function setupRegistryIfNeeded(
   }
 
   // Profile has local images - start registry infrastructure
-  const resolvedTunnel = options.tunnelService || 'kadi';
-  const resolvedEngine = options.containerEngine || 'docker';
   logger.log(`🔧 Local images detected — setting up temporary registry (${resolvedTunnel} tunnel)...`);
 
   const manager = new TemporaryContainerRegistryManager(logger);
@@ -179,7 +181,8 @@ export function hasLocalImages(profile: AkashProfile, engine: 'docker' | 'podman
       // Check if image exists locally
       const result = execSync(`${engine} images -q ${image}`, {
         encoding: 'utf8',
-        stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+        stdio: ['pipe', 'pipe', 'pipe'], // Suppress stderr
+        timeout: 10000 // 10s — don't hang if daemon is unresponsive
       });
       return result.trim().length > 0;
     } catch (error) {

package/src/types.ts

@@ -183,6 +183,14 @@ export interface IKadiContext {
   commander: ICommander; // Commander.js instance for CLI registration
   logger: IKadiLogger; // KADI logging utilities
   core: IKadiCore; // Core KADI functionality and utilities
+
+  /**
+   * Global KADI configuration from ~/.kadi/config.json
+   *
+   * Injected by the main kadi CLI. Provides access to user preferences
+   * including preferences.containerEngine for default engine selection.
+   */
+  config?: Record<string, any>;
 }
 
 /**

package/src/utils/engine.ts

@@ -0,0 +1,88 @@
+/**
+ * Container Engine Utilities
+ *
+ * Centralized engine resolution and compose command detection for kadi-deploy.
+ * Mirrors the resolution pattern used in kadi-broker for consistency:
+ *
+ *   CLI --engine flag > profile.engine > global preferences.containerEngine > 'docker'
+ *
+ * @module utils/engine
+ */
+
+import { execSync } from 'node:child_process';
+
+export type ContainerEngine = 'docker' | 'podman';
+
+const DEFAULT_ENGINE: ContainerEngine = 'docker';
+
+/**
+ * Resolve which container engine to use.
+ *
+ * Resolution order (highest priority wins):
+ * 1. CLI --engine flag (explicit per-command override)
+ * 2. Deploy profile engine (agent.json profile setting)
+ * 3. Global config preferences.containerEngine (user default via `kadi config set`)
+ * 4. DEFAULT_ENGINE ('docker')
+ *
+ * @param flagEngine  - Value of the --engine CLI flag (may be undefined)
+ * @param profileEngine - Engine from the deploy profile in agent.json (may be undefined)
+ * @param ctx - KADI context (used to read global config preferences)
+ * @returns The resolved container engine
+ */
+export function resolveEngine(
+  flagEngine: string | undefined,
+  profileEngine: string | undefined,
+  ctx: any
+): ContainerEngine {
+  // 1. CLI flag takes highest priority
+  if (flagEngine && isValidEngine(flagEngine)) {
+    return flagEngine as ContainerEngine;
+  }
+
+  // 2. Deploy profile engine
+  if (profileEngine && isValidEngine(profileEngine)) {
+    return profileEngine as ContainerEngine;
+  }
+
+  // 3. Global config preferences.containerEngine
+  const configEngine = ctx?.config?.preferences?.containerEngine;
+  if (configEngine && isValidEngine(configEngine)) {
+    return configEngine as ContainerEngine;
+  }
+
+  // 4. Fall back to default
+  return DEFAULT_ENGINE;
+}
+
+/**
+ * Get the compose command for the given engine.
+ *
+ * - docker  -> "docker compose"
+ * - podman  -> "podman-compose" if available, else "podman compose"
+ *
+ * Podman doesn't have a built-in compose — it delegates to an external
+ * compose provider. On systems with Docker Desktop installed (even if not
+ * running), `podman compose` may resolve to Docker Desktop's broken shim.
+ * We prefer `podman-compose` (the standalone Python tool) when available.
+ *
+ * @param engine - The container engine to get the compose command for
+ * @returns The compose command string
+ */
+export function composeCmd(engine: ContainerEngine): string {
+  if (engine !== 'podman') return `${engine} compose`;
+
+  try {
+    execSync('podman-compose --version', { stdio: 'ignore' });
+    return 'podman-compose';
+  } catch {
+    return 'podman compose';
+  }
+}
+
+/**
+ * Validate that a string is a supported container engine.
+ */
+function isValidEngine(value: string): value is ContainerEngine {
+  const normalized = value.toLowerCase();
+  return normalized === 'docker' || normalized === 'podman';
+}