Use sandboxes

The sandbox command group creates and manages AgentKit sandbox tools, then uses sandbox sessions to run commands, invoke agents, transfer files, open web previews, or inject local model subscription credentials. Current sandbox tool types are CodeEnv, SkillEnv, and Private.

Sandbox commands do not expose a --region flag. To set the AgentKit control-plane region, write it to .agentkit/sandbox.yaml with agentkit sandbox config --set region=<region>, or set AGENTKIT_SANDBOX_REGION. For TOS mounts, set AGENTKIT_SANDBOX_TOS_REGION; when it is omitted, the CLI infers the TOS region from the bucket or current cloud environment.

Session-oriented commands share the same tool and session selectors: -s, --session-id <id>, --sid <id> selects the user session id; --tool-id <id> selects a sandbox tool id; --tool-name <name> resolves by tool name; --tool-type <type> selects the tool type. If local config already stores tool-id, tool-name, tool-type, or session-id, commands use those defaults as described in each option table when the corresponding option is omitted.

Command overview

Subcommand	Description
`build`	Build a custom sandbox image in cloud Code Pipeline and store `Private` tool config.
`init`	Generate a sandbox Dockerfile template.
`config`	Read, write, or remove sandbox command defaults.
`create`	Create a sandbox tool.
`delete`	Delete a sandbox tool or a specific session.
`list`	List locally cached sandbox sessions.
`mount`	Open a TOS-mounted sandbox session directory in TosBrowser.
`exec`	Connect to a sandbox terminal and execute a command.
`invoke`	Invoke an agent in a `SkillEnv` sandbox through A2A.
`run`	Execute a YAML-defined set of `sandbox exec` tasks.
`shell`	Run a non-interactive shell command in the sandbox and print JSON output.
`web`	Open the sandbox web preview.
`codex-login`	Inject local Codex or Claude subscription credentials into a sandbox session.
`model-login`	Equivalent to `codex-login`.
`scp`	Transfer files or directories between local storage and an existing sandbox session.

sandbox build

Build a custom sandbox image in cloud Code Pipeline. After a successful build, the CLI sets tool-type to Private and writes the generated image URL to .agentkit/sandbox.yaml for later sandbox create commands.

sandbox build uses cloud resources such as TOS, Container Registry, and Code Pipeline, which may incur charges. Confirm account permissions, the project directory, and image naming before running it. If the build fails, the CLI may write build logs under .agentkit/sandbox/build/ in the project.

Flag / Argument	Description	Default
`--dockerfile <path>`	Dockerfile path relative to the project directory.	`Dockerfile`
`--image-name <name>`	Container Registry image name, mapped to the CR repository name.	`agentkit-custom-sandbox-image`
`--repo <name>`	Container Registry repository name; equivalent to `--image-name`.	`agentkit-custom-sandbox-image`
`--tag <tag>`	Container image tag; may include the `{{timestamp}}` placeholder.	`{{timestamp}}`
`--namespace <name>`	Container Registry namespace.	`agentkit`
`--project-dir <path>`	Project directory to package as the Docker build context.	Current directory

agentkit sandbox build --project-dir . --dockerfile Dockerfile --image-name custom-sandbox

sandbox init

Generate a sandbox Dockerfile template. When no template is specified, the command generates the skill template.

Flag / Argument	Description	Default
`-t, --template <name>`	Dockerfile template name: `skill`, `skills`, `aio`, `code`, `code-install-package`, `code-install-skills`, `code-web-server`.	`skill`
`-o, --output <path>`	Output Dockerfile path.	Template default path
`-f, --force`	Overwrite an existing output file.	`false`

agentkit sandbox init --template code-web-server --output Dockerfile.sandbox

sandbox config

Configure local defaults for sandbox commands. The config file is .agentkit/sandbox.yaml in the current project. --list prints YAML after merging defaults and redacts model API keys and WebSearch API keys.

Flag / Argument	Description	Default
`--set <KEY=VALUE>`	Set a config value; repeatable.	—
`--unset <KEY>`	Remove a config value; repeatable.	—
`--list`	Print the current effective config.	`false`

