Complete CLI reference for managing agents, tasks, and swarm configuration from the terminal — install via bunx or npx, manage worktrees, run agent commands, and configure your swarm without the dashboard UI

Agent Swarm provides a CLI for managing the swarm, running agents, and development.

Installation

# Run directly with bunx or npx
bunx @desplega.ai/agent-swarm <command>
npx @desplega.ai/agent-swarm <command>

# Or install globally
bun install -g @desplega.ai/agent-swarm
agent-swarm <command>

Commands

onboard

Set up a new swarm from scratch using Docker Compose. The interactive wizard collects credentials, generates docker-compose.yml + .env, starts the stack, verifies health, and prints a dashboard deep-link that auto-connects with the generated API URL and key.

bunx @desplega.ai/agent-swarm onboard
npx @desplega.ai/agent-swarm onboard
bunx @desplega.ai/agent-swarm onboard --dry-run
bunx @desplega.ai/agent-swarm onboard --yes --preset=dev
ANTHROPIC_API_KEY=sk-... bunx @desplega.ai/agent-swarm onboard --yes --preset=solo

Option	Description
`--dry-run`	Preview what would be generated without writing
`-y, --yes`	Non-interactive mode (reads from env vars)
`--preset <name>`	Preset: `dev`, `content`, `research`, `solo`

connect

Connect this project to an existing swarm. Creates .mcp.json and .claude/settings.local.json with server URL and API key. Auto-reads AGENT_SWARM_API_KEY (or legacy API_KEY) from .env if present.

bunx @desplega.ai/agent-swarm connect
npx @desplega.ai/agent-swarm connect
bunx @desplega.ai/agent-swarm connect --dry-run
bunx @desplega.ai/agent-swarm connect -y

Option	Description
`--dry-run`	Show what would be changed without writing
`--restore`	Restore files from `.bak` backups
`-y, --yes`	Non-interactive mode (use env vars)

api

Start the API + MCP HTTP server.

bunx @desplega.ai/agent-swarm api
npx @desplega.ai/agent-swarm api
bunx @desplega.ai/agent-swarm api --port 8080 --key my-secret
bunx @desplega.ai/agent-swarm api --db /data/swarm.sqlite

Option	Description
`-p, --port <port>`	Port to listen on (default: 3013)
`-k, --key <key>`	API key for authentication
`--db <path>`	Database file path (default: `./agent-swarm-db.sqlite`)

claude

Run Claude CLI with optional message and headless mode.

agent-swarm claude
agent-swarm claude --headless -m "Hello"
agent-swarm claude -- --resume

Option	Description
`-m, --msg <message>`	Message to send to Claude
`--headless`	Run in headless mode (stream JSON output)
`-- <args...>`	Additional arguments to pass to Claude CLI

worker

Run Claude in headless loop mode as a worker agent.

agent-swarm worker
agent-swarm worker --yolo
agent-swarm worker -m "Custom prompt"
agent-swarm worker --system-prompt "You are a Python specialist"

Option	Description
`-m, --msg <prompt>`	Custom prompt (default: `/agent-swarm:start-worker`)
`--yolo`	Continue on errors instead of stopping
`--system-prompt <text>`	Custom system prompt (appended to Claude)
`--system-prompt-file <path>`	Read system prompt from file
`-- <args...>`	Additional arguments to pass to Claude CLI

lead

Run Claude as lead agent in headless loop mode. Same options as worker.

agent-swarm lead
agent-swarm lead --yolo

Authenticate Codex via ChatGPT OAuth (browser or manual paste). Prompts interactively for the target API URL and a best-effort masked API key, then stores credentials in the swarm API config store for deployed workers. Run from your laptop, not inside a worker container.

bunx @desplega.ai/agent-swarm codex-login
npx @desplega.ai/agent-swarm codex-login
bunx @desplega.ai/agent-swarm codex-login --api-url https://swarm.example.com

