# Sandboxes A sandbox is an isolated virtual machine for an agent or any other program. It runs one command when it first starts, then any command you send it. It keeps `/workspace` between stops and restarts, stops by itself when idle and starts again when work arrives. It can serve one HTTP port at its own URL, and it takes snapshots you can restore. This guide covers a sandbox's whole life in the console, the CLI and the API. The CLI examples assume you've installed and configured `caas` (see [The CLI](/docs/cli)). ## Create a sandbox ### In the console 1. Open **Sandboxes** and choose **New sandbox**. (The button shows for a workspace's owners and operators.) 2. Under **1. Choose an image**, pick **Default** or **Your image** (see [Images](#images)), and fill in what the sandbox runs (see [Choose what it runs](#choose-what-it-runs)). 3. Under **2. Configure**, optionally enter a **Name**, and pick a **Size** (see [Sizes](#sizes)). The estimate beside the form shows what the size costs. 4. In **Allowed outbound hosts**, list the hosts the sandbox may reach, one per line. Everything else is blocked. 5. Keep **Keep state between restarts** checked to keep `/workspace` across stops and restarts, or uncheck it to start fresh every time. 6. Choose **Create sandbox**. The sandbox's page opens. Its status moves from **Starting** to **Running**, and then its command runs. ### With the CLI `caas run` creates a sandbox, waits for its command to finish and prints the command's output: ```sh caas run --name build-agent --size l -- node --version ``` Put `--` before the command whenever its arguments start with `--`. The options: | Option | What it does | | --- | --- | | `--from .` | Uploads your Git repository's committed files, unpacked into `/workspace` (see [An uploaded archive](#an-uploaded-archive)) | | `--image IMAGE` | Runs your own image instead of the Default one | | `--name NAME` | Names the sandbox | | `--size SIZE` | `xs`, `s`, `m` (the default), `l`, `xl`, `2xl`, or `custom` with `--vcpu`, `--memory` and `--disk` | | `--egress-host HOST` | Allows the sandbox to reach a host; repeat it for each host | | `--expose PORT` | Serves a port at the sandbox's URL; add `--public` to open it to anyone | | `--idle-stop MINUTES` | Stops it after this many idle minutes, 5 to 240 (15 by default) | | `--wake-on-request` | Lets requests start it even after you stop it yourself | | `--ephemeral` | Starts it fresh every time, keeping nothing between restarts | | `--detach` | Returns as soon as the sandbox exists, without waiting for its command | `caas run` exits with an error when the command fails. With `--detach`, it prints the sandbox, with its ID, as soon as it exists; check the command later with `caas sandboxes command initial-agent-command`. When the command starts with `npx`, `caas run` also allows `registry.npmjs.org`. ### With the API Send the sandbox you want to `POST /v1/tenants//sandboxes` with an API key. Your Tenant ID and API keys are in the console's **Settings**. ```sh export CAAS_TENANT= export CAAS_API_KEY= curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes \ -H "Authorization: Bearer $CAAS_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "kind": "agent", "name": "build-agent", "size": "l", "source": { "type": "stdio", "command": ["node", "--version"] }, "egressHosts": ["api.github.com"] }' ``` The answer, `201 Created`, is the new sandbox with its `id` and `"status": "starting"`. The `Idempotency-Key` header (8 to 128 characters) is required: if you retry with the same key, you get the same sandbox, never a second one. | Field | Value | | --- | --- | | `kind` | `"agent"` for a sandbox. (`"mcp"` deploys an MCP server; see [MCP servers](/docs/mcp).) | | `source` | What it runs; see [Choose what it runs](#choose-what-it-runs). Required. | | `size` | `"xs"`, `"s"`, `"m"`, `"l"`, `"xl"` or `"2xl"`, or a custom size such as `{ "vcpu": 2, "memoryGib": 8, "diskGb": 16 }`. Defaults to `"m"`. | | `name` | Optional; see [Names](#names). | | `egressHosts` | Up to 32 hosts the sandbox may reach. | | `persistent` | `false` to start fresh on every start. Defaults to `true`. | | `idleStopMinutes` | 5 to 240. Defaults to 15. | | `wakeOnRequest` | `true` to let requests start a sandbox you stopped. Defaults to `false`. | | `expose` | `{ "port": 3000, "public": false }` turns on the sandbox's URL. | | `snapshotTime` | The nightly snapshot's time as `"HH:MM"`, or `null` for none. Defaults to `"02:00"` for a sandbox that keeps state. | `GET /v1/tenants//sandboxes` lists your sandboxes with their status, and `GET /v1/tenants//sandboxes/` returns one. See [The API](/docs/api) for keys and their scopes. ## Images ### The Default image The Default image is Alpine Linux with bash, coreutils, Node and Docker. It runs on any size. It doesn't include your project's dependencies or coding agents such as Claude Code: install what you need in a command, or build your own image. To install Alpine packages with `apk`, allow `dl-cdn.alpinelinux.org`. ### Your own image You can run any `linux/amd64` image you've pushed to your workspace's namespace of the registry, `registry.caas.sh//NAME`. [Images and the registry](/docs/images) shows how to push one. - A sandbox on your own image needs size M or larger, or a custom size with at least 4 GiB of memory and 8 GB of disk. - It needs a command, which replaces the image's entrypoint and command. - The command, every later command and file transfer run inside the image's container, with `/workspace` mounted. The image needs `/bin/sh`, `base64`, `tar` and `gzip`, which caas.sh uses to move files and take snapshots. - In the console, pick **Your image** and enter the image by digest, `registry.caas.sh//NAME@sha256:…` (`docker push` prints the digest). - The CLI also takes a tag and pins it to its digest for you: ```sh caas run --image agent:1.2.0 -- node agent.js ``` - The API takes the digest form in `source`: `{ "type": "image", "reference": "registry.caas.sh//agent@sha256:…", "command": ["node", "agent.js"] }`. ## Sizes A size sets the vCPU, memory and disk the sandbox gets: | Size | vCPU | Memory | Disk | | --- | --- | --- | --- | | XS | 1/16 | 256 MiB | 2 GB | | S | 1/4 | 1 GiB | 4 GB | | M (default) | 1/2 | 4 GiB | 8 GB | | L | 1 | 6 GiB | 12 GB | | XL | 2 | 8 GiB | 16 GB | | 2XL | 4 | 12 GiB | 20 GB | A **Custom** size takes whole numbers: 1 to 4 vCPU, at least 3 GiB of memory per vCPU and at most 12 GiB, and 2 to 20 GB of disk. In the console, pick **Custom** and fill in **vCPU**, **Memory (GiB)** and **Disk (GB)**. With the CLI: ```sh caas run --size custom --vcpu 2 --memory 8 --disk 16 -- node task.js ``` A sandbox keeps the size it was created with. While it runs, it bills for its full memory and disk, and for vCPU only while it computes. See [pricing](/pricing.html) for the rates. ## Names A name is optional. It has up to 63 lowercase letters, digits and hyphens, starts and ends with a letter or digit, and is unique among the workspace's sandboxes and MCP servers. The console shows it in place of the ID, and `caas sandboxes list` prints it beside the ID. CLI and API commands take the sandbox's ID. ## Choose what it runs Every sandbox runs a command once, after it first starts: the agent's initial run. The command runs in `/workspace`, as one executable with its arguments and no shell. Its time limit is two hours. To use shell features, run a shell: `sh -c 'node build.js && node test.js'`. The API takes the command as a list of 1 to 32 arguments. On the Default image, the files the command works on come from one of three places. ### A command alone Enter only the **Command**. In the API, the source is `{ "type": "stdio", "command": ["node", "--version"] }`. ### A Git repository In the console, enter a **Repository** (such as `github.com/your-org/agent`) and, unless it's the default branch, a **Branch**. The repository is cloned into `/workspace` before the command runs. In the API: ```json { "type": "git", "url": "https://github.com/your-org/agent", "ref": "main", "command": ["node", "task.js"] } ``` The URL is an HTTPS URL with no username, password or port in it. `ref` is a branch, tag or commit, and defaults to the default branch. The clone happens in a fresh workspace: on the first start, or on every start of a sandbox that doesn't keep state. While it sets up, the sandbox may reach the repository's host even if that host isn't in its allowed outbound hosts. ### An uploaded archive With the CLI, `--from .` packs your Git repository's committed files and uploads them: ```sh caas run node task.js --from . ``` Run it at the repository's root. It refuses a worktree with uncommitted changes or untracked files, and tracked files whose names look sensitive (such as `.env` or `id_rsa`). Ignored files are never uploaded. In the console, when the command runs a file of yours, such as `./run.sh` or `node task.js`, the form asks for a **Source archive**: a `.tar.gz` of your files. With the API, upload a gzipped tar of up to 250 MiB first, then pass its `uploadId` in the source: ```sh tar -czf source.tar.gz -C my-project . curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/uploads \ -H "Authorization: Bearer $CAAS_API_KEY" \ -H "Content-Type: application/gzip" \ --data-binary @source.tar.gz ``` ```json { "type": "stdio", "command": ["node", "task.js"], "uploadId": "" } ``` The archive is unpacked into `/workspace` on the first start. An upload is kept for seven days, so a sandbox started from one must keep state between restarts. ## Run commands You can run more commands in a sandbox at any time. Each one runs in `/workspace` as one executable with its arguments, with a time limit from 1 second to 2 hours. A command sent to a sandbox that stopped while idle starts it first. ### In the console On the sandbox's page: - **Inspect initial run** shows the initial command and its output. - **Run a command** takes a **Command** and a **Time limit** (1 minute to 2 hours; 10 minutes by default). Quote arguments that contain spaces. The result shows each stream's output, or a download link when it's long, with **Refresh** and, while it runs, **Cancel**. ### With the CLI ```sh caas sandboxes exec -- node --version caas sandboxes exec --timeout-ms 3600000 -- sh -c 'node build.js && node test.js' ``` `exec` waits for the command, prints its output, and exits with an error when it fails. `--timeout-ms` takes 1000 to 7200000 (10 minutes by default). With `--detach`, it returns at once with the command's ID: ```sh caas sandboxes command caas sandboxes cancel-command ``` ### With the API Send the command with an `Idempotency-Key` of 8 to 128 letters, digits, `-` and `_`. The key becomes the command's ID, and resending it never runs the command twice. ```sh curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/commands \ -H "Authorization: Bearer $CAAS_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: run-tests-0001" \ -d '{ "command": ["node", "--version"], "timeoutMs": 600000 }' ``` Instead of `command`, you can send `script`, a shell script of up to 131,071 bytes that runs as `/bin/sh -c`. Then read the command, waiting up to 25 seconds for it to end: ```sh curl "https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/commands/run-tests-0001?waitMs=25000" \ -H "Authorization: Bearer $CAAS_API_KEY" ``` The record has the command's `state` (`submitting`, `running`, `succeeded`, `failed`, `timed_out`, `canceled` or `lost`), `exitCode`, and `stdout` and `stderr`. When a stream is short, its `base64` field holds all of it; otherwise download it from `…/commands//stdout` or `…/stderr`. `DELETE …/commands/` cancels a running command. Command records are kept for seven days, at most 1,000 per sandbox. Stopping a sandbox cancels its running commands. ## Read and write files The API reads, writes and deletes single files under `/workspace` or `/tmp` (but not `/workspace/.caas`, which belongs to caas.sh), up to 100 MiB each: ```sh # Write a file, creating its directories curl -X PUT "https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/files?path=/workspace/config.json" \ -H "Authorization: Bearer $CAAS_API_KEY" \ --data-binary @config.json # Read it; add &tail=4096 for only its last 4,096 bytes curl "https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/files?path=/workspace/config.json" \ -H "Authorization: Bearer $CAAS_API_KEY" -o config.json # Delete it curl -X DELETE "https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/files?path=/workspace/config.json" \ -H "Authorization: Bearer $CAAS_API_KEY" ``` A write replaces the whole file. Like a command, a transfer starts a sandbox that stopped while idle; if the sandbox is still starting, you get `503`: try again shortly. Only `/workspace` is kept between restarts: `/tmp` starts empty every time. The bytes you read, like downloaded command output, bill as egress. ## Stop and start Stop a sandbox with **Stop** on its page or in its row's menu in **Sandboxes**, `caas sandboxes stop `, or `POST …/sandboxes//stop`. Start it with **Start**, `caas sandboxes start `, or `POST …/start`. A sandbox that keeps state saves `/workspace` as it stops and gets it back when it starts. A stopped sandbox bills for no vCPU, memory or disk, only for storing its snapshots. ### Idle stop A running sandbox stops by itself after 15 minutes without activity. Commands and file transfers, a command still running, and requests to its URL or its MCP endpoint all count as activity. Set the period, from 5 to 240 minutes, when you create the sandbox: `--idle-stop 60` with the CLI, or `"idleStopMinutes": 60` in the API. ### Wake on request A sandbox that stopped while idle starts again by itself when a command, a file transfer or a request to its URL arrives. A sandbox you stopped yourself stays stopped until you start it, unless you created it with `--wake-on-request` (`"wakeOnRequest": true`). A sandbox also starts only while the workspace has a card on file and a balance above $0. At $0, its sandboxes stop until funds arrive; see [Billing and usage](/docs/billing). After three failed starts in a row, start the sandbox yourself. ### Keep state, or start fresh By default a sandbox keeps `/workspace` between stops and restarts, with automatic and nightly snapshots. A sandbox created without **Keep state between restarts**, with `--ephemeral`, or with `"persistent": false` starts with a fresh workspace every time and takes no automatic or nightly snapshots. You can still take snapshots of it yourself and restore one. A sandbox started from an uploaded archive always keeps state. ## Sandbox URLs A sandbox can serve one HTTP port at its own address, `https://