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. sandbox create and sandbox config accept All-in-one, Skill, CodeEnv, DevEnv, ArkClawEnv, HermesEnv, and Private as public tool types.
Most sandbox commands read the AgentKit control-plane region from
.agentkit/sandbox.yaml or AGENTKIT_SANDBOX_REGION; sandbox dashboard also accepts --region for the local dashboard session. 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.-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.
Tool selection usually resolves explicit CLI options first, then .agentkit/sandbox.yaml, AGENTKIT_SANDBOX_TOOL_ID, and local cache or a remote Ready tool. Whether a command may auto-create a tool or prompt for selection depends on that command’s behavior below.
Command overview
sandbox build
Build a custom sandbox image in cloud Code Pipeline. After a successful build, the CLI setstool-type to Private and writes the generated image URL to .agentkit/sandbox.yaml for later sandbox create commands.
sandbox init
Generate a sandbox Dockerfile template. When no template is specified, the command generates theskill template. The command resolves the current built-in base image for the template’s tool type and writes the concrete image URL into the generated Dockerfile.
Resolving the built-in base image requires usable AgentKit control-plane credentials and region configuration. Offline or unauthorized environments cannot generate a template with a concrete base image.
sandbox config
Configure local defaults for sandbox commands. The config file is.agentkit/sandbox.yaml in the current project. --list prints the current config file and redacts model API keys and WebSearch API keys.
.agentkit/sandbox.yaml is first written, the CLI persists only foundational defaults such as networking, tool type, CPU, snapshots, and session TTL. Model provider, model name, and model base URL are filled in when the effective config is read, and are persisted only after you set them explicitly with sandbox config --set model-* or command-line flags.
Supported config keys are listed below.
Model Environment Variables
Model options forsandbox create and sandbox exec are translated into multiple environment variable names so Codex, OpenCode, and runtimes or tools that read MODEL_AGENT_* can share the same settings.
When
--model-base-url points to a non-built-in model endpoint, pass --model-provider as well. For an existing CodeEnv session, model name, API key, or base URL values passed explicitly to sandbox exec update /home/gem/.env, Codex config, and OpenCode config inside the session, so later terminals reuse the same settings.
Generated Codex config is written to
/home/gem/.codex/config.toml inside the sandbox session. General model options no longer generate ANTHROPIC_* variables and no longer pass generated config through CODEX_CONFIG_TOML or CODEX_MODEL_CATALOG_JSON; to customize Codex config, edit that file inside the session or run sandbox codex-login again to rewrite the subscription login config.sandbox create
Create a sandbox tool. After creation, the CLI waits until the tool reachesReady, then stores the tool id and name in local sandbox config.
Skill tool, pass the app ID explicitly. This option is supported only with Skill tool type.
Private tool, prepare an image URL first:
sandbox dashboard
Start a local web dashboard for viewing and operating sandbox tools and sessions. The command listens on a local port and opens a browser in an interactive terminal by default; in CI or with--no-open, it only prints the URL.
Standalone binaries installed through the install script or
agentkit upgrade include the assets required by the dashboard terminal UI, so no extra Node.js dependencies are needed. When manually extracting a standalone release, keep the vendor/ directory beside ak in the same install directory; otherwise the dashboard page may not load the terminal component.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.
sandbox list
List sandbox sessions or tools and always print JSON. When neither--tools nor --sessions is passed, the command defaults to --sessions --local and reads the local session cache; with --tools, it reads the local tool cache by default. Pass --remote explicitly to query remote data.
sandbox list is an inspection command and does not auto-create or select a sandbox tool through the tool resolution chain used by session-oriented commands. --tools and --sessions are mutually exclusive, as are --local and --remote; --tool-name, --tool-type, and --status are valid only in tool mode.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 throughagentkit login.
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.
sandbox invoke
Invoke an agent in a sandbox through A2A. The default tool type isSkillEnv, and output is JSON. With --async, the command returns immediately after creating the task; with --task-id, it polls an existing task.
sandbox run
Read a YAML file and convert its entries intoagentkit 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.
agentkit-sandbox-run.yaml
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.
sandbox web
Open the sandbox web preview and print JSON containing the URL, tool id, session id, and whether the session was newly created. When opening a browser by default, the CLI also asks the remote sandbox browser to open/home/gem/ so the session files are immediately visible; with --no-open, it only returns the web URL.
sandbox codex-login
Inject local Codex or Claude subscription credentials into a sandbox session.model-login is equivalent to this command.
With --provider codex, the CLI writes /home/gem/.codex/config.toml inside the sandbox session, configures the codex_login model provider for OAuth login, and sets the default model gpt-5.5 through CODEX_MODEL, OPENCODE_MODEL, and MODEL_AGENT_NAME. Local API keys are not injected with subscription credentials.
sandbox model-login
model-login is equivalent to codex-login; it injects local Codex or Claude subscription credentials into a sandbox session.
sandbox scp
Transfer files or directories between local storage and an existing sandbox session. Remote paths must start withsandbox:; 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.