divergent/docs
Sandboxes

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.

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.

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

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

    SB=$(div sandbox create)

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

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

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

    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:

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

  4. Stop the sandbox.

    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.

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

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.

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

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 for what each plan includes and allows.

Next steps

esc