agentkit sandbox config \
  --set tool-type=CodeEnv \
  --set session-id=dev \
  --set model-name=glm-5-2-260617

agentkit sandbox config --list

Supported config keys are listed below.

Config key	Type	Default	Description
`model-name`	string	Selected from the cloud environment	Model name injected into the sandbox.
`model-base-url`	string	Selected from the model provider	Model API base URL.
`model-provider`	string	`model_square` on Volcengine, `byteplus_model_square` on BytePlus	Model provider.
`model-api-key`	string	—	Model API key injected into the sandbox.
`network-public`	boolean	`true`	Enable public network access when creating a tool.
`network-private`	boolean	`false`	Enable private VPC access when creating a tool.
`network-shared-internet`	boolean	`false`	Enable shared internet access for private networking.
`network-vpc-id`	string	—	VPC ID for private networking.
`network-subnet-ids`	string list	—	Subnet IDs for private networking, as CSV or a JSON array.
`tool-type`	`CodeEnv` \| `SkillEnv` \| `Private`	`CodeEnv`	Default sandbox tool type.
`tool-id`	string	—	Default sandbox tool id.
`tool-name`	string	—	Default sandbox tool name.
`region`	string	Current cloud environment region	AgentKit control-plane region.
`cpu`	`2` \| `4` \| `8` \| `16`	`4`	vCPU count used when creating a tool.
`tos-bucket`	string	—	TOS bucket to mount when creating a tool.
`tos-mount`	string	`/home/gem/workspace`	TOS mount path inside the sandbox.
`role-name`	string	—	IAM role name used when `--skill-role-name` is passed without a value.
`enable-snapshot`	boolean	`false`	Enable session snapshots when creating a tool.
`websearch-apikey`	string	—	WebSearch API key injected into the sandbox.
`image-url`	string	—	Custom image URL for `Private` tools.
`tool-image-url`	string	—	Alias for `image-url`.
`session-id`	string	Randomly generated	Default user session id.
`ttl`	integer	`28800`	Session TTL in seconds.
`git-config`	`local` or file path	—	Git identity source injected into sandbox sessions.

sandbox create

Create a sandbox tool. After creation, the CLI waits until the tool reaches Ready, then stores the tool id and name in local sandbox config.

sandbox create provisions cloud compute resources that may incur charges while they exist. Confirm the tool type, resource size, network settings, image, and TOS mount configuration before creating one. Delete unused tools with sandbox delete --tool-id <id> --force.

Flag / Argument	Description	Default
`--tool-type <type>`	Tool type: `CodeEnv`, `SkillEnv`, or `Private`.	Config value or `CodeEnv`
`--tool-name <name>`	Tool name; generated when omitted.	Auto-generated
`--tos-bucket <bucket>`	TOS bucket to mount.	Config value or —
`--tos-mount <path>`	TOS mount path inside the sandbox.	Config value or `/home/gem/workspace`
`--cpu <count>`	vCPU count: `2`, `4`, `8`, or `16`.	Config value or `4`
`--model-name <name>`	Model name injected into the sandbox.	Config value or model-provider default
`--model-api-key <key>`	Model API key injected into the sandbox.	Config value or —
`--model-provider <provider>`	Model provider.	Config value or cloud-environment default
`--model-base-url <url>`	Model API base URL.	Config value or model-provider default
`--skill-role-name [roleName]`	Configure an IAM role for sandbox skills; omit the value to generate a role name.	Configured `role-name` or —
`--websearch-apikey <key>`	WebSearch API key; mutually exclusive with `--skill-role-name`.	Config value or —
`--image-url <url>`	Custom image URL; required for `Private` tools.	Config value or —
`--enable-snapshot`	Enable session snapshots.	Config value or `false`
`--network-public`	Enable public network access.	Config value or `true`
`--no-network-public`	Disable public network access.	—
`--network-private`	Enable private VPC access.	Config value or `false`
`--no-network-private`	Disable private VPC access.	—
`--network-shared-internet`	Enable shared internet access for private networking.	Config value or `false`
`--no-network-shared-internet`	Disable shared internet access.	—
`--network-vpc-id <id>`	VPC ID for private networking; required when `--network-private` is enabled.	Config value or —
`--network-subnet-ids <ids>`	Comma-separated subnet IDs.	Config value or —
`--json`	Output JSON.	`false`

