CLI Evidence: Help
abx --help
$ abx --help
Usage: cli [OPTIONS] [COMMAND] [ARGS]...
abx — Agent Sandbox CLI
Create, manage, and interact with cloud sandboxes.
Setup, create, or scaffold:
abx config init Guided credentials setup (run first)
abx create [DESCRIPTION] Create a cloud sandbox (AI or --template)
abx template init [DIR] Scaffold a local template project
Examples:
abx create --template base
abx list --status running
abx template search python
Related commands:
abx config --help Configure credentials and endpoints
abx sandbox --help Manage sandbox lifecycle and resources
abx template --help Discover, build, and deploy templates
Options:
-j, --json Output as JSON
-q, --quiet Minimal output
-v, --verbose Verbose output (DEBUG level)
--no-color Disable colored output
--log-level [debug|info|warning|error]
Set log level explicitly
--ci CI/CD mode (quiet + no-color + json)
-t, --timeout INTEGER Default sandbox lifetime in seconds (positive
integer; default: 300)
-p, --profile TEXT [Reserved] Configuration profile
--version Show the version and exit.
-h, --help Show this message and exit.
Commands:
config Manage persistent credentials and CLI defaults.
connect Open an interactive command REPL for a sandbox.
create Create a new sandbox.
deploy Publish a template project: build, push to ACR, register the...
download Download a file from the sandbox to local.
exec Execute one command in a sandbox and return its exit code.
info Show status, template, region, timeout, and URL for a sandbox.
init Scaffold a new sandbox template project.
install Install a template from TEMPLATE_REF (shortcut for 'abx...
kill Permanently destroy one sandbox or all running sandboxes.
list List sandboxes, optionally filtered by lifecycle status.
mcp Configure and run Agent Sandbox as an MCP server.
run Run a named custom command or registered command.
sandbox Manage sandbox lifecycle, files, processes, and system details.
template Discover, scaffold, build, and manage sandbox templates.
upload Upload a local file or directory to the sandbox.
Exit code: 0
create --help
$ abx create --help
Usage: cli create [OPTIONS] [DESCRIPTION]
Create a new sandbox.
Exactly one route is taken, and it must be explicit:
abx create --template base → launch the 'base' template
abx create --template NAME → launch NAME directly (no AI)
abx create "DESCRIPTION" → Qwen Code generates a template, builds
and deploys it, then launches a sandbox;
the agent researches public facts first
and asks only for details it cannot infer.
An interactive terminal is first asked
whether to switch to template init
(local files only)
DESCRIPTION and --template are mutually exclusive: passing both is rejected
instead of silently ignoring one of them.
Examples:
abx create --template base # explicit 'base' template
abx create --template python-hello # named template (no AI)
abx create -e API_KEY=xxx -e DEBUG=1 # inject env vars
abx create --upload ./app --timeout 600 # upload dir, 10-min lifetime
abx create "a python data science env" # AI-generate, build, deploy, create
abx create -y "a node.js api server" # non-interactive full pipeline
abx template init "a python data science env" # template files only
Notes:
AI generation needs the Qwen Code CLI and a DashScope/ModelStudio key
('abx config init'). The agent researches publicly verifiable facts
itself (tool stack, official install method, common dependencies) and
only asks for private preferences or business decisions it cannot
infer — one question at a time in interactive sessions. Non-interactive
shells must pass --yes to generate without asking. Interactive
sessions are asked up front whether to switch to template init,
which writes Dockerfile, commands.py, and template.yaml and stops
before build, push, deploy, and sandbox create. --yes skips that
question and runs the full pipeline.
Related commands:
abx list List existing sandboxes
abx info SANDBOX_ID Inspect a created sandbox
abx template init DIR Scaffold a new template project (local)
abx template init "DESC" AI-scaffold a template only (no build)
abx template search KEY Find reusable templates
abx config init Configure platform and Qwen Code credentials
Options:
-T, --template TEXT Template ID or alias to launch (e.g. 'base', 'python-
hello'). Defaults to 'base' when omitted. Cannot be
combined with DESCRIPTION.
-u, --upload PATH Local file or directory to upload after creation
-t, --timeout INTEGER Sandbox lifetime in seconds (positive integer;
default: global --timeout)
--request-timeout FLOAT HTTP request timeout in seconds for the create call
(floor: 120s for cold starts, or your configured
http_timeout if larger). Increase for very slow
sandbox creation.
-e, --env TEXT Environment variable for the sandbox, format
KEY=VALUE (repeatable)
-m, --metadata TEXT Metadata key-value pair, format KEY=VALUE
(repeatable)
-y, --yes Skip interactive prompts (the template-only switch,
Qwen Code install, credentials, description
clarification, build/deploy confirmation) and run the
full create pipeline. Required for AI generation in
non-interactive shells.
--acr-namespace TEXT ACR namespace for building the AI-generated template
(env: ACR_NAMESPACE, or set in .env file)
--dir DIRECTORY Parent directory for the AI-generated template files
(Dockerfile, commands.py, template.yaml); a new
<name>-<timestamp>-<id> subfolder is created inside
it. Default: ~/.abx/generated (an interactive
terminal is asked when omitted).
-v, --verbose Verbose output (DEBUG level)
-h, --help Show this message and exit.
Exit code: 0
list --help
$ abx list --help
Usage: cli list [OPTIONS]
List sandboxes, optionally filtered by lifecycle status.
Examples:
abx list
abx list --status running
abx list --status error --limit 50
abx list --region cn-shanghai
Related commands:
abx info SANDBOX_ID Show one sandbox in detail
abx create Create a new sandbox
abx kill SANDBOX_ID Destroy a sandbox
Options:
-s, --status [running|stopped|creating|paused|error]
Filter by status
-l, --limit INTEGER Maximum results (positive integer; default:
20)
-r, --region TEXT Region override for this command (default:
'abx config set region' value, else cn-
hangzhou)
-h, --help Show this message and exit.
Exit code: 0
info --help
$ abx info --help
Usage: cli info [OPTIONS] SANDBOX_ID
Show status, template, region, timeout, and URL for a sandbox.
Examples:
abx info abc123
abx --json info abc123
Related commands:
abx list Find sandbox IDs
abx sandbox capabilities Show declared capability groups
abx exec SANDBOX_ID CMD Run a command in the sandbox
Options:
-h, --help Show this message and exit.
Exit code: 0
kill --help
$ abx kill --help
Usage: cli kill [OPTIONS] [SANDBOX_ID]
Permanently destroy one sandbox or all running sandboxes.
Confirmation is required unless --yes is supplied. Use --yes for scripts and
other non-interactive environments.
Examples:
abx kill abc123
abx kill abc123 --yes
abx kill --all --yes
abx kill --all --yes --region cn-shanghai
Related commands:
abx list Find running sandbox IDs
abx info SANDBOX_ID Verify a sandbox before deletion
abx create Create a replacement sandbox
Options:
--all Kill all running sandboxes
-y, --yes Skip confirmation
-r, --region TEXT Region override for this command (default: 'abx config set
region' value, else cn-hangzhou)
-h, --help Show this message and exit.
Exit code: 0
exec --help
$ abx exec --help
Usage: cli exec [OPTIONS] SANDBOX_ID COMMAND
Execute one command in a sandbox and return its exit code.
Quote commands containing spaces or shell operators. Use --cwd to select the
remote working directory and --timeout for long-running commands.
Examples:
abx exec abc123 "python --version"
abx exec abc123 "pytest -q" --cwd /app --timeout 300
abx --json exec abc123 "echo ready"
Related commands:
abx connect SANDBOX_ID Open the command REPL
abx sandbox shell-stream SANDBOX_ID -c CMD
abx run SANDBOX_ID NAME Run a registered custom command
Options:
-t, --timeout INTEGER Command timeout in seconds (positive integer; default:
60)
--cwd TEXT Working directory (empty = container default)
-v, --verbose Verbose output (DEBUG level)
-h, --help Show this message and exit.
Exit code: 0
run --help
$ abx run --help
Usage: cli run [OPTIONS] SANDBOX_ID COMMAND_NAME
Run a named custom command or registered command.
Supports two argument styles:
Legacy: abx run <id> <cmd> --arg key=value
New: abx run <id> <cmd> --key value
When the command comes from @sandbox.register, typed options (--x, --y, ...)
are derived automatically from the function signature.
Examples:
abx run abc123 dev
abx run abc123 test --arg file=tests/
abx run abc123 demo --x 1 --y hello
Related commands:
abx exec SANDBOX_ID CMD Run an arbitrary shell command
abx info SANDBOX_ID Inspect the target sandbox
abx template info ID Inspect a template definition
Options:
-a, --arg TEXT Command argument as key=value (repeatable, legacy style)
-h, --help Show this message and exit.
Exit code: 0
connect --help
$ abx connect --help
Usage: cli connect [OPTIONS] SANDBOX_ID
Open an interactive command REPL for a sandbox.
This is a line-based REPL, not a PTY or a full SSH session: every entered line
runs in a new process with a 30-second timeout, and no shell state survives
between lines - ``cd``, environment variables and aliases are gone after each
command (use ``cd /path && <cmd>`` on one line, or ``abx exec --cwd``,
instead).
On interactive terminals basic line editing and command history are enabled
(Up/Down history, Ctrl+R search, Ctrl+A/E and friends). Type
``exit``/``quit`` or press Ctrl+D to leave; Ctrl+C also disconnects. Failed
commands are reported as one friendly message - never as raw HTTP errors.
Examples:
abx connect abc123
abx sandbox connect abc123
Related commands:
abx exec SANDBOX_ID CMD Run one command with a custom timeout
abx info SANDBOX_ID Inspect connection details
abx sandbox shell-stream SANDBOX_ID -c CMD
Options:
-h, --help Show this message and exit.
Exit code: 0
upload --help
$ abx upload --help
Usage: cli upload [OPTIONS] SANDBOX_ID LOCAL_PATH REMOTE_PATH
Upload a local file or directory to the sandbox.
Examples:
abx upload abc123 ./script.py /app/script.py
abx upload abc123 ./data/ /app/data/
Related commands:
abx download SANDBOX_ID REMOTE_PATH LOCAL_PATH
abx sandbox files list SANDBOX_ID --path /app
abx exec SANDBOX_ID CMD
Options:
-h, --help Show this message and exit.
Exit code: 0
download --help
$ abx download --help
Usage: cli download [OPTIONS] SANDBOX_ID REMOTE_PATH LOCAL_PATH
Download a file from the sandbox to local.
Examples:
abx download abc123 /app/result.csv ./result.csv
abx download abc123 /app/output.log .
Related commands:
abx upload SANDBOX_ID LOCAL_PATH REMOTE_PATH
abx sandbox files stat SANDBOX_ID --path REMOTE_PATH
abx sandbox files list SANDBOX_ID --path REMOTE_DIR
Options:
-h, --help Show this message and exit.
Exit code: 0
install --help
$ abx install --help
Usage: cli install [OPTIONS] TEMPLATE_REF
Install a template from TEMPLATE_REF (shortcut for 'abx template install').
Downloads and (by default) builds + deploys a template: local docker build,
ACR push, and CreateTemplate registration — cloud-side steps that can incur
Alibaba Cloud costs. Use --download-only to only fetch it into the local cache
(~/.abx/templates/) without building.
TEMPLATE_REF formats:
<name> Template name from the official index
owner/repo GitHub repo (default registry)
owner/repo@v1.0 Pinned to a tag/branch/commit
owner/repo//subdir A subdirectory within a repo
./path/to/template Local directory
Examples:
abx install python-hello --download-only # install by index name
abx install owner/repo --acr-namespace my-ns # download + build + deploy
abx install owner/repo --acr-namespace my-ns --region cn-shanghai
abx install owner/repo --download-only # download only
abx install ./my-template --acr-namespace ns # local dir + deploy
Related commands:
abx template search QUERY
abx template list
abx create --template TEMPLATE
Options:
--registry-url TEXT Registry URL (default: GitHub)
--registry-type [github|local] Registry type (auto-detected if not specified)
--token TEXT GitHub token for private repos / higher rate
limits. Prefer 'abx config set github_token'
(masked input, stored once in ~/.abx/.env);
--token is a temporary override that may leak
into shell history and the process list (env:
GITHUB_TOKEN).
-a, --alias TEXT Template alias
--download-only Only download to local cache (skip build and
deploy)
--dir PATH Download template source into this directory
instead of the cache
--acr-namespace TEXT ACR namespace for deploy
--cpu INTEGER CPU cores
--memory INTEGER Memory in MB
-y, --yes Skip confirmation prompt
-r, --region TEXT Region override for this command (default:
'abx config set region' value, else cn-
hangzhou)
-h, --help Show this message and exit.
Exit code: 0
config --help
$ abx config --help
Usage: cli config [OPTIONS] COMMAND [ARGS]...
Manage persistent credentials and CLI defaults.
Values are read from ~/.abx/config.toml and ~/.abx/.env. Environment variables
can still override the stored configuration at runtime.
Examples:
abx config init
abx config list
abx config get region
abx config set http_timeout 120
abx config set github_token Prompt for the token (masked input)
abx config delete region Remove one stored value
Related commands:
abx config init Guided setup (credentials, region, ACR, LLM)
abx config get Read one effective value
abx config set Store or update one value
abx config delete KEY Remove one stored value
Options:
-h, --help Show this message and exit.
Commands:
delete Remove one stored configuration value.
get Get a configuration value by KEY.
init Guided setup: credentials, region, ACR namespace, and the LLM API...
list List all effective configuration values and their sources.
set Set a configuration value: KEY [VALUE].
Exit code: 0
config-get --help
$ abx config get --help
Usage: cli config get [OPTIONS] KEY
Get a configuration value by KEY.
Prints the effective value: the process environment wins, then the value
stored by ``abx config set``, then the built-in default. Keys without any of
these print ``(not set)``. Sensitive keys are masked.
Available keys:
sandbox_api_key Sandbox service API key (E2B-compatible; env vars
E2B_API_KEY > SANDBOX_API_KEY; stored in ~/.abx/.env,
shown masked). ``api_key`` is accepted as an alias.
access_key_id Alibaba Cloud AccessKey ID for AK/SK auth
(template deploy, ACR push; stored in ~/.abx/.env)
access_key_secret Alibaba Cloud AccessKey Secret for AK/SK auth
(template deploy, ACR push; stored in ~/.abx/.env,
shown masked)
acr_namespace ACR namespace for template build, push, and install
(stored in ~/.abx/.env as ACR_NAMESPACE)
api_url Platform API URL
domain Envd data-plane domain
region Default region (e.g. cn-hangzhou)
http_timeout HTTP request timeout in seconds
http2 Enable HTTP/2 (true/false)
max_retries Maximum retry attempts
llm_api_key LLM API key for NL inference and the coding agent
(stored in ~/.abx/.env as ABX_LLM_API_KEY, shown
masked; a legacy config.toml value is still readable)
llm_model LLM model name (default: qwen3-coder-plus)
llm_base_url LLM API base URL, OpenAI-compatible
(default: DashScope compatible-mode)
github_token GitHub token for template downloads (stored in
~/.abx/.env, shown masked)
shortcuts All top-level shortcuts configured in
~/.abx/config.toml
shortcuts.<name> Target command of one configured shortcut
Examples:
abx config get sandbox_api_key
abx config get region
abx config list # show all values at once
abx config get shortcuts # all configured aliases
abx config get shortcuts.list # target of one alias
Related commands:
abx config list Show every effective value and its source
abx config set KEY VALUE
abx config set KEY "" Clear one stored value
Options:
-h, --help Show this message and exit.
Exit code: 0
config-set --help
$ abx config set --help
Usage: cli config set [OPTIONS] KEY [VALUE]
Set a configuration value: KEY [VALUE].
Settings are stored in ~/.abx/config.toml, except credentials
(sandbox_api_key, access_key_id, access_key_secret, acr_namespace,
llm_api_key, github_token) which are written to ~/.abx/.env using their
environment-variable names. Setting llm_api_key also removes any legacy
config.toml copy of it (the secret migrates to the 0600-protected ~/.abx/.env
storage).
Passing an empty VALUE clears the stored value for KEY instead: the key falls
back to its built-in default or becomes not set. An empty string is never
stored as a credential or override. Environment variables that are still
exported keep overriding the key at runtime; their values are never printed.
Clearing llm_api_key removes both the ~/.abx/.env entry and any legacy
config.toml copy.
In an interactive terminal VALUE may be omitted: sensitive keys (github_token,
sandbox_api_key, access_key_secret, llm_api_key) are then read through the
masked (asterisk) input and the typed value is never echoed; other keys use a
visible prompt. Pressing Enter at the prompt cancels without changing
anything. In CI / non-interactive sessions VALUE is required.
Available keys (expected value):
sandbox_api_key Sandbox service API key, E2B-compatible (string;
env vars E2B_API_KEY > SANDBOX_API_KEY).
``api_key`` is accepted as an alias.
access_key_id Alibaba Cloud AccessKey ID for AK/SK auth, used by
template deploy and ACR push (string)
access_key_secret Alibaba Cloud AccessKey Secret for AK/SK auth, used by
template deploy and ACR push (string)
acr_namespace ACR namespace for template build, push, and install
(string; stored in ~/.abx/.env as ACR_NAMESPACE)
api_url Platform API URL (e.g. https://api.cn-hangzhou.e2b.fc.aliyuncs.com)
domain Envd data-plane domain (e.g. cn-hangzhou.e2b.fc.aliyuncs.com)
region Default region (e.g. cn-hangzhou, cn-shanghai)
http_timeout HTTP request timeout in seconds (number, e.g. 120)
http2 Enable HTTP/2 (true/false)
max_retries Maximum retry attempts (integer, e.g. 3)
llm_api_key LLM API key for NL inference and the coding agent,
e.g. a DashScope/ModelStudio key (string; stored in
~/.abx/.env as ABX_LLM_API_KEY)
llm_model LLM model name (default: qwen3-coder-plus)
llm_base_url LLM API base URL, OpenAI-compatible (string;
default: DashScope compatible-mode)
github_token GitHub token for template downloads, used by
'abx template install' / 'abx template search'
(string; stored in ~/.abx/.env)
shortcuts.<name> Top-level shortcut. The value is the command path
without the "abx" prefix, for example
"template init" (not "abx template init"):
'abx config set shortcuts.ps "sandbox process list"';
an empty VALUE removes the shortcut
Examples:
abx config set sandbox_api_key YOUR_API_KEY
abx config set access_key_id YOUR_ACCESS_KEY_ID
abx config set access_key_secret YOUR_ACCESS_KEY_SECRET
abx config set acr_namespace YOUR_ACR_NAMESPACE
abx config set region cn-hangzhou
abx config set http_timeout 120
abx config set http2 false
abx config set llm_api_key YOUR_DASHSCOPE_OR_LLM_KEY
abx config set region "" # clear the stored region
abx config set sandbox_api_key "" # remove the stored sandbox API key
abx config set github_token # masked prompt (VALUE omitted)
abx config set github_token YOUR_GITHUB_TOKEN
abx config set github_token "" # remove the stored token
abx config set shortcuts.ps "sandbox process list"
abx config set shortcuts.ps "" # remove the 'ps' shortcut
Related commands:
abx config get KEY Verify the effective value
abx config list Review effective values and sources
abx config delete KEY Remove one stored value
Options:
-h, --help Show this message and exit.
Exit code: 0
config-list --help
$ abx config list --help
Usage: cli config list [OPTIONS]
List all effective configuration values and their sources.
Values are grouped by function — Sandbox authentication, Alibaba Cloud
credentials, connection, LLM, integrations, and shortcuts — in a stable order.
Group titles are display-only: ``config get`` and ``config set`` keep taking
the bare key names, and ``--json`` output stays a flat ``{key: value}`` map.
Sources: ``(env)`` a process environment variable, ``(user)`` a value in
``./.env`` or stored with ``abx config set``, ``(default)`` a built-in
default, and ``(not set)`` when no value exists anywhere. A set environment
variable wins over either file. ``./.env`` wins over ``~/.abx`` for a key it
sets; a key it omits still comes from ``~/.abx``. Sensitive values are always
masked.
Examples:
abx config list
abx --json config list
abx config get http_timeout
Related commands:
abx config get KEY Inspect one effective value
abx config set KEY VALUE
abx config delete KEY Remove one stored value
Options:
-h, --help Show this message and exit.
Exit code: 0
config-init --help
$ abx config init --help
Usage: cli config init [OPTIONS]
Guided setup: credentials, region, ACR namespace, and the LLM API key.
In a terminal this prompts for the platform API key, the default region, the
LLM API key used for AI template generation and NL inference (``abx create
"<description>"``; consumed by Qwen Code), the ACR namespace, and the Alibaba
Cloud AccessKey pair. The last three are what ``abx install`` and ``abx
template deploy`` need in order to build and push an image. Press Enter to
skip a prompt. Secrets are typed with asterisk feedback (never echoed) when
the terminal supports it, and stored in ~/.abx/.env; the region goes to
~/.abx/config.toml. The namespace is stored as ``ACR_NAMESPACE``.
In non-TTY environments (CI, piped input) the wizard never blocks: it prints
the equivalent non-interactive ``abx config set ...`` commands and exits
successfully. ``--yes`` behaves the same way.
``--reset-shortcuts`` restores the default ``[shortcuts]`` section of
~/.abx/config.toml (and nothing else), then exits.
Examples:
abx config init
abx config init --yes # print non-interactive commands
abx config init --reset-shortcuts # restore default shortcuts only
Related commands:
abx config list Review effective values and sources
abx config set KEY VALUE Set one value directly
abx config set KEY "" Clear one stored value
Options:
-y, --yes Non-interactive: print the equivalent commands instead of
prompting
--reset-shortcuts Reset [shortcuts] section to defaults
-h, --help Show this message and exit.
Exit code: 0
template --help
$ abx template --help
Usage: cli template [OPTIONS] COMMAND [ARGS]...
Discover, scaffold, build, and manage sandbox templates.
Examples:
abx template search python
abx template init --template python --name my-template
abx template list
Related commands:
abx create --template TEMPLATE Launch a sandbox from a template
abx install TEMPLATE_REF Install shortcut
abx config --help Configure credentials and region
Options:
-h, --help Show this message and exit.
Commands:
build Build Docker image locally, push to ACR, and create a sandbox...
create Create a sandbox template from an existing container image.
delete Delete a custom template from the remote platform.
deploy Build, push, and create template in one step (alias of 'template...
info Show details for a template ID.
init Scaffold a new sandbox template project.
install Download a template and (by default) build + deploy it.
list List custom templates registered for the current account.
push Push a locally-built image to Alibaba Cloud ACR.
search Search the template catalog by name, tag, or description.
Exit code: 0
template-list --help
$ abx template list --help
Usage: cli template list [OPTIONS]
List custom templates registered for the current account.
By default this queries the configured platform endpoint. Pass --official-api
to use the Alibaba Cloud FCSandbox API with AK/SK. This command does not
search the community template index.
Examples:
abx template list
abx template list --official-api
abx template list --region cn-shanghai
abx --json template list
Related commands:
abx template info TEMPLATE_ID
abx template search QUERY
abx template install TEMPLATE_REF
Options:
--official-api Query templates via the official Alibaba Cloud FCSandbox
API (AK/SK).
-r, --region TEXT Region override for this command (default: 'abx config set
region' value, else cn-hangzhou)
-h, --help Show this message and exit.
Exit code: 0
template-info --help
$ abx template info --help
Usage: cli template info [OPTIONS] TEMPLATE_ID
Show details for a template ID.
Pass --official-api to use the Alibaba Cloud FCSandbox GetTemplate API; that
mode requires configured AccessKey credentials.
Examples:
abx template info tmpl-abc123
abx template info tmpl-abc123 --official-api
abx template info tmpl-abc123 --region cn-shanghai
abx --json template info tmpl-abc123
Related commands:
abx template list
abx create --template TEMPLATE_ID
abx template delete TEMPLATE_ID
Options:
--official-api Query the template via the official Alibaba Cloud FCSandbox
API (AK/SK).
-r, --region TEXT Region override for this command (default: 'abx config set
region' value, else cn-hangzhou)
-h, --help Show this message and exit.
Exit code: 0
template-build --help
$ abx template build --help
Usage: cli template build [OPTIONS] TEMPLATE_DIR
Build Docker image locally, push to ACR, and create a sandbox template.
Full pipeline with cloud side effects: the local docker build is local-only,
but the ACR push and the remote template registration can incur Alibaba Cloud
costs (ACR storage/traffic, template resources).
Supports two modes:
--official-api (default):
local docker build → ACR push → official CreateTemplate API (envdInject).
Requires AK/SK credentials and 'agent-sandbox[alicloud]' extra.
--legacy-api:
local docker build → ACR push → legacy v3/v2 platform API.
Use --legacy-api to keep the old behaviour.
Requires Docker daemon running and ACR credentials. In automation/CI, pass
--acr-namespace and TEMPLATE_DIR explicitly instead of relying on
ACR_NAMESPACE / ABX_TEMPLATE_DIR environment variables or .env files, so the
build cannot drift with the surrounding environment.
Examples:
abx template build ./examples/templates/python-hello \
--acr-namespace my-ns --acr-repo python-hello
abx template build ./my-template \
--acr-namespace prod --acree-instance-id cri-xxx
abx template build ./my-template \
--acr-namespace prod --disk-size 10240 --internet-access
abx template build ./my-template \
--acr-namespace prod --legacy-api
abx template build ./my-template --acr-namespace prod --region cn-shanghai
Related commands:
abx template init DIRECTORY Scaffold template source files
abx template push IMAGE Push an existing local image only
abx create --template ID Launch the completed template
Options:
--acr-registry TEXT ACR registry host
--acr-namespace TEXT ACR namespace (env: ACR_NAMESPACE, or set in
.env file)
--acr-repo TEXT ACR repository name (defaults to template.yaml
name or dir name)
--acr-username TEXT ACR login username (defaults to AccessKey from
.env)
--acr-password TEXT ACR login password (defaults to AccessSecret
from .env)
--acree-instance-id TEXT ACR EE instance ID (cri-...)
--vpc-id TEXT VPC ID for ACR EE
--vswitch-ids TEXT Comma-separated VSwitch IDs
--security-group-id TEXT Security group ID
-a, --alias TEXT Template alias
-t, --tag TEXT Docker image tag
--platform TEXT Target platform
--cpu INTEGER CPU cores (default: from template.yaml
resources.cpu, fallback 2)
--memory INTEGER Memory in MB (default: from template.yaml
resources.memory, fallback 2048)
--start-cmd TEXT Container start command
--ready-cmd TEXT Container readiness check command
--timeout INTEGER Build timeout in seconds
-f, --dockerfile PATH Custom Dockerfile path
--disk-size INTEGER Disk size in MB (official API only)
--internet-access / --no-internet-access
Internet access (default: platform decides;
official API only)
--official-api / --legacy-api Use official CreateTemplate API (default) or
legacy v3/v2
--team-id TEXT Team ID for official API (or env TEAM_ID /
E2B_TEAM_ID)
--envd-inject / --no-envd-inject
Enable envd injection (default False)
--generation INTEGER Sandbox generation (default: template.yaml
'generation', otherwise 1). 1=first-gen
(rund), 2=second-gen MicroVM.
--target-image TEXT Destination image ref for envd copy (auto-
derived with random suffix if omitted)
-y, --yes Skip confirmation prompt
-v, --verbose Verbose output (DEBUG level)
-r, --region TEXT Region override for this command (default:
'abx config set region' value, else cn-
hangzhou)
-h, --help Show this message and exit.
Exit code: 0
template-init --help
$ abx template init --help
Usage: cli template init [OPTIONS] [DIRECTORY]
Scaffold a new sandbox template project.
Creates a ready-to-build template directory with template.yaml, Dockerfile,
and (depending on the case) a commands.py file. Nothing is built, pushed,
deployed, or turned into a sandbox.
When DIRECTORY is omitted a new ./<name> subdirectory is created (derived from
--name, the scaffold case, or the fetched template).
A DIRECTORY that contains whitespace or CJK text is a natural-language
description: Qwen Code generates Dockerfile, commands.py (the HTTP server) and
template.yaml into ./<name>/ and stops. An interactive terminal is asked for
that directory first (Enter keeps ./<name>/). A path token (my-app, ./my app)
stays a directory.
--adopt adapts a project that already has source code and no template files.
The agent sees a copy, and only Dockerfile, commands.py, template.yaml and a
generated .dockerignore are written back, after you confirm. Nothing is built
or deployed.
Examples:
abx template init --list # List built-in cases
abx template init -t python # Creates ./python/
abx template init -t python --name myapp # Creates ./myapp/
abx template init -t python ./my-template # Explicit directory
abx template init --from owner/repo # Creates ./<template-name>/
abx template init "a python data science env" # AI files only, no build
abx template init -y "a node.js api server" # non-interactive AI files
abx template init --adopt . --hint "port 8080" # adapt this project
abx template init --adopt ./app --dry-run # show what would be sent
Related commands:
abx template deploy DIRECTORY
abx template install TEMPLATE_REF
abx create --template TEMPLATE
abx create "DESCRIPTION" # generate, build, deploy, and create
Options:
-t, --template TEXT Built-in scaffold case (python, node, minimal)
--from TEXT Fetch template source from a registry ref (owner/repo,
local path)
--name TEXT Template name (default: case name, or fetched template
name)
--list List available scaffold cases
--force Overwrite existing files
--adopt Adapt an existing source project: the coding agent adds
the template files (Dockerfile, commands.py,
template.yaml). DIRECTORY is the project (default: .).
--hint TEXT With --adopt: what the code cannot tell the agent (ports,
services).
--dry-run With --adopt: list what would be sent to the model.
Nothing is sent or written.
-v, --verbose Verbose output (DEBUG level)
-y, --yes Skip confirmation prompts: the template directory,
description clarification, and (with --adopt) the send
and write prompts. Required for non-interactive AI
generation. Does not build or deploy. Replacing an
existing Dockerfile still needs --force when there is no
interactive preview.
-h, --help Show this message and exit.
Exit code: 0
template-delete --help
$ abx template delete --help
Usage: cli template delete [OPTIONS] TEMPLATE_ID
Delete a custom template from the remote platform.
This irreversible operation does not remove the local template cache.
Confirmation is required unless --yes is supplied.
Examples:
abx template delete tmpl-abc123
abx template delete tmpl-abc123 --yes --region cn-shanghai
Related commands:
abx template info TEMPLATE_ID Verify the target before deletion
abx template list Confirm the template was removed
abx template install REF Reinstall a template
Options:
-y, --yes Skip confirmation prompt
-r, --region TEXT Region override for this command (default: 'abx config set
region' value, else cn-hangzhou)
-h, --help Show this message and exit.
Exit code: 0
template-install --help
$ abx template install --help
Usage: cli template install [OPTIONS] TEMPLATE_REF
Download a template and (by default) build + deploy it.
By default, install downloads the template, then runs docker build, pushes to
ACR, and creates a sandbox template via the official API — cloud-side
operations that can incur Alibaba Cloud costs (ACR storage/traffic, template
resources). Use --download-only to skip the build/deploy step and only
download to the local cache (~/.abx/templates/).
Use --dir <path> to download into a specific directory instead of the cache.
TEMPLATE_REF can be a bare template name from the official index (Easy-
Sandbox/awesome-templates) or a registry reference. Bare names are resolved
against the remote index; entries may pin a version, in which case that pinned
ref is honoured.
A GitHub token (private repos / higher rate limits) is taken from --token,
then the GITHUB_TOKEN environment variable, then ./.env, then the stored
github_token; prefer 'abx config set github_token' - --token may leak into
shell history and process listings.
Examples:
abx template install python-hello --download-only # install by index name
abx template install owner/repo --acr-namespace my-ns
abx template install owner/repo@v1.0 --download-only
abx template install owner/repo//subdir --dir ./local-copy
abx template install owner/repo --acr-namespace my-ns --region cn-shanghai
Related commands:
abx template search QUERY Find a template in the index
abx template list List registered templates
abx create --template ID Launch the installed template
Options:
--registry-url TEXT Registry URL (default: GitHub)
--registry-type [github|local] Registry type (auto-detected if not specified)
--token TEXT GitHub token for private repos / higher rate
limits. Prefer 'abx config set github_token'
(masked input, stored once in ~/.abx/.env);
--token is a temporary override that may leak
into shell history and the process list (env:
GITHUB_TOKEN).
-a, --alias TEXT Template alias
--download-only Only download to local cache (skip build and
deploy)
--dir PATH Download template source into this directory
instead of the cache
--acr-namespace TEXT ACR namespace for deploy (env: ACR_NAMESPACE,
or set in .env file)
--cpu INTEGER CPU cores (default: from template.yaml or 2)
--memory INTEGER Memory in MB (default: from template.yaml or
2048)
-y, --yes Skip confirmation prompt
-r, --region TEXT Region override for this command (default:
'abx config set region' value, else cn-
hangzhou)
-h, --help Show this message and exit.
Exit code: 0
mcp --help
$ abx mcp --help
Usage: cli mcp [OPTIONS] COMMAND [ARGS]...
Configure and run Agent Sandbox as an MCP server.
Use local STDIO transport for IDE integrations, or generate a Streamable HTTP
deployment artifact for manual deployment to Alibaba Cloud FC.
Examples:
abx mcp install --target cursor
abx mcp start
abx mcp start --http --background
abx mcp stop
abx mcp deploy --generate-token --output-dir ./mcp-artifact
Related commands:
abx config set sandbox_api_key VALUE Configure sandbox authentication
abx mcp status Inspect local MCP configuration
abx mcp stop Stop the local MCP server
Options:
-h, --help Show this message and exit.
Commands:
deploy Generate an Alibaba Cloud FC deployment artifact.
install Install MCP Server configuration to a target IDE.
start Start the MCP server and print its configuration to stderr.
status Show MCP tools, authentication state, and IDE installation status.
stop Stop the local MCP server started by 'abx mcp start'.
Exit code: 0
mcp-deploy --help
$ abx mcp deploy --help
Usage: cli mcp deploy [OPTIONS]
Generate an Alibaba Cloud FC deployment artifact.
Creates a Streamable HTTP ASGI application artifact and prints manual FC
deployment steps. Automatic FC API deployment is not implemented.
The artifact contains ``requirements.txt``, ``app.py`` (ASGI entry point), and
``config.yaml`` (a YAML deployment manifest with FC function settings and
environment variables).
``--region`` overrides the FC region for this invocation; without it the
region comes from ``abx config set region`` / the ``SANDBOX_REGION``
environment variable and defaults to ``cn-hangzhou``.
A non-empty Bearer token is required (--generate-token or --auth-token-file).
POST and DELETE /mcp are implemented. GET /mcp returns 405 until SSE server
notifications exist. The function environment sets SANDBOX_REGION to the
selected region.
Examples:
abx mcp deploy --generate-token --api-key $E2B_API_KEY
abx mcp deploy --auth-token-file ./token.txt --region cn-shanghai
abx mcp deploy --generate-token --output-dir ./deploy-artifact
Related commands:
abx mcp start Run the local STDIO server
abx mcp status Inspect MCP authentication state
abx config set sandbox_api_key VALUE Configure sandbox authentication
Options:
--name TEXT FC function name for the artifact.
-r, --region TEXT Region override for this command (default:
'abx config set region' value, else cn-
hangzhou)
--template TEXT Default sandbox template for MCP sessions.
--memory INTEGER FC function memory (MB).
--timeout INTEGER FC function timeout (s).
--auth-token-file PATH Path to a non-empty Bearer token file.
--generate-token Auto-generate a random Bearer token.
--enable-session-affinity / --no-session-affinity
Enable Mcp-Session-Id affinity (requires FC
MCP support).
--api-key TEXT E2B_API_KEY to inject into the FC function
env.
--custom-domain TEXT Custom domain for the MCP endpoint.
--output-dir PATH Write the FC deployment artifact to this
directory.
-h, --help Show this message and exit.
Exit code: 0
mcp-install --help
$ abx mcp install --help
Usage: cli mcp install [OPTIONS]
Install MCP Server configuration to a target IDE.
Generates the correct MCP config and merges it into the selected IDE's
configuration file. Supported targets are cursor, claude, and vscode.
Examples:
abx mcp install --target cursor
abx mcp install --target claude
abx mcp install --target vscode
Related commands:
abx mcp status Verify installed IDE configurations
abx mcp start Run the configured STDIO server
abx config get sandbox_api_key
Options:
--target [cursor|claude|vscode]
Target IDE for MCP installation. [required]
-h, --help Show this message and exit.
Exit code: 0
mcp-start --help
$ abx mcp start --help
Usage: cli mcp start [OPTIONS]
Start the MCP server and print its configuration to stderr.
The default transport is STDIO: an IDE writes JSON-RPC to stdin and reads
responses from stdout. Run it in a terminal to see the configuration and stop
it with Ctrl-C or 'abx mcp stop'.
--http listens for Streamable HTTP. --background detaches that HTTP server;
STDIO cannot keep a client attached after detach, so --background starts HTTP.
Examples:
abx mcp start
abx mcp start --template python-hello
abx mcp start --http --port 9000
abx mcp start --http --background
abx mcp stop
Related commands:
abx mcp install --target cursor Register the STDIO command in an IDE
abx mcp stop Stop the local MCP server
abx mcp status Check authentication and IDE setup
Options:
--template TEXT Default sandbox template ID or alias (default: code-
interpreter-v1).
--api-key TEXT API key override.
--api-url TEXT API URL override.
--domain TEXT Domain override.
--http Serve Streamable HTTP instead of STDIO.
--host TEXT HTTP bind address. [default: 127.0.0.1]
--port INTEGER HTTP bind port. [default: 9000]
--auth-token TEXT Bearer token for the HTTP server. Required when --host is
not loopback.
--background Detach an HTTP server. Stop it later with 'abx mcp stop'.
-h, --help Show this message and exit.
Exit code: 0
mcp-stop --help
$ abx mcp stop --help
Usage: cli mcp stop [OPTIONS]
Stop the local MCP server started by 'abx mcp start'.
Sends SIGTERM to the recorded pid (STDIO foreground or HTTP background) and
waits for it to exit. Sandboxes owned by that server are destroyed during its
shutdown.
Examples:
abx mcp stop
Related commands:
abx mcp start Start STDIO in the foreground
abx mcp start --http --background
abx mcp status Inspect configuration and whether a server is running
Options:
-h, --help Show this message and exit.
Exit code: 0
mcp-status --help
$ abx mcp status --help
Usage: cli mcp status [OPTIONS]
Show MCP tools, authentication state, and IDE installation status.
Examples:
abx mcp status
abx --json mcp status
Related commands:
abx mcp install --target cursor
abx mcp start
abx config get sandbox_api_key
Options:
-h, --help Show this message and exit.
Exit code: 0
deploy --help
$ abx deploy --help
Usage: cli deploy [OPTIONS] [PATH]
Publish a template project: build, push to ACR, register the template.
Runs the fixed pipeline: docker build, push the image to ACR, register the
template, and wait until it is ready. No LLM is involved. PATH is the template
directory (default: .). It must contain a Dockerfile; template.yaml supplies
the template name and resources.
To author the files first, use 'abx template init': --adopt for an existing
project, a natural-language description to let the AI write the files, or -t
for a scaffold.
Accepts every option of 'abx template deploy' (--acr-namespace, --alias,
--yes, -v/--verbose, ...).
Examples:
abx deploy --acr-namespace my-ns # publish ./ as a template
abx deploy ./my-template --yes # non-interactive
abx deploy ./my-template -v # with debug logs
Typical flow:
abx template init --adopt . # 1a. author from a project
abx template init "a python data science env" # 1b. author from a description
abx deploy ./<name> --acr-namespace my-ns # 2. publish
abx create --template <TEMPLATE_ID> # 3. launch a sandbox
Related commands:
abx template init Author Dockerfile / template.yaml (AI optional)
abx template deploy DIR The same pipeline with a required DIRECTORY
abx create "DESCRIPTION" Author + publish + launch in one go
Options:
--acr-registry TEXT ACR registry host
--acr-namespace TEXT ACR namespace (env: ACR_NAMESPACE, or set in
.env file)
--acr-repo TEXT ACR repository name (defaults to template.yaml
name or dir name)
--acr-username TEXT ACR login username (defaults to AccessKey from
.env)
--acr-password TEXT ACR login password (defaults to AccessSecret
from .env)
--acree-instance-id TEXT ACR EE instance ID (cri-...)
--vpc-id TEXT VPC ID for ACR EE
--vswitch-ids TEXT Comma-separated VSwitch IDs
--security-group-id TEXT Security group ID
-a, --alias TEXT Template alias
-t, --tag TEXT Docker image tag
--platform TEXT Target platform
--cpu INTEGER CPU cores (default: from template.yaml
resources.cpu, fallback 2)
--memory INTEGER Memory in MB (default: from template.yaml
resources.memory, fallback 2048)
--start-cmd TEXT Container start command
--ready-cmd TEXT Container readiness check command
--timeout INTEGER Build timeout in seconds
-f, --dockerfile PATH Custom Dockerfile path
--disk-size INTEGER Disk size in MB (official API only)
--internet-access / --no-internet-access
Internet access (default: platform decides;
official API only)
--official-api / --legacy-api Use official CreateTemplate API (default) or
legacy v3/v2
--team-id TEXT Team ID for official API (or env TEAM_ID /
E2B_TEAM_ID)
--envd-inject / --no-envd-inject
Enable envd injection (default False)
--generation INTEGER Sandbox generation (default: template.yaml
'generation', otherwise 1). 1=first-gen
(rund), 2=second-gen MicroVM.
--target-image TEXT Destination image ref for envd copy (auto-
derived with random suffix if omitted)
-y, --yes Skip confirmation prompt
-v, --verbose Verbose output (DEBUG level)
-r, --region TEXT Region override for this command (default:
'abx config set region' value, else cn-
hangzhou)
-h, --help Show this message and exit.
Exit code: 0
顶层 init（abx template init 快捷别名）
$ abx init --help
Usage: cli init [OPTIONS] [DIRECTORY]
Scaffold a new sandbox template project.
Creates a ready-to-build template directory with template.yaml, Dockerfile,
and (depending on the case) a commands.py file. Nothing is built, pushed,
deployed, or turned into a sandbox.
When DIRECTORY is omitted a new ./<name> subdirectory is created (derived from
--name, the scaffold case, or the fetched template).
A DIRECTORY that contains whitespace or CJK text is a natural-language
description: Qwen Code generates Dockerfile, commands.py (the HTTP server) and
template.yaml into ./<name>/ and stops. An interactive terminal is asked for
that directory first (Enter keeps ./<name>/). A path token (my-app, ./my app)
stays a directory.
--adopt adapts a project that already has source code and no template files.
The agent sees a copy, and only Dockerfile, commands.py, template.yaml and a
generated .dockerignore are written back, after you confirm. Nothing is built
or deployed.
Examples:
abx template init --list # List built-in cases
abx template init -t python # Creates ./python/
abx template init -t python --name myapp # Creates ./myapp/
abx template init -t python ./my-template # Explicit directory
abx template init --from owner/repo # Creates ./<template-name>/
abx template init "a python data science env" # AI files only, no build
abx template init -y "a node.js api server" # non-interactive AI files
abx template init --adopt . --hint "port 8080" # adapt this project
abx template init --adopt ./app --dry-run # show what would be sent
Related commands:
abx template deploy DIRECTORY
abx template install TEMPLATE_REF
abx create --template TEMPLATE
abx create "DESCRIPTION" # generate, build, deploy, and create
Options:
-t, --template TEXT Built-in scaffold case (python, node, minimal)
--from TEXT Fetch template source from a registry ref (owner/repo,
local path)
--name TEXT Template name (default: case name, or fetched template
name)
--list List available scaffold cases
--force Overwrite existing files
--adopt Adapt an existing source project: the coding agent adds
the template files (Dockerfile, commands.py,
template.yaml). DIRECTORY is the project (default: .).
--hint TEXT With --adopt: what the code cannot tell the agent (ports,
services).
--dry-run With --adopt: list what would be sent to the model.
Nothing is sent or written.
-v, --verbose Verbose output (DEBUG level)
-y, --yes Skip confirmation prompts: the template directory,
description clarification, and (with --adopt) the send
and write prompts. Required for non-interactive AI
generation. Does not build or deploy. Replacing an
existing Dockerfile still needs --force when there is no
interactive preview.
-h, --help Show this message and exit.
Exit code: 0