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

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.

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

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

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

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

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

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

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

```bash lines theme={null}
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`](#sandbox-rm).

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

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

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

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

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

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

```bash lines theme={null}
agentkit sandbox web --session my-session
```

## sandbox login

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

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

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

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

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

```bash lines theme={null}
agentkit sandbox rm my-session -y
```