# Chalk CLI Reference: Sandboxes
source: https://docs.chalk.ai/cli#sandboxes

Create and manage sandboxes for interactive development, debugging, and running ad-hoc commands in your Chalk environment.

## `chalk sandbox start`
source: https://docs.chalk.ai/cli?command=sandbox_start

```bash
chalk sandbox start [function] [-- command args...]
```

Choose a deployed function returning Sandbox, fill in its typed arguments, and open a remote session in this terminal. Uses the current Chalk environment. Only functions published with the Sandbox type marker are offered. Provisioning is queued and polled; use --call-id to resume waiting after an interruption without submitting the function again.

The CLI parses the published docstring locally for the function summary and argument help. Google, NumPy, Sphinx, and paragraphs beginning with an argument name are supported. Types, defaults, and validation come from the published schema.

An explicit command runs unchanged inside the sandbox. Without one, choose Claude, Codex, or a shell. Ctrl-\ detaches while leaving the process running. Network interruptions reconnect to the same session. Closing the terminal does not terminate the sandbox; its configured lifetime still applies.

With --tmux, create a named tmux session and reconnect through fresh tmux clients to restore the screen. Resume later with 'chalk sandbox attach --tmux'. Tmux must be installed in the image. Ctrl-B then D detaches the tmux client. No local restoration record is written in this mode. --tmux cannot be combined with --no-attach.

**Flags**

- `--call-id <id>` (string)
  Resume waiting for a deferred provisioning call without invoking the function again.
- `--arg <name=value>` (string[], default `[]`)
  Provisioning function argument as name=value. Strings are literal; lists and objects use JSON. Repeat for multiple arguments.
- `--timeout <timeout>` (int, default `600`)
  Maximum provisioning and readiness time in seconds.
- `--workdir <workdir>` (string)
  Working directory for the command inside the sandbox. Defaults to the sandbox image's working directory.
- `--no-attach <no-attach>` (bool, default `false`)
  Provision a sandbox and print its ID without starting a command.
- `--tmux <tmux>` (bool, default `false`)
  Use tmux inside the sandbox for screen restoration on attach and reconnect. Requires tmux in the sandbox image and an interactive terminal.

**Example**

```
$ chalk sandbox start make_ds_sandbox --tmux -- claude
$ chalk sandbox start make_eng_sandbox -- codex
$ chalk sandbox start make_ds_sandbox --arg lifetime_minutes=30 --no-attach
```

## `chalk sandbox attach`
source: https://docs.chalk.ai/cli?command=sandbox_attach

```bash
chalk sandbox attach [sandbox]
```

Attach to an existing remote process by sandbox name or ID. Omit the sandbox to choose a running sandbox in the current Chalk environment. Select a session when necessary, or supply --session. Noninteractive callers must supply a sandbox. Reconnection never provisions a sandbox or launches a new agent. With --tmux, discover sessions on the sandbox user's default tmux socket, including manually created sessions. Choose one or supply its name or ID with --session. Attachment and reconnection start a fresh tmux client and detach other clients on that tmux session to restore the screen. No local restoration record is required or written.

**Flags**

- `--session <id>` (string)
  Attach this existing remote session instead of opening the session picker. With --tmux, use a tmux session name or ID.
- `--tmux <tmux>` (bool, default `false`)
  Use tmux inside the sandbox for screen restoration on attach and reconnect. Requires tmux in the sandbox image and an interactive terminal.
- `--skip-status-check <skip-status-check>` (bool, default `false`)
  Skip the lifecycle status check before attaching. Use this only when the sandbox status endpoint is unavailable; session errors may be less actionable.

**Example**

```
$ chalk sandbox attach --tmux
$ chalk sandbox attach my-sandbox --tmux --session claude
$ chalk sandbox attach my-sandbox --session session-id
```

## `chalk sandbox create`
source: https://docs.chalk.ai/cli?command=sandbox_create

```bash
chalk sandbox create
```

Use 'chalk sandbox create' to provision a new sandbox.

A sandbox is a long-lived container you exec into, rather than a workload whose entrypoint is the job. It accepts the same workload options as 'chalk container run': resources, volumes, secrets, networking, and routing all behave identically.

A sandbox outlives whatever you run in it. Unless you pass --entrypoint, the server keeps the sandbox alive on its own, so --exec runs as a separate process and the sandbox stays running once that process exits. It keeps running until you 'chalk sandbox terminate' it, or its --lifetime expires. This is the difference from 'chalk container run', where the entrypoint IS the job and the workload finishes when that process exits.

To run something at creation time, pass '--exec CMD' to run CMD and stream its output, with any arguments after '--' going to CMD. Add -t to attach a PTY. Or pass '--exec-tty' to take the whole command from the trailing arguments with a PTY attached, as in '--exec-tty -- bash'. Note that trailing arguments belong to --exec / --exec-tty here, whereas 'chalk container run' appends them to the container's entrypoint; a sandbox's own entrypoint comes from --entrypoint.

Without any --exec flag the command returns as soon as the sandbox is running, and you exec into it later with 'chalk sandbox exec'.

Because a sandbox outlives its command, it is easy to leave one running by accident, and --lifetime defaults to 0, meaning forever. Add --rm to any --exec form to terminate the sandbox once the command finishes, which is what you want for a one-shot run. For a sandbox you do mean to keep, pass --lifetime so it cleans itself up, and 'chalk sandbox list' to find the ones you forgot.

**Flags**

- `-i, --image <image>` (string)
  Container image to use for the sandbox.
- `-n, --name <name>` (string)
  Optional name for the sandbox.
- `--entrypoint <entrypoint>` (string)
  Override container entrypoint command (space-separated).
- `--tags <tags>` (string)
  User-defined tags as `key=value` pairs (comma-separated).
- `-l, --lifetime <lifetime>` (string, default `0`)
  How long the sandbox should run before termination (e.g., `'1h'`, `'30m'`, `'0'` for infinite).
- `--cpu <cpu>` (string)
  CPU limit (e.g., `'2'` or `'500m'`).
- `--memory <memory>` (string)
  Memory limit (e.g., `'4Gi'` or `'512Mi'`).
- `--gpu <gpu>` (string)
  GPU request as `type:count` (e.g., `'nvidia-tesla-t4:1'`) or just `count` (e.g., `'1'`).
- `--kernel-policy <kernel-policy>` (string)
  Kernel security policy for the sandbox. Valid values are `restricted` and `open`.
- `--route <route>` (string[], default `[]`)
  Allowed outbound route as `CIDR[=PORT[,PORT-PORT,...]]`. Omitting ports allows all ports. Can be specified multiple times.
- `--no-routes <no-routes>` (bool, default `false`)
  Allow no outbound routes, denying all egress. Host compute class only. Cannot be combined with --route.
- `--host <host>` (string[], default `[]`)
  Allowed outbound host as `HOSTNAME`, such as `github.com`. Without --route, only the named hosts are reachable. Host compute class only. Can be specified multiple times.
- `--port <port>` (int, default `0`)
  Port to serve over https.
- `--restart <restart>` (bool, default `false`)
  Automatically restart the sandbox if it terminates.
- `-e, --env <env>` (string)
  Environment variables for the sandbox, as `key=value` pairs (comma-separated). Every process in the sandbox sees these; use `--exec-env` to add variables for the `--exec` process alone.
- `--env-file <env-file>` (string)
  Path to an env file containing environment variables (one `KEY=VALUE` per line).
- `--secret-from-chalk <secret-from-chalk>` (string[], default `[]`)
  Name of a secret already in Chalk to inject as env vars. Can be specified multiple times.
- `--secret-from-integration <secret-from-integration>` (string[], default `[]`)
  Inject an integration's secrets as env vars, as `NAME` or `NAME:KEY1,KEY2` to pick specific keys. Can be specified multiple times.
- `--secret-from-local-env <secret-from-local-env>` (string[], default `[]`)
  Create a Chalk secret from an environment variable on this machine and inject it, as `VAR` or `VAR=SECRET_NAME`. The secret is scoped to this sandbox, so --name is required. Can be specified multiple times.
- `--secret-from-local-env-file <secret-from-local-env-file>` (string[], default `[]`)
  Create a Chalk secret from every `KEY=VALUE` in an env file on this machine and inject them. The secrets are scoped to this sandbox, so --name is required. Can be specified multiple times.
- `--grpc <grpc>` (bool, default `false`)
  Use gRPC as the backend protocol instead of HTTP.
- `--internal <internal>` (bool, default `false`)
  Use private routing (not publicly accessible).
- `--authenticated <authenticated>` (bool, default `false`)
  Require JWT authentication on the sandbox's HTTP route.
- `--chalk-identity <chalk-identity>` (bool, default `true`)
  Inject Chalk credentials for the creating user or service token into the sandbox. Set --chalk-identity=false to disable.
- `--startup-probe <startup-probe>` (bool, default `false`)
  Wait for the externally routed HTTP or gRPC endpoint to respond before reporting the sandbox as running. Requires --port.
- `--resource-detection <resource-detection>` (string[], default `[]`)
  Detect resources the sandbox creates through its egress traffic and record them against the sandbox. Valid values are `github-pull-requests`. Only applies to hosts the network policy allows. Can be specified multiple times.
- `--volume <volume>` (string[], default `[]`)
  Chalk Volume URI, optionally followed by `=/mount/path`. Defaults to `/mnt/VOLUME`. Can be specified multiple times.
- `--empty-dir <empty-dir>` (string[], default `[]`)
  Ephemeral disk mount path, optionally followed by `=SIZE`. Defaults to the platform size limit. Can be specified multiple times.
- `--with-local-file <with-local-file>` (string[], default `[]`)
  Upload a local file to an auto-created volume and mount it into the sandbox, as `local_path:/sandbox/path`. If the sandbox path ends with `/`, the local file name is appended. Can be specified multiple times.
- `--compute-class <compute-class>` (string)
  Where to run the sandbox: `'host'` (default, a Chalk Compute host) or `'k8s'` (run as a pod).
- `--runtime <runtime>` (string)
  Runtime for host sandboxes. Not supported for Kubernetes workloads.
- `--execution-target <execution-target>` (string)
  Where to place the sandbox: `environment` or `serverless`.
- `--exec <exec>` (string)
  After creating the sandbox, execute this command in it. Arguments after `--` are passed to the command.
- `--exec-tty <exec-tty>` (bool, default `false`)
  Run the trailing command in the new sandbox through a TTY session (same as `--exec` plus `-t`).
- `--rm <rm>` (bool, default `false`)
  Terminate the sandbox once the `--exec` / `--exec-tty` command finishes, instead of leaving it running (similar to `docker run --rm`). A session that detaches instead of finishing leaves the sandbox alone.
- `-t, --interactive <interactive>` (bool, default `false`)
  When combined with `--exec`, allocate a PTY and proxy the terminal (similar to `docker run -it`).
- `--exec-workdir <exec-workdir>` (string)
  Working directory for the `--exec` process. The sandbox itself has no configurable working directory.
- `--exec-env <exec-env>` (string)
  Extra environment variables for the `--exec` process only, as `key=value` pairs (comma-separated). Use `--env` for variables the whole sandbox should have.
- `--exec-timeout <exec-timeout>` (int, default `0`)
  Timeout in seconds for the `--exec` process. This bounds the command, not the sandbox; use `--lifetime` to bound the sandbox.

**Example**

```
# Interactive shell that terminates the sandbox when you exit, either spelling
$ chalk sandbox create -i ubuntu:22.04 --rm -t --exec bash
$ chalk sandbox create -i ubuntu:22.04 --rm --exec-tty -- bash

# One-shot run: upload a script, run it, and terminate the sandbox afterwards
$ chalk sandbox create -i python:3.13 --rm --with-local-file ./hello.py:/app/hello.py \
    --exec python -- /app/hello.py

# Size it for the job at hand
$ chalk sandbox create -i python:3.12 --cpu 2 --memory 4Gi --rm --exec python -- /app/train.py

# Check that an env file landed
$ chalk sandbox create -i python:3.12 --env-file .env --rm --exec env

# Inject a secret already in Chalk, an integration's secrets, and one made from a local value
$ chalk sandbox create -i python:3.12 -n etl --secret-from-chalk openai \
    --secret-from-integration snowflake:user,password --secret-from-local-env ANTHROPIC_API_KEY \
    --rm --exec python -- -c "import os; print('openai' in os.environ)"

# Mount a ChalkFS volume, and restrict egress
$ chalk sandbox create -i python:3.12 --volume chalk://my-data@v2 --route '10.0.0.0/8=443,5432' \
    --rm --exec ls -- /mnt/my-data

# Record GitHub pull requests the sandbox opens against it
$ chalk sandbox create -i python:3.12 -n pr-bot --resource-detection github-pull-requests

# Leave one running to exec into later, bounded so it cannot outlive the day
$ chalk sandbox create -i python:3.12 -n my-sandbox --lifetime 8h

# Serve a port on a Chalk Compute host with a GPU, for as long as you need it
$ chalk sandbox create -i my-model:v1 -n gpu-box --port 8000 --gpu nvidia-tesla-t4:1 --lifetime 4h
```

## `chalk sandbox exec`
source: https://docs.chalk.ai/cli?command=sandbox_exec

```bash
chalk sandbox exec [--] command [args...]
```

Use 'chalk sandbox exec' to run a command in a running sandbox.

Identify the sandbox by --id, or by --name. Because names are reused, a name resolves to the active sandbox with that name, of which there can only be one, falling back to the most recently created finished one when none is active.

Stdin is forwarded to the process, and stdout/stderr are printed to the terminal. The exit code of the remote process is used as the exit code of this command.

Pass -t to allocate a PTY and proxy your terminal, similar to 'docker exec -it'.

Put '--' before the remote command so its flags are not read as Chalk CLI flags.

**Arguments**

- `command` (string)
  The command and arguments to execute

**Flags**

- `-i, --id <id>` (string)
  ID of the sandbox to execute the command in (mutually exclusive with --name).
- `-n, --name <name>` (string)
  Name of the sandbox to execute the command in (mutually exclusive with --id).
- `--workdir <workdir>` (string)
  Working directory for the command.
- `-e, --env <env>` (string)
  Environment variables as `key=value` pairs (comma-separated).
- `--timeout <timeout>` (int, default `0`)
  Command timeout in seconds.
- `-t, --interactive <interactive>` (bool, default `false`)
  Allocate a PTY and proxy the terminal (similar to `docker exec -it`).

**Example**

```
# Run a one-off command
$ chalk sandbox exec --name my-sandbox -- python -c "print('hello')"

# Interactive shell
$ chalk sandbox exec --id 550e8400-e29b-41d4-a716-446655440000 -t -- bash

# Pipe stdin in
$ echo "data" | chalk sandbox exec -n my-sandbox -- cat

# Set the working directory, extra env, and a timeout
$ chalk sandbox exec -n my-sandbox --workdir /app -- ls -la
$ chalk sandbox exec -n my-sandbox -e "LOG_LEVEL=debug" -- env
$ chalk sandbox exec -n my-sandbox --timeout 30 -- ./long-job.sh
```

## `chalk sandbox get`
source: https://docs.chalk.ai/cli?command=sandbox_get

```bash
chalk sandbox get
```

Use 'chalk sandbox get' to view the current status and spec of a sandbox.

Identify the sandbox by --id, or by --name. Because names are reused, a name resolves to the active sandbox with that name, of which there can only be one, falling back to the most recently created finished one when none is active.

**Flags**

- `-i, --id <id>` (string)
  ID of the sandbox (mutually exclusive with --name).
- `-n, --name <name>` (string)
  Name of the sandbox (mutually exclusive with --id).

**Example**

```
$ chalk sandbox get --id 550e8400-e29b-41d4-a716-446655440000
$ chalk sandbox get --name my-sandbox
$ chalk sandbox get -i 550e8400-e29b-41d4-a716-446655440000 --json
```

## `chalk sandbox list`
source: https://docs.chalk.ai/cli?command=sandbox_list

```bash
chalk sandbox list
```

Use 'chalk sandbox list' to view sandboxes in the current environment.

By default this lists only sandboxes that are pending, running, or in error, since those are the ones you can still act on. Pass --all for every status, or --status to pick specific ones.

Sandboxes come a page at a time, at most --limit per page, and the cursor to fetch the next page is printed alongside them. Pass --tui to browse them in an interactive table instead, which loads the next page when you press 'm'.

**Flags**

- `--status <status>` (string[], default `[]`)
  Only list sandboxes in these statuses (`pending`, `running`, `succeeded`, `failed`, `terminated`, `error`, `unknown`, `suspended`). Defaults to `pending`, `running`, `error`. Can be specified multiple times.
- `--all <all>` (bool, default `false`)
  List sandboxes in every status, not just `pending`, `running`, and `error`.
- `--search <search>` (string)
  Only list sandboxes whose name matches this search term.
- `--limit <limit>` (int, default `40`)
  Maximum number of sandboxes to return.
- `--cursor <cursor>` (string)
  Cursor for pagination, from a previous page's output.
- `--tui <tui>` (bool, default `false`)
  Browse sandboxes in an interactive table. Press `m` to load the next page, `↑`/`↓` to scroll, and `q` to quit.

**Example**

```
# Pending, running, and errored sandboxes
$ chalk sandbox list

# Every sandbox, including finished ones
$ chalk sandbox list --all

# Just the ones that finished successfully
$ chalk sandbox list --status succeeded

# Only the ones whose name matches
$ chalk sandbox list --search etl

# Browse them interactively, loading more with 'm'
$ chalk sandbox list --tui

# Page explicitly, using the cursor from the previous page
$ chalk sandbox list --limit 100 --cursor <cursor-from-previous-page>
```

## `chalk sandbox terminate`
source: https://docs.chalk.ai/cli?command=sandbox_terminate

```bash
chalk sandbox terminate
```

Use 'chalk sandbox terminate' to stop and remove a sandbox.

Identify the sandbox by --id, or by --name. Because names are reused, a name resolves to the active sandbox with that name, of which there can only be one, falling back to the most recently created finished one when none is active.

**Flags**

- `-i, --id <id>` (string)
  ID of the sandbox to terminate (mutually exclusive with --name).
- `-n, --name <name>` (string)
  Name of the sandbox to terminate (mutually exclusive with --id).

**Example**

```
$ chalk sandbox terminate --id 550e8400-e29b-41d4-a716-446655440000
$ chalk sandbox terminate --name my-sandbox
```

## `chalk sandbox fork`
source: https://docs.chalk.ai/cli?command=sandbox_fork

```bash
chalk sandbox fork
```

Restore a snapshot into a new sandbox and wait for it to run. The snapshot's recorded spec supplies the resources and configuration; the scheduler chooses a compatible host.

**Flags**

- `--snapshot-id <snapshot-id>` (string)
  ID of the snapshot.

**Example**

```
$ chalk sandbox fork --snapshot-id <snapshot-id> --json
```

## `chalk sandbox suspend`
source: https://docs.chalk.ai/cli?command=sandbox_suspend

```bash
chalk sandbox suspend
```

Capture the sandbox's state and release its running resources. Restore it later with 'chalk sandbox restore'. Snapshot support must be enabled in your environment.

**Flags**

- `-i, --id <id>` (string)
  ID of the sandbox (mutually exclusive with --name).
- `-n, --name <name>` (string)
  Name of the sandbox (mutually exclusive with --id).

**Example**

```
$ chalk sandbox suspend --id <sandbox-id>
$ chalk sandbox suspend --name my-sandbox
```

## `chalk sandbox restore`
source: https://docs.chalk.ai/cli?command=sandbox_restore

```bash
chalk sandbox restore
```

Restore a suspended sandbox and wait for it to run. The sandbox keeps its ID; the scheduler chooses a host compatible with the saved snapshot.

**Flags**

- `-i, --id <id>` (string)
  ID of the sandbox (mutually exclusive with --name).
- `-n, --name <name>` (string)
  Name of the sandbox (mutually exclusive with --id).

**Example**

```
$ chalk sandbox restore --id <sandbox-id>
$ chalk sandbox restore --name my-sandbox
```

## `chalk sandbox snapshot create`
source: https://docs.chalk.ai/cli?command=sandbox_snapshot_create

```bash
chalk sandbox snapshot create
```

Capture a running sandbox's memory and filesystem without stopping it. The snapshot can be forked into a new sandbox. Snapshot support must be enabled in your environment. Waits until the snapshot is completed and ready to restore. Exiting this command does not cancel accepted capture.

**Flags**

- `-i, --id <id>` (string)
  ID of the sandbox (mutually exclusive with --name).
- `-n, --name <name>` (string)
  Name of the sandbox (mutually exclusive with --id).

**Example**

```
$ chalk sandbox snapshot create --id <sandbox-id> --json
$ chalk sandbox snapshot create --name my-sandbox
```

## `chalk sandbox snapshot get`
source: https://docs.chalk.ai/cli?command=sandbox_snapshot_get

```bash
chalk sandbox snapshot get
```

View a snapshot's status, phase, upload progress, recorded sandbox spec, and restore metadata. Only completed status proves the snapshot is ready to restore.

**Flags**

- `--snapshot-id <snapshot-id>` (string)
  ID of the snapshot.

**Example**

```
$ chalk sandbox snapshot get --snapshot-id <snapshot-id> --json
```

## `chalk sandbox snapshot list`
source: https://docs.chalk.ai/cli?command=sandbox_snapshot_list

```bash
chalk sandbox snapshot list
```

List one page of snapshots in the current environment. Use --cursor with the returned next_cursor to fetch another page.

**Flags**

- `--sandbox-id <sandbox-id>` (string)
  Only list snapshots captured from this sandbox ID.
- `--limit <limit>` (int, default `40`)
  Maximum snapshots per page.
- `--cursor <cursor>` (string)
  Cursor from a previous page's next_cursor.
- `--status <status>` (string[], default `[]`)
  Filter by pending, in_progress, completed, or failed. Can be specified multiple times.

**Example**

```
$ chalk sandbox snapshot list --sandbox-id <sandbox-id> --status completed --json
```

## `chalk sandbox snapshot delete`
source: https://docs.chalk.ai/cli?command=sandbox_snapshot_delete

```bash
chalk sandbox snapshot delete
```

Delete a snapshot so it can no longer be used to fork a sandbox. This does not terminate the source sandbox.

**Flags**

- `--snapshot-id <snapshot-id>` (string)
  ID of the snapshot.

**Example**

```
$ chalk sandbox snapshot delete --snapshot-id <snapshot-id>
```