agentkit sandbox create --tool-type CodeEnv --tool-name dev-code --cpu 4

To create a custom Private tool, prepare an image URL first:

agentkit sandbox create \
  --tool-type Private \
  --tool-name private-dev \
  --image-url cr.example.com/agentkit/custom-sandbox:latest

sandbox delete

Delete a sandbox tool or a specific session under a tool. When a session id is passed, the command deletes that session; when it is omitted, the command deletes the tool itself. Tool deletion must target exactly one tool with either --tool-id or --tool-name.

Deleting a sandbox tool or session cannot be undone. Files, runtime state, and session cache that were not persisted elsewhere may be lost. Confirm the target id or name and download required files before proceeding.

Flag / Argument	Description	Default
`-s, --session-id <id>, --sid <id>`	User session id to delete; omit it to delete the tool.	—
`--tool-id <id>`	Sandbox tool id.	—
`--tool-name <name>`	Sandbox tool name.	—
`--force`	Skip the confirmation prompt.	`false`

agentkit sandbox delete --tool-id tool-123 --session-id dev --force

agentkit sandbox delete --tool-name private-dev --force

sandbox list

List locally cached sandbox sessions, or inspect one cached session. This command reads the local session cache and prints JSON; it does not list all cloud sandbox tools.

Flag / Argument	Description	Default
`-s, --session-id <id>, --sid <id>`	User session id to look up.	—
`--tool-id <id>`	Filter the local cache by sandbox tool id.	—

agentkit sandbox list

agentkit sandbox list --tool-id tool-123 --session-id dev

sandbox mount

Open a TOS-mounted sandbox session directory in TosBrowser. The target tool must already have a TOS mount, and a login profile usable for mount authorization must exist locally through agentkit login.

Flag / Argument	Description	Default
`-s, --session-id <id>, --sid <id>`	User session id to mount.	Config value or —
`--oauth-url <url>`	Select the login profile matching the OAuth profile URL.	Current active profile
`--tool-id <id>`	Sandbox tool id.	Config value or —
`--tool-name <name>`	Sandbox tool name.	Config value or —
`--tool-type <type>`	Sandbox tool type.	Config value or `CodeEnv`

agentkit sandbox mount --tool-id tool-123 --session-id dev

sandbox exec

Connect to a sandbox terminal and execute a command. Use --command to provide the initial command after connection; omit it to open a terminal connection. --mode tmux attaches to or creates a tmux session named after the session id.

Flag / Argument	Description	Default
`-s, --session-id <id>, --sid <id>`	User session id.	Config value or random
`--tool-id <id>`	Sandbox tool id.	Config value or —
`--tool-name <name>`	Sandbox tool name.	Config value or —
`--tool-type <type>`	Sandbox tool type.	`CodeEnv`
`--command <cmd>`	Command to run after connecting.	—
`--mode <mode>`	Execution mode; currently supports `tmux`.	—
`--shell-id <id>`	Remote terminal shell id to reconnect.	—
`--copy <sourceAndDestination...>`	Upload local SOURCE to sandbox DESTINATION before exec; pass repeated pairs.	—
`--git-config <source>`	Git identity source: `local` or an INI/TOML/JSON file.	Config value or —
`--model-name <name>`	Model name injected into the session.	Config value or —
`--model-api-key <key>`	Model API key injected into the session.	Config value or —
`--model-provider <provider>`	Model provider injected into the session.	Config value or —
`--model-base-url <url>`	Model API base URL injected into the session.	Config value or —
`--disable-websearch-apikey`	Do not inject the WebSearch API key for this session.	`false`

agentkit sandbox exec --session-id dev --command "npm test"

agentkit sandbox exec \
  --session-id dev \
  --mode tmux \
  --copy ./app sandbox:/home/gem/app \
  --command "cd /home/gem/app && codex"

sandbox invoke