Option	Description
`--api-url <url>`	Swarm API URL (default: `MCP_BASE_URL` or `http://localhost:3013`)
`--api-key <key>`	Swarm API key (default: `API_KEY` or `123123`)
`--slot <n>`	Store the OAuth credential in a specific pool slot (`0-100`) instead of auto-picking the next free slot

See Provider Auth: Codex OAuth for the full ChatGPT OAuth flow.

rbac bootstrap

Seed the built-in RBAC roles and backfill the default role onto any zero-role users. This is idempotent and is the operator-side bootstrap step before turning RBAC_ENABLED=true.

bunx @desplega.ai/agent-swarm rbac bootstrap
npx @desplega.ai/agent-swarm rbac bootstrap
agent-swarm rbac bootstrap

The command accepts exactly the bootstrap subcommand. Anything else prints help and exits non-zero.

claude-managed-setup

Bootstrap Anthropic Managed Agents for the swarm: create the cloud Environment, upload plugin/commands/*.md skills, create the managed Agent, and persist the resulting MANAGED_AGENT_ID + MANAGED_ENVIRONMENT_ID to swarm_config so deployed workers can restore them at boot. Prompts interactively for ANTHROPIC_API_KEY when not set in env. Idempotent — re-run with --force to recreate. Run from your laptop, not inside a worker container.

bunx @desplega.ai/agent-swarm claude-managed-setup
npx @desplega.ai/agent-swarm claude-managed-setup
bunx @desplega.ai/agent-swarm claude-managed-setup --force
bunx @desplega.ai/agent-swarm claude-managed-setup --api-url https://swarm.example.com

Option	Description
`--api-url <url>`	Swarm API URL (default: `MCP_BASE_URL` or `http://localhost:3013`)
`--api-key <key>`	Swarm API key (default: `API_KEY` or `123123`)
`--force`	Recreate Anthropic-side resources even if already configured

e2b

Build Agent Swarm E2B templates and launch or manage grouped E2B swarms on demand for CI, Dockerless smoke tests, and ephemeral staging environments.

bunx @desplega.ai/agent-swarm e2b build-template --role worker
npx @desplega.ai/agent-swarm e2b build-template --role worker
bunx @desplega.ai/agent-swarm e2b start-worker --api-url https://swarm.example.com --api-key "$SWARM_API_KEY"
bunx @desplega.ai/agent-swarm e2b start-stack --yes --swarm demo --workers 2 --api-key "$SWARM_API_KEY"
bunx @desplega.ai/agent-swarm e2b swarms info demo
bunx @desplega.ai/agent-swarm e2b swarms logs demo --role api --follow

Subcommand	Description
`build-template --role api\|worker`	Build or rebuild an E2B template
`delete-template <template...>`	Delete E2B templates
`publish-template <template...>`	Publish E2B templates
`unpublish-template <template...>`	Make E2B templates private
`start-api --template <name>`	Start the API in an E2B sandbox
`start-worker --api-url <url>`	Start a worker against a public API URL
`start-stack`	Launch a grouped API + lead + N worker swarm; opens an Ink wizard on a TTY unless `--yes` / headless
`list`	List active E2B sandboxes
`extend <sandbox-id...>`	Extend or reduce one or more sandbox TTLs with `--timeout-sec <seconds>`
`swarms list`	Group dispatcher-owned sandboxes by `metadata.swarm` slug
`swarms info <slug>`	Show API URL, key source, TTLs, health, and dashboard deep-link for a swarm
`swarms add <slug>`	Add workers or `--add-lead` to an existing swarm and re-sync their TTL to the group's current end
`swarms logs <slug>`	Stream tee'd entrypoint logs for the API, lead, or worker role; `--follow` tails live output
`swarms kill <slug> \| --all`	Tear down one grouped swarm or sweep every dispatcher-owned swarm
`kill <sandbox-id...> \| --all`	Stop one or more E2B sandboxes, or every dispatcher-owned sandbox

Key E2B options:

Option	Description
`--swarm <slug>`	Set the group slug used by `start-stack` and the `swarms` commands
`--workers <n>`	Number of workers to start or add (default `1`)
`--no-lead`	Legacy topology: start only the API plus workers
`--provider <name>`	Worker harness provider (default `claude`)
`--timeout-sec <seconds>`	Sandbox TTL; for `extend`, the new TTL counted from now
`--env-file`, `--secret`, `--inherit-env`	Shared runtime configuration applied to all roles
`--api-env-file`, `--lead-env-file`, `--worker-env-file`	Role-scoped env layers added on top of the shared config
`--api-secret`, `--lead-secret`, `--worker-secret`	Role-scoped secrets layered on top of the shared config
`--json`	Machine-readable output for automation

start-stack now defaults to the full API + lead + workers topology. It runs interactively on a TTY, but switches to headless mode automatically under --yes, --non-interactive, --dry-run, or any non-TTY invocation. The swarms logs output is secret-scrubbed before it hits stdout, and swarms info can optionally embed the API key into the dashboard deep-link with --reveal-key when you explicitly need a copy-pasteable URL.

x

Execute an external command route. The first target is Composio:

agent-swarm x composio GET /tools
agent-swarm x composio POST /tool_router/session --body '{"user_id":"swarm-user-id"}'

See The x command for the Composio workflow, swarm_x MCP equivalent, and safety rules.

docs

Show the documentation URL. All pages are also available in markdown format by appending .md to the URL.

bunx @desplega.ai/agent-swarm docs
npx @desplega.ai/agent-swarm docs
bunx @desplega.ai/agent-swarm docs --open

Option	Description
`--open`	Open docs in default browser

hook

Handle Claude Code hook events from stdin. Used internally by the agent-swarm hooks system.

agent-swarm hook

codex-hook

Handle Codex CLI lifecycle hook events from stdin for queued steering delivery. This internal command is registered by the worker image's managed Codex requirements and is not normally invoked by operators.

agent-swarm codex-hook

artifact

Manage agent artifacts — serve static files or Hono apps via localtunnel.

# Serve a directory as a public artifact
agent-swarm artifact serve ./my-report --name my-report

# Serve a Hono app (must export default Hono instance)
agent-swarm artifact serve ./server.ts --name dashboard

# List active artifacts
agent-swarm artifact list

# Stop an artifact
agent-swarm artifact stop my-report

Subcommands:

Subcommand	Description
`serve <path>`	Serve a directory or script via localtunnel
`list`	List active artifacts from the service registry
`stop <name>`	Stop an artifact and close its tunnel

Options for serve:

Option	Description
`--name <name>`	Name for the artifact (derived from path if omitted)
`--port <port>`	Local port to use
`--no-auth`	Disable authentication
`--subdomain <sub>`	Request a specific localtunnel subdomain

Artifacts are registered in the service registry and automatically cleaned up when the session ends (via the Stop hook).

Development Commands

These are available when developing Agent Swarm locally:

# Start MCP server
bun run start        # STDIO transport
bun run start:http   # HTTP transport

# Development with hot reload
bun run dev          # STDIO
bun run dev:http     # HTTP

# MCP Inspector (debug tools)
bun run inspector:http

# Run worker/lead locally
bun run worker
bun run lead

# Hook handler
bun run hook

# Linting and formatting
bun run lint
bun run lint:fix
bun run format

# Type checking
bun run tsc:check

# Build binaries
bun run build:binary      # x64
bun run build:binary:arm64  # ARM64

# Docker
bun run docker:build:worker
bun run docker:run:worker
bun run docker:run:lead

# Generate MCP docs
bun run docs:mcp

Dashboard UI

The React-based monitoring dashboard is in the ui/ directory:

cd ui
pnpm install
pnpm run dev

Opens at http://localhost:5274. Provides real-time visibility into:

Agent status and activity
Task list and progress
Inter-agent chat messages
Service registry
Usage and cost tracking

Getting Started — Set up your first swarm
Environment Variables — Configuration reference for all env vars
MCP Tools Reference — Complete reference for all swarm MCP tools
Deployment Guide — Production deployment options

CLI Reference