> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

<Note>
  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.
</Note>

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.

<Warning>
  `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.
</Warning>

| 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 |

```bash lines theme={null}
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` |

```bash lines theme={null}
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` |

```bash lines theme={null}
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` \| `DevEnv` \| `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.

<Warning>
  `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`.
</Warning>

| Flag / Argument | Description | Default |
| - | - | - |
| `--tool-type <type>` | Tool type: `CodeEnv`, `SkillEnv`, `DevEnv`, 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` |

```bash lines theme={null}
agentkit sandbox create --tool-type CodeEnv --tool-name dev-code --cpu 4
```

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

```bash lines theme={null}
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`.

<Warning>
  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.
</Warning>

| 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` |

```bash lines theme={null}
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. | — |

```bash lines theme={null}
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` |

```bash lines theme={null}
agentkit sandbox mount --tool-id tool-123 --session-id dev
```

## sandbox exec

`sandbox attach` is an alias of this command and accepts the same flags.

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` |

```bash lines theme={null}
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` |

```bash lines theme={null}
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` |

```yaml title="agentkit-sandbox-run.yaml" lines theme={null}
exec:
  - session_id: dev
    cwd: .
    copy:
      - ["./app", "sandbox:/home/gem/app"]
    command: "cd /home/gem/app && npm test"
```

```bash lines theme={null}
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 — |

```bash lines theme={null}
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` |

```bash lines theme={null}
agentkit sandbox web --session-id dev --no-open
```

## sandbox codex-login

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

<Warning>
  `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.
</Warning>

| 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` |

```bash lines theme={null}
agentkit sandbox codex-login --session-id dev --provider codex

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

## sandbox model-login

`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` |

```bash lines theme={null}
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. | — |

```bash lines theme={null}
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
```