agent-sandbox

llms.txt

# Agent Sandbox

> CLI (`abx`, Node.js/TypeScript) for the Alibaba Cloud FC Agent Sandbox service;
> the Python SDK lives in the `python-sdk` repository.
> E2B-protocol compatible with Alibaba Cloud extensions (OSS, VPC, custom domains).

## Purpose

Agent Sandbox lets AI agents and developers create, manage, and interact
with secure cloud sandboxes. It provides isolated execution environments for
running untrusted code, file operations, and shell commands — designed for
LLM tool-use and agentic workflows.

AI coding tools: read [SKILL.md](SKILL.md) — a static, tool-neutral Agent
Skills guide covering install, credential safety, MCP vs SDK selection,
sandbox lifecycle, file operations, and error diagnosis. The guide can be
installed into skills-aware tools (Qoder, Claude Code, Cursor, Qwen Code,
Codex, …) before the CLI/SDK is installed, with:

    npx skills add agent-sandbox/agent-sandbox --skill agent-sandbox -a <agent> -y

Full matrix (manual copy, Git sparse checkout, version pinning, uninstall):
docs/en/guide/agent-skill-installation.md

## Architecture

Layered CLI (lower layers never import upper layers; the client core mirrors the
Python SDK's layers, whose own architecture lives in the `python-sdk` repository):

- bin: `abx` executable entry (src/bin/abx.ts)
- framework: click-compatible command framework (parsing, help, exit codes)
- cli: main, OutputManager, formatters, command groups (src/cli/commands)
- agent / session: MCP server, template authoring, local session store
- api: Sandbox, files, code, commands, network, image, template
- protocol / transport: E2B-compatible REST + WebSocket, HTTP/2, API Key / AK-SK auth
- models / utils: typed models, error hierarchy, config, secret store, logging, retry

Details: docs/en/design/architecture.md

## Key Commands

Install: `npm install -g @agent-sandbox/cli`

```
abx create --template python-hello # create sandbox
abx exec <id> -- echo hello          # run command (--stream, --background)
abx run <id> <name> --arg k=v       # named command on the in-sandbox server
abx upload <id> ./local /remote     # file transfer
abx mcp start                       # start MCP server (STDIO)
abx kill <id>                       # destroy sandbox
```

## Source Layout

- src/transport/ — HTTP, WebSocket, auth, codec
- src/protocol/ — sandbox lifecycle, filesystem, process, terminal
- src/models/ — data models, error hierarchy
- src/api/ — Sandbox class, file/code/command/network APIs
- src/cli/ — CLI commands and formatters (on the mini click-compatible framework in src/framework/)
- src/agent/ — MCP server, tool definitions, template authoring
- src/bin/abx.ts — executable entry point

## Links

- Agent usage skill: SKILL.md
- Agent skill installation: docs/en/guide/agent-skill-installation.md
- README: README.md
- Documentation index: docs/en/README.md
- Design index: docs/en/DESIGN.md
- CLI architecture: docs/en/design/architecture.md
- CLI design: docs/en/design/cli-design.md
- Templates catalog: docs/en/design/templates-catalog.md
- MCP server: docs/en/design/mcp-server.md
- Python to Node port contract: docs/PORTING.md
- Contributing: .github/CONTRIBUTING.md
- Changelog: CHANGELOG.md

## Related: the Python SDK (`python-sdk` repository)

- Repository: https://github.com/alibaba-agent-sandbox/python-sdk
- Architecture: https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/docs/en/design/architecture.md
- SDK API design: https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/docs/en/design/sdk-api-design.md
- Template system: https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/docs/en/design/template-system.md
- template.yaml spec: https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/docs/en/reference/template-yaml-spec.md
- SDK usage: https://github.com/alibaba-agent-sandbox/python-sdk/blob/main/docs/en/guide/sdk-usage.md