# Sandboxes

> Linux machines that you or your agent create in seconds, run commands in, stop, and resume later, from 5¢ an hour.

A sandbox is a Linux machine that you or your agent keep for as long as a task needs. You create it, run commands in it, copy files in and out, and stop it when you are done. A stopped sandbox keeps its files and running processes, and resumes where it left off.

A sandbox has no GPU. To run a job on a GPU, use [Compute](https://docs.divergentlabs.xyz/compute.md).

## Quickstart

This quickstart creates a sandbox, runs a script in it, and stops it.

1. Install `div` and sign in. `div login` opens your browser.

   ```bash
   curl -fsSL https://div.io/install.sh | sh
   div login
   ```

2. Create a sandbox and save its name in `SB`.

   ```bash
   SB=$(div sandbox create)
   ```

   The sandbox is running when the command returns. The output looks like this:

   ```text
   sb-4c1e9a running · small, 1 vCPU, 2 GiB · $0.05/h · runs until stopped
   ```

3. Copy a script into the sandbox and run it.

   ```bash
   echo 'print("hello")' > hello.py
   div sandbox cp ./hello.py $SB:/root/hello.py
   div sandbox exec $SB -- python3 hello.py
   ```

   The output looks like this:

   ```text
   Copied 15 B to sb-4c1e9a:/root/hello.py.
   hello
   ```

4. Stop the sandbox.

   ```bash
   div sandbox stop $SB
   ```

   The output shows the size of the stored data and the total spent. A stopped sandbox costs only its storage. Run `div sandbox resume $SB` to continue, or `div sandbox rm $SB` to delete it.

If you have `ssh` and nothing else, run `ssh div.io` instead. See [Use a sandbox over SSH](https://docs.divergentlabs.xyz/sandboxes/ssh.md).

## What a sandbox has

- Ubuntu 24.04 with Python 3 and `curl`. Install anything else with `apt-get`.
- Root access. Commands run as root in `/root` unless you pass `--cwd`.
- A desktop with Chromium, off until you start it. See [Use the desktop and browser](https://docs.divergentlabs.xyz/sandboxes/desktop.md).
- Claude Code and OpenCode, ready to take a task with `div agent prompt`. They use your own API key or subscription. See [Run a coding agent in a sandbox](https://docs.divergentlabs.xyz/sandboxes/agents.md).
- Internet access, with two exceptions: a sandbox cannot send mail on port 25, and it cannot reach private network addresses.

Some sites block traffic from datacenter IP addresses. To reach them, send the sandbox's traffic through your own machine with [`div sandbox tunnel --exit`](https://docs.divergentlabs.xyz/sandboxes/tunnels.md).

## What persists

| Action | Files | Running processes | Billing |
| --- | --- | --- | --- |
| `stop` | kept | kept | storage only |
| `resume` | restored | restored | by size again |
| `fork` | copied to a new sandbox | not copied | the new sandbox is billed separately |
| `rm` | deleted | ended | stops |

See [Stop, resume and fork a sandbox](https://docs.divergentlabs.xyz/sandboxes/snapshots.md).

## Secrets

A sandbox receives only the org secrets you name with `--secret`. Secret values are masked in the output of `div sandbox exec`. Output in an SSH session is not masked.

- Each sandbox reads its secrets from one [environment](https://docs.divergentlabs.xyz/compute/cli/secrets.md#environments-and-products), `default` unless you pass `--environment`. The same secret name can hold a different value in each environment.
- A named secret must exist in that environment and include `sandboxes` in its products. Otherwise `create` fails with `unknown_secrets`.
- `resume` reads the secrets again from the same environment. A fork uses the source's environment.
- A sandbox that names any secret cannot have a [sandbox token](https://docs.divergentlabs.xyz/sandboxes/cli/sandbox.md#token).

```bash
div secrets env add acme
div secrets set GITHUB_TOKEN --from-env --environment acme
SB=$(div sandbox create --environment acme --secret GITHUB_TOKEN)
```

See [Keep each customer's credentials in its own environment](https://docs.divergentlabs.xyz/sandboxes/environments.md).

## Sizes and prices

| Size | vCPU | Memory | Disk | Per hour |
| --- | --- | --- | --- | --- |
| `small` (default) | 1 | 2 GiB | 10 GiB | $0.05 |
| `standard` | 2 | 4 GiB | 20 GiB | $0.10 |
| `large` | 4 | 8 GiB | 40 GiB | $0.20 |
| `xl` | 8 | 16 GiB | 80 GiB | $0.40 |

A running sandbox is billed by the minute. A stopped sandbox is billed 6¢ per GiB a month for the data it changed, and the first 25 GiB a month is included on every plan. See [Sandbox pricing and plans](https://docs.divergentlabs.xyz/sandboxes/pricing.md) for what each plan includes and allows.

## Next steps

- [`div sandbox`](https://docs.divergentlabs.xyz/sandboxes/cli/sandbox.md): every subcommand and flag.
- [Run a coding agent in a sandbox](https://docs.divergentlabs.xyz/sandboxes/agents.md)
- [Sandbox pricing and plans](https://docs.divergentlabs.xyz/sandboxes/pricing.md)
- [Stop, resume and fork a sandbox](https://docs.divergentlabs.xyz/sandboxes/snapshots.md)
- [Use the desktop and browser](https://docs.divergentlabs.xyz/sandboxes/desktop.md)
- [Add computer use to your product](https://docs.divergentlabs.xyz/sandboxes/computer-use.md)
- [Keep each customer's credentials in its own environment](https://docs.divergentlabs.xyz/sandboxes/environments.md)
- [Reach your machine from a sandbox](https://docs.divergentlabs.xyz/sandboxes/tunnels.md)
- [Use a sandbox over SSH](https://docs.divergentlabs.xyz/sandboxes/ssh.md)
- [Sandbox MCP tools](https://docs.divergentlabs.xyz/sandboxes/mcp.md): the same operations as tools an agent calls directly.
- [TypeScript SDK](https://docs.divergentlabs.xyz/sandboxes/sdk.md): sandboxes, the desktop and the live screen from your own code.