Invoke an agent in a sandbox through A2A. The default tool type is SkillEnv, and output is JSON. With --async, the command returns immediately after creating the task; with --task-id, it polls an existing task.

Flag / Argument	Description	Default
`[asyncMode]`	Optional boolean value, `true` or `false`, used with `--async`.	—
`-s, --session-id <id>, --sid <id>`	User session id.	Config value or random
`--prompt <prompt>`	Prompt to send to the sandbox A2A agent; required unless `--task-id` is set.	—
`--tool-id <id>`	Sandbox tool id.	Config value, `AGENTKIT_SANDBOX_TOOL_ID`, or —
`--tool-name <name>`	Sandbox tool name.	Config value or —
`--tool-type <type>`	Sandbox tool type.	Config value or `SkillEnv`
`--async`	Return immediately after creating the task.	`false`
`--task-id <id>`	Poll an existing A2A task id.	—
`--ttl <seconds>`	Sandbox session TTL.	Config value or `28800`
`--model-name <name>`	Model name injected as `MODEL_AGENT_NAME`.	Config value or —
`--model-provider <provider>`	Model provider injected as `MODEL_AGENT_PROVIDER`.	Config value or —
`--model-base-url <url>`	Model API base URL injected as `MODEL_AGENT_API_BASE`.	Config value or —
`--model-api-key <key>`	Model API key injected as `MODEL_AGENT_API_KEY`.	Config value or —
`--timeout <seconds>`	Maximum seconds to wait for task completion.	`1200`
`--interval <seconds>`	Polling interval in seconds.	`2`
`--history-length <count>`	A2A task history length to request.	`20`
`--a2a-path <path>`	A2A JSON-RPC path on the sandbox endpoint.	`/a2a`

agentkit sandbox invoke --tool-id skill-tool-123 --session-id task-dev --prompt "Summarize the project structure"

agentkit sandbox invoke --tool-id skill-tool-123 --prompt "Run the long task" --async

sandbox run

Read a YAML file and convert its entries into agentkit sandbox exec commands. The default file name is agentkit-sandbox-run.yaml. The root can be a list, or an object containing exec, execs, tabs, or commands.

Flag / Argument	Description	Default
`-f, --config <path>`	YAML file containing exec entries.	`agentkit-sandbox-run.yaml`
`--terminal <count>`	Number of exec entries to open or run.	`1`
`--dry-run`	Print the `sandbox exec` commands without running them.	`false`

agentkit-sandbox-run.yaml

exec:
  - session_id: dev
    cwd: .
    copy:
      - ["./app", "sandbox:/home/gem/app"]
    command: "cd /home/gem/app && npm test"

agentkit sandbox run --config agentkit-sandbox-run.yaml --dry-run

Entry fields include session_id, sid, tool_id, tool_type, command, mode, shell_id, git_config, model_name, model_api_key, model_provider, model_base_url, cwd, workdir, copy, and copies. You can also use args or argv to provide the raw sandbox exec argument list directly.

sandbox shell

Run a non-interactive shell command in the sandbox and print the JSON result. This command requires --command and is suited to scripts; use sandbox exec when you need an interactive terminal.

Flag / Argument	Description	Default
`-s, --session-id <id>, --sid <id>`	User session id.	Config value or random
`--tool-id <id>`	Sandbox tool id.	Config value or —
`--tool-name <name>`	Sandbox tool name.	Config value or —
`--tool-type <type>`	Sandbox tool type.	Config value or `CodeEnv`
`--command <cmd>`	Command to execute in the sandbox.	Required
`--exec-dir <dir>`	Command execution directory.	—
`--copy <sourceAndDestination...>`	Upload local SOURCE to sandbox DESTINATION before running the command.	—
`--git-config <source>`	Git identity source: `local` or an INI/TOML/JSON file.	Config value or —

agentkit sandbox shell --session-id dev --command "python --version"

sandbox web

Open the sandbox web preview and print JSON containing the URL, tool id, session id, and whether the session was newly created.

Flag / Argument	Description	Default
`-s, --session-id <id>, --sid <id>`	User session id.	Config value or random
`--tool-id <id>`	Sandbox tool id.	Config value or —
`--tool-name <name>`	Sandbox tool name.	Config value or —
`--tool-type <type>`	Sandbox tool type.	`CodeEnv`
`--no-open`	Return the web URL without opening a browser.	`false`

agentkit sandbox web --session-id dev --no-open

Inject local Codex or Claude subscription credentials into a sandbox session. model-login is equivalent to this command.

sandbox codex-login and sandbox model-login copy local subscription credentials into a remote sandbox session. Use them only with a trusted sandbox and a dedicated session, and avoid sharing that session. Delete the session or sandbox tool when finished.

Flag / Argument	Description	Default
`-s, --session-id <id>, --sid <id>`	User session id to inject into.	Config value or random
`-p, --provider <provider>`	Subscription type to inject: `codex` or `claude`.	`codex`
`--auth-file <path>`	Specific local credential file.	—
`--codex-home <path>`	Local Codex home.	`$CODEX_HOME` or `~/.codex`
`--login`	Run `codex login` when the local Codex credential is missing.	`true`
`--no-login`	Do not run `codex login` when the local Codex credential is missing.	—
`--tool-id <id>`	Sandbox tool id.	Config value or —
`--tool-name <name>`	Sandbox tool name.	Config value or —
`--tool-type <type>`	Sandbox tool type.	`CodeEnv`
`--dry-run`	Print the redacted injection command without creating a session.	`false`

agentkit sandbox codex-login --session-id dev --provider codex

agentkit sandbox model-login --session-id dev --provider claude --dry-run

model-login is equivalent to codex-login; it injects local Codex or Claude subscription credentials into a sandbox session.

Flag / Argument	Description	Default
`-s, --session-id <id>, --sid <id>`	User session id to inject into.	Config value or random
`-p, --provider <provider>`	Subscription type to inject: `codex` or `claude`.	`codex`
`--auth-file <path>`	Specific local credential file.	—
`--codex-home <path>`	Local Codex home.	`$CODEX_HOME` or `~/.codex`
`--login`	Run `codex login` when the local Codex credential is missing.	`true`
`--no-login`	Do not run `codex login` when the local Codex credential is missing.	—
`--tool-id <id>`	Sandbox tool id.	Config value or —
`--tool-name <name>`	Sandbox tool name.	Config value or —
`--tool-type <type>`	Sandbox tool type.	`CodeEnv`
`--dry-run`	Print the redacted injection command without creating a session.	`false`

agentkit sandbox model-login --session-id dev --provider codex

sandbox scp

Transfer files or directories between local storage and an existing sandbox session. Remote paths must start with sandbox:; relative remote paths resolve under /home/gem. This command uses the local session cache, so create the target session first with sandbox exec, sandbox shell, sandbox web, sandbox invoke, or a login command.

Flag / Argument	Description	Default
`<source>`	Source path; either a local path or `sandbox:<path>`.	Required
`<destination>`	Destination path; either a local path or `sandbox:<path>`.	Required
`-s, --session-id <id>, --sid <id>`	User session id used for the transfer.	Config value or —
`--tool-id <id>`	Sandbox tool id used to disambiguate the local session cache.	—

agentkit sandbox scp ./local.txt sandbox:/home/gem/local.txt --session-id dev

agentkit sandbox scp sandbox:/home/gem/result.json ./result.json --session-id dev

Getting Started

AI-Friendly

Command reference

Command overview

sandbox build

sandbox init

sandbox config

sandbox create

sandbox delete

sandbox list

sandbox mount

sandbox exec

sandbox invoke

sandbox run

sandbox shell

sandbox web

sandbox scp

​Command overview

​sandbox build

​sandbox init

​sandbox config

​sandbox create

​sandbox delete

​sandbox list

​sandbox mount

​sandbox exec

​sandbox invoke

​sandbox run

​sandbox shell

​sandbox web

​sandbox codex-login

​sandbox model-login

​sandbox scp

Command overview

sandbox build

sandbox init

sandbox config

sandbox create

sandbox delete

sandbox list

sandbox mount

sandbox exec

sandbox invoke

sandbox run

sandbox shell

sandbox web

sandbox codex-login

sandbox model-login

sandbox scp