Use sandboxes

A sandbox is an isolated code or skill environment. The sandbox command group covers its full lifecycle—create, list, show, update, delete—and its operations: run commands in a session, open an interactive terminal, transfer files, open a web preview, inject subscription credentials, and manage sessions.

run, shell, cp, web, and login share a set of session and sandbox flags: -s, --session <id> (session id, reused if it exists, else generated), --tool-id <id> (sandbox id), --type <type> (sandbox type code | skill, default code), --auto-create (always create a new sandbox, even if some already exist), -r, --region <region> (Volcengine region), and -p, --project <name> (AgentKit project, default default). sessions, logs, and rm accept only the subset used to resolve a sandbox; see each command’s table for its exact flags. attach is an alias for shell.When --tool-id is omitted and --auto-create is not set, the CLI looks for a sandbox of the requested type in the project: exactly one is used automatically; when several exist the command fails and asks you to pass --tool-id; when none exist you need --auto-create. Passing --auto-create always provisions a brand-new sandbox—even when the project already has some—and waits for it to become ready before use. Having several code sandboxes in a project is common, so run agentkit sandbox list to find the target id and pass it via --tool-id.

sandbox create

Create a sandbox (a code or skill environment).

Flag / Argument	Description	Default
`--name <name>`	Sandbox name (required).	—
`--type <type>`	Sandbox type: `code` \| `skill`.	`code`
`-r, --region <region>`	Volcengine region.	from env
`--description <text>`	Description.	—
`--command <command>`	Container start command.	—
`--image-url <url>`	Container image url.	—
`--port <port>`	Container port.	—
`-p, --project <name>`	Project name.	`default`
`--role-name <role>`	IAM role name.	—
`--apmplus`	Enable APMPlus.	—
`--cpu <milli>`	CPU in milli-cores.	—
`--memory <mb>`	Memory in MB.	—
`--enable-security`	Enable the security sandbox.	—
`--enable-tos`	Mount TOS into the sandbox.	—
`--env <KEY=VALUE>`	Environment variable (repeatable).	—
`--json <jsonString>`	Extra fields as a JSON object, merged into the request body.	—

sandbox create provisions cloud compute resources that may incur charges while they exist. Confirm the project, region, resource size, and image source before creating one. Delete the sandbox with sandbox delete when it is no longer needed.

agentkit sandbox create --name dev-sandbox --type code --cpu 1000 --memory 2048

The following example creates a web sandbox from a custom image. Replace the image URL with one that your project can access:

agentkit sandbox create \
  --name web-sandbox \
  --image-url your-registry.example.com/team/python-web:latest \
  --command "python -m http.server 8080" \
  --port 8080

sandbox list

List sandboxes (the code and skill environments in the project).

Flag / Argument	Description	Default
`-r, --region <region>`	Volcengine region.	auto-detect
`-p, --project <name>`	Project name.	`default`
`--type <type>`	Filter by sandbox type: `code` \| `skill`.	—
`--json`	Output raw JSON.	`false`

agentkit sandbox list --type code

sandbox show

Show a sandbox’s details.

Flag / Argument	Description	Default
`<id>`	Sandbox id, e.g. `t-xxxxxxxx` (required).	—
`-r, --region <region>`	Volcengine region.	auto-detect
`--json`	Output raw JSON.	`false`

agentkit sandbox show t-12345678

sandbox update

Update a sandbox’s configuration.

Flag / Argument	Description	Default
`<id>`	Sandbox id, e.g. `t-xxxxxxxx` (required).	—
`-r, --region <region>`	Volcengine region.	auto-detect
`--description <text>`	Description.	—
`--command <command>`	Container start command.	—
`--image-url <url>`	Container image url.	—
`--port <port>`	Container port.	—
`--apmplus`	Enable APMPlus.	—
`--json <jsonString>`	Extra fields as a JSON object, merged into the request body.	—

agentkit sandbox update t-12345678 --description "Dev sandbox" --port 9090

sandbox delete

Delete a sandbox—the environment itself. To delete a single session instead, use sandbox rm.

Deleting a sandbox cannot be undone. Its sessions and files that were not stored elsewhere may be lost with it. Confirm the sandbox ID and download or persist required files before proceeding.

Flag / Argument	Description	Default
`<id>`	Sandbox id, e.g. `t-xxxxxxxx` (required).	—
`-r, --region <region>`	Volcengine region.	auto-detect
`-y, --yes`	Skip the confirmation prompt.	`false`

agentkit sandbox delete t-12345678 --yes

sandbox run

Run a command in a sandbox session and print its output.

Flag / Argument	Description	Default
`<command>`	Command to run (required)	None
`--json`	Print the raw result (`{ output, ... }`)	`false`
`--cwd <dir>`	Working directory to run in	None
`--model-name <name>`	Model for the sandbox coding agent	None
`--model-api-key <key>`	Model API key	None
`--model-provider <provider>`	Model provider	None
`--cpu <milli>`	CPU milli-cores when `--auto-create`	None
`--memory <mb>`	Memory MB when `--auto-create`	None
`--timeout <seconds>`	Max seconds to wait for the command before aborting; `0` disables the limit	`30`
`-s, --session <id>`	Session id (reused if it exists; else generated)	None
`--tool-id <id>`	Sandbox id. Auto-resolved when omitted: used automatically if the project has exactly one sandbox of this type, required when there are several, and needs `--auto-create` when there are none	Auto-resolved
`--type <type>`	Sandbox type: `code` \| `skill`	`code`
`--auto-create`	Always create a new sandbox, even if some already exist	`false`
`-r, --region <region>`	Volcengine region	None
`-p, --project <name>`	AgentKit project	`default`

agentkit sandbox run "ls -la" --session my-session

A one-shot run waits for the command to finish, so an interactive program—an editor, a REPL, or codex launched with no arguments—would block until the timeout elapses. Open an interactive session with agentkit sandbox shell instead, or raise --timeout (or set it to 0) for long-running non-interactive jobs.

sandbox shell

Open an interactive terminal in a sandbox session (Ctrl-] to detach). sandbox attach is an alias for this command.

Flag / Argument	Description	Default
`--tmux`	Attach/create a persistent tmux session	`false`
`--command <cmd>`	Run an initial command after attaching	None
`--workspace <dir>`	Sandbox workspace root	None
`--src-dir <path>`	Local file/dir to upload before attaching	None
`--dst-dir <dir>`	Remote destination for `--src-dir` (under `--workspace`)	None
`--model-name <name>`	Model for the sandbox coding agent	None
`--model-api-key <key>`	Model API key	None
`--model-provider <provider>`	Model provider	None
`-s, --session <id>`	Session id (reused if it exists; else generated)	None
`--tool-id <id>`	Sandbox id. Auto-resolved when omitted: used automatically if the project has exactly one sandbox of this type, required when there are several, and needs `--auto-create` when there are none	Auto-resolved
`--type <type>`	Sandbox type: `code` \| `skill`	`code`
`--auto-create`	Always create a new sandbox, even if some already exist	`false`
`-r, --region <region>`	Volcengine region	None
`-p, --project <name>`	AgentKit project	`default`

agentkit sandbox shell --tmux --session my-session

sandbox cp

Copy files to/from a sandbox session — prefix the remote side with :.

Flag / Argument	Description	Default
`<src>`	Source path (prefix remote side with `:`, required)	None
`<dst>`	Destination path (prefix remote side with `:`, required)	None
`--overwrite`	Overwrite an existing local file on download	`false`
`-s, --session <id>`	Session id (reused if it exists; else generated)	None
`--tool-id <id>`	Sandbox id. Auto-resolved when omitted: used automatically if the project has exactly one sandbox of this type, required when there are several, and needs `--auto-create` when there are none	Auto-resolved
`--type <type>`	Sandbox type: `code` \| `skill`	`code`
`--auto-create`	Always create a new sandbox, even if some already exist	`false`
`-r, --region <region>`	Volcengine region	None
`-p, --project <name>`	AgentKit project	`default`

# Upload a local file
agentkit sandbox cp ./local.txt :/workspace/local.txt --session my-session

# Download a remote file
agentkit sandbox cp :/workspace/report.json ./report.json --session my-session

# Allow replacement when the destination already exists
agentkit sandbox cp :/workspace/report.json ./report.json --session my-session --overwrite

sandbox web

Open the sandbox web preview in a browser.

Flag / Argument	Description	Default
`--no-open`	Just print the URL	`false`
`-s, --session <id>`	Session id (reused if it exists; else generated)	None
`--tool-id <id>`	Sandbox id. Auto-resolved when omitted: used automatically if the project has exactly one sandbox of this type, required when there are several, and needs `--auto-create` when there are none	Auto-resolved
`--type <type>`	Sandbox type: `code` \| `skill`	`code`
`--auto-create`	Always create a new sandbox, even if some already exist	`false`
`-r, --region <region>`	Volcengine region	None
`-p, --project <name>`	AgentKit project	`default`

agentkit sandbox web --session my-session

This command copies a local subscription credential into a remote sandbox session. Use it only with a trusted sandbox and a dedicated session, and do not share that session with others. When finished, delete the session with agentkit sandbox rm <session> -y.

Inject your local codex/claude subscription into a sandbox session.

Flag / Argument	Description	Default
`--provider <provider>`	`codex` \| `claude`	`codex`
`--auth-file <path>`	Use a specific local credential file	None
`--codex-home <dir>`	Local codex home	`$CODEX_HOME` or `~/.codex`
`-s, --session <id>`	Session id (reused if it exists; else generated)	None
`--tool-id <id>`	Sandbox id. Auto-resolved when omitted: used automatically if the project has exactly one sandbox of this type, required when there are several, and needs `--auto-create` when there are none	Auto-resolved
`--type <type>`	Sandbox type: `code` \| `skill`	`code`
`--auto-create`	Always create a new sandbox, even if some already exist	`false`
`-r, --region <region>`	Volcengine region	None
`-p, --project <name>`	AgentKit project	`default`

agentkit sandbox login --provider claude --session my-session

sandbox sessions

List active sandbox sessions.

Flag / Argument	Description	Default
`--tool-id <id>`	Sandbox id. Auto-resolved when omitted: used automatically if the project has exactly one sandbox of this type, required when there are several, and needs `--auto-create` when there are none	Auto-resolved
`--type <type>`	Sandbox type: `code` \| `skill`	`code`
`-r, --region <region>`	Volcengine region	None
`-p, --project <name>`	AgentKit project	`default`
`--json`	Output raw JSON	`false`

agentkit sandbox sessions

sandbox logs

Show a sandbox session’s logs.

Flag / Argument	Description	Default
`[session]`	Session id	None
`--tool-id <id>`	Sandbox id. Auto-resolved when omitted: used automatically if the project has exactly one sandbox of this type, required when there are several, and needs `--auto-create` when there are none	Auto-resolved
`--type <type>`	Sandbox type: `code` \| `skill`	`code`
`--tail <n>`	Max log lines	None
`-r, --region <region>`	Volcengine region	None
`-p, --project <name>`	AgentKit project	`default`
`--json`	Output raw JSON	`false`

agentkit sandbox logs my-session --tail 100

sandbox rm

Stop and delete a sandbox session (or --all). To delete the sandbox environment itself, use sandbox delete.

Flag / Argument	Description	Default
`[session]`	Session id	None
`--tool-id <id>`	Sandbox id. Auto-resolved when omitted: used automatically if the project has exactly one sandbox of this type, required when there are several, and needs `--auto-create` when there are none	Auto-resolved
`--type <type>`	Sandbox type: `code` \| `skill`	`code`
`--all`	Delete every session on the sandbox	`false`
`-y, --yes`	Skip confirmation	`false`
`-r, --region <region>`	Volcengine region	None
`-p, --project <name>`	AgentKit project	`default`

agentkit sandbox rm my-session -y

Getting Started

AI-Friendly

Command reference

sandbox create

sandbox list

sandbox show

sandbox update

sandbox delete

sandbox run

sandbox shell

sandbox cp

sandbox web

sandbox sessions

sandbox logs

sandbox rm