Agent Sandbox Registry

agent-sandbox

Agent Sandbox CLI — Design Document Index

中文

docs/en/DESIGN.md

Agent Sandbox CLI — Design Document Index

Version: v3.0 | Last Updated: 2026-10-12

Entry point and index for the design documentation of the abx CLI (this repository). Detailed designs live in the topic documents under design/. The Python SDK has its own design set in the python-sdk repository; see Related SDK documentation.

Project Overview

abx (npm package @agent-sandbox/cli) is the command-line client for the Alibaba Cloud FC Agent Sandbox service, designed for both human developers and AI Agents. It is implemented in Node.js / TypeScript. It also hosts the MCP server that exposes sandboxes to IDE agents.

Core Principles

  1. Stable command surface — command names, options, help text, error text, output channels and exit codes (0–6) stay stable; golden files guard them
  2. AI-first — natural language sandbox creation, --json / --quiet / --ci output modes, the MCP server as a first-class citizen
  3. Zero configuration defaults — install, export an API key, create a sandbox

Quick Start

npm install -g @agent-sandbox/cli   # abx CLI (Node.js 20+)
export ABX_SANDBOX_API_KEY=your-api-key
abx create --template base
abx list

Architecture Overview

The CLI follows a strict layered structure — lower layers never import upper layers. The full breakdown (layer table, source directories, build and release, parity contract) is CLI Architecture.

graph TB
    BIN["bin — abx entry"]
    subgraph Front["Command line"]
        FW["framework — click-compatible command framework"]
        CLI["cli — main, OutputManager, formatters"]
        CMD["cli/commands — command groups"]
    end
    subgraph Services["Host-side services"]
        AG["agent — MCP server, template authoring"]
        SES["session — LocalSessionStore"]
    end
    subgraph Core["Client core"]
        API["api — Sandbox, files, code, commands, template"]
        PRO["protocol"]
        TRA["transport — HTTP, WebSocket, auth"]
        MOD["models + utils"]
    end
    BIN --> CLI --> FW
    CLI --> CMD
    CMD --> AG
    CMD --> SES
    CMD --> API
    AG --> API
    SES --> API
    API --> PRO --> TRA --> MOD

Design Topic Index

Architecture and Commands

Topic Document Summary
CLI Architecture architecture.md Layers, src/ directory structure, command groups, output and exit codes, config/credentials, build / SEA binary / release, parity contract
CLI Command System cli-design.md Command tree (45 commands), global options, natural language creation, OutputManager, AI-friendly design
Templates Catalog templates-catalog.md Single source of truth (SSOT): the awesome-templates catalog repo, the remote index client, caching/degradation behaviour, the fixture boundary, and the template command surface

AI and Agent Integration

Topic Document Summary
MCP Server mcp-server.md 7 P0 MCP tools, STDIO + Streamable HTTP transports, FC deployment artifact, session binding
Agents API agents-api.md In-sandbox agent sessions. Codex and Qwen Code today; more CLIs on the same routes later

Port, Layout and Provider Drafts

These are English-only maintainer documents under docs/design/ and docs/PORTING.md.

Topic Document Summary
Python to Node port PORTING.md Module-by-module port rules, the parity gate, test ledger
Repository layout repository-layout.md CLI repository layout review and docs-ownership rule
Providers and credentials (CLI spec) providers-and-credentials-cli.md Draft: CLI grammar, JSON shapes and tests for the provider layer, applied after parity
Providers review log providers-and-credentials-cli-review.md Review log for the draft above

Implementation Status

Feature Status Notes
CLI (45 commands) Implemented See cli-design.md
MCP Server (STDIO) Implemented 7 P0 tools
MCP Server (Streamable HTTP) Implemented agent/mcp_http.ts
abx mcp deploy (FC artifact generation) Implemented Generates deploy artifact; manual FC deployment steps printed. See mcp-server.md
Template build/push/create pipeline Implemented Via official CreateTemplate API
Single-file binary (Node SEA) Implemented See Binary Installation
Provider layer Planned Applied after the parity gate; see the provider drafts above
Resource Location
Architecture Decision Records (ADR) .agents/notes/
CLI golden-file evidence .agents/evidence/
Agents API python-sdk docs/en/guide/agents-api.md
User guides docs/en/guide/
CLI reference docs/en/reference/
Chinese (中文) design index docs/zh/DESIGN.md

The Python SDK (agent-sandbox), the in-sandbox server SDK and the platform contracts are documented in the python-sdk repository. The pages a CLI reader most often needs: