Stop, resume and fork a sandbox

This guide shows how to stop a sandbox when you are not using it, resume it, and fork it into a copy.

Stop a sandbox

div sandbox stop $SB

The sandbox keeps its files, installed packages and running processes. From now on it is billed for storage only.

Changes are saved when a sandbox stops. If a running sandbox fails, changes since its last stop can be lost. Stop a sandbox before you leave it if its state matters.

Resume a sandbox

div sandbox resume $SB

The sandbox continues where it stopped, within a few seconds. Servers are listening again, builds continue, and an open desktop comes back with its windows.

Stop a sandbox automatically when idle

A sandbox runs until you stop it, unless you set an idle timeout.

1. Set the timeout when you create the sandbox:

   SB=$(div sandbox create --idle 15m)

2. To change it later, or to turn it off:

   div sandbox set $SB --idle 2h
   div sandbox set $SB --idle 0

These count as use: running a command, copying a file in or out, an open SSH session, and a coding agent’s running turn. A process running inside the sandbox does not count. A server or training job with no one connecting to the sandbox is idle.

If you want a sandbox to keep running while no one uses it, leave the timeout at 0.

If an agent creates sandboxes for you, set a timeout. A forgotten sandbox then costs storage instead of its hourly price.

Fork a sandbox

FORK=$(div sandbox fork $SB --name try-b)

The fork is a new running sandbox with a copy of the source’s files at this moment. It has the source’s size, secrets, secrets environment and idle timeout, and its own bill. The source can be running or stopped and does not change.

The fork does not copy running processes or the desktop. Start any servers again in the fork.

If you want to try two fixes side by side, fork before the change, try one fix in each sandbox, and delete the one you do not keep with div sandbox rm.

Set up once, fork for each task

1. Create a base sandbox and install what every task needs.

   BASE=$(div sandbox create --name base --size standard)
   div sandbox exec $BASE 'apt-get update && apt-get install -y git nodejs npm'
   div sandbox exec $BASE 'git clone https://github.com/acme/app && cd app && npm ci'

2. Stop it.

   div sandbox stop $BASE

3. Fork it for each task.

   SB=$(div sandbox fork base)
   div sandbox exec $SB 'cd app && npm test'

A fork of a base where the browser is signed in to a site is signed in too. See Use the desktop and browser.

About stopped sandboxes

What is kept. A stopped sandbox keeps its memory and disk: files, installed packages and running processes. It is kept until you delete it with div sandbox rm.

What it costs.

State	Billed
Running	By size, per minute, with a one-minute minimum
Stopped	6¢ per GiB a month for the data the sandbox changed. The operating system it started from is not counted.
Deleted	Nothing

A sandbox that cloned a repository and installed its dependencies costs about what they take up on disk.

Why a sandbox stopped. A sandbox stops when you stop it, when it reaches its idle timeout, when its coding agents finish, or when the org reaches its usage limit or runs out of credit with no card on file. It is never deleted, and it does not restart by itself. div sandbox ls --json shows the reason in stopped_reason: requested, idle, agents_finished or limit_reached.

For every flag, see div sandbox.