First sandbox
A sandbox is a Linux VM with its own cores. The API lives at https://api.groundbox.dev/v1. Send your key as Authorization: Bearer gbx_.... Sandboxes are on the paid plan.
Start, exec, files
1. Start a sandbox
curl https://api.groundbox.dev/v1/sandboxes \
-H "Authorization: Bearer $GROUNDBOX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"cpus": 2, "timeout_minutes": 60}'Defaults: 2 vCPUs (from 1 to 8), 2 GB of RAM per vCPU (up to 4), a 20 GB disk, and it stops after 60 minutes. The longest timeout is 24 hours; renew it with PATCH. Send Idempotency-Key so a retry never starts, and bills, two sandboxes. The response has the sandbox id, which starts with sbx_.
2. Run a command
curl https://api.groundbox.dev/v1/sandboxes/sbx_.../exec \
-H "Authorization: Bearer $GROUNDBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cmd": "git clone https://github.com/you/app && cd app && npm test"}'The command runs with sh -c. You get back the exit code and output:
{
"exit_code": 0,
"stdout": "...",
"stderr": "",
"duration_ms": 41873,
"timed_out": false
}3. Move files
# Upload a file
curl -X PUT "https://api.groundbox.dev/v1/sandboxes/sbx_.../files?path=/work/input.json" \
-H "Authorization: Bearer $GROUNDBOX_API_KEY" \
--data-binary @input.json
# List a folder
curl "https://api.groundbox.dev/v1/sandboxes/sbx_.../files?dir=/work" \
-H "Authorization: Bearer $GROUNDBOX_API_KEY"4. Delete it
curl -X DELETE https://api.groundbox.dev/v1/sandboxes/sbx_... \
-H "Authorization: Bearer $GROUNDBOX_API_KEY"Billing stops when the sandbox stops.
Fork
Fork a running sandbox. The copy has the same files and running processes, and its own id.
curl -X POST https://api.groundbox.dev/v1/sandboxes/sbx_.../fork \
-H "Authorization: Bearer $GROUNDBOX_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Pause and resume
A paused sandbox keeps its memory and disk and is billed for storage only, at $0.05 per GB-month. Resume brings it back as it was.
curl -X POST https://api.groundbox.dev/v1/sandboxes/sbx_.../pause \
-H "Authorization: Bearer $GROUNDBOX_API_KEY"
curl -X POST https://api.groundbox.dev/v1/sandboxes/sbx_.../resume \
-H "Authorization: Bearer $GROUNDBOX_API_KEY"Scheduled runs
A schedule is a cron expression, a sandbox spec and a command. Each run gets a fresh sandbox, which is destroyed when the command exits.
curl https://api.groundbox.dev/v1/schedules \
-H "Authorization: Bearer $GROUNDBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cron": "0 3 * * *", "timezone": "UTC", "cmd": "./run-evals.sh", "sandbox": {"cpus": 4}}'Egress allowlist
Set allow_hosts to choose the hosts a sandbox can reach. Everything else is blocked.
curl https://api.groundbox.dev/v1/sandboxes \
-H "Authorization: Bearer $GROUNDBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"cpus": 2, "allow_hosts": ["github.com", "registry.npmjs.org"]}'