Sandbox Quickstart

Create a managed sandbox, run a command in it, and stop it. A sandbox is a Linux VM the platform runs for you. It connects as a remote, so you run commands on it the same way as on your own machine.

→ Managed sandboxes · Inside a sandbox · Limits and pricing · Sandboxes API

Before you start

• belt v1.28.21 or later. Check with belt --version, update with belt update. See CLI setup.
• A signed-in session (belt login) or INFERENCE_API_KEY with the sandboxes:read, sandboxes:write, remotes:read and remotes:write scopes. The standard preset has all four.
• A purchase in the last 30 days on the workspace that pays. Sandboxes need one (see Limits and pricing).

1. Create a sandbox

1belt sandbox create dev --wait

--wait returns once the VM is up and its remote is connected. Without it, create returns at once and the box boots in the background. The default size is 2 vCPUs, 4096 MiB memory and 10240 MiB disk.

Pick a size with --vcpus, --memory and --disk (MiB):

1belt sandbox create build --vcpus 4 --memory 8192 --disk 20480 --wait

2. Run commands

1belt sandbox exec dev -- uname -a2belt sandbox exec dev -- bash -c "git clone https://github.com/octocat/Hello-World && ls Hello-World"3belt sandbox exec dev --cwd /tmp --env CI=1 --timeout 600 -- bash -c "echo \$CI && pwd"

Output streams as it arrives. belt exits with the command's exit code. Commands run as the agent user in /home/agent, and sudo works without a password. See Inside a sandbox for what is installed.

3. Check it

1belt sandbox list2belt sandbox get dev --json

status is running while the VM is up. See Lifecycle for the other states.

4. Stop or delete it

1belt sandbox stop dev --yes      # VM off; disk kept on the engine for the next start2belt sandbox start dev --wait    # boots again, reusing the kept disk when disk_kept is true3belt sandbox delete dev --yes    # removes the sandbox and its remote

A running sandbox is billed until you stop it or it stops itself: after 15 minutes with no exec, agent session or belt sandbox keepalive on it (the default; set it with --idle-timeout, 0 for never). See Idle auto-stop. Files on the writable disk survive a stop and start on the same engine while the disk is kept; see Disk.

From scripts and agents

Add --json to any belt sandbox command for JSON on stdout. Progress and --wait updates go to stderr. Add --no-input so belt never prompts; stop, delete and revoke-grant then need --yes. Exit codes are listed in Exit codes.

1id=$(belt sandbox create ci --wait --jq .id)2belt sandbox exec "$id" -- bash -c "make test"3belt sandbox delete "$id" --yes --no-input

get, create, start and stop print the sandbox object. list prints one page with items, next_cursor and has_next.

From the API

The same steps over HTTP. Exec runs on the sandbox's remote_id through the Exec runs API.

1KEY=inf_your_key2API=https://api.inference.sh34# Create5curl -s -X POST $API/sandboxes \6  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \7  -d '{"name":"dev"}'8# → {"id":"...","status":"pending","remote_id":"...", ...}910# Wait until the sandbox is running and its remote is connected11curl -s $API/sandboxes/SANDBOX_ID -H "Authorization: Bearer $KEY"   # status: running12curl -s $API/remotes/REMOTE_ID -H "Authorization: Bearer $KEY"      # status: running1314# Run a command15curl -s -X POST $API/remotes/REMOTE_ID/execs \16  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \17  -d '{"command":"bash","args":["-c","uname -a"],"timeout_ms":60000}'18# → {"id":"EXEC_ID","status":"running", ...}1920# Read output (data is base64) and the result21curl -s "$API/execs/EXEC_ID/output?after_seq=0" -H "Authorization: Bearer $KEY"22curl -s $API/execs/EXEC_ID -H "Authorization: Bearer $KEY"          # status, exit_code2324# Stop, then delete25curl -s -X POST $API/sandboxes/SANDBOX_ID/stop -H "Authorization: Bearer $KEY"26curl -s -X DELETE $API/sandboxes/SANDBOX_ID -H "Authorization: Bearer $KEY"

Poll every few seconds; belt sandbox create --wait polls every 2 seconds. A sandbox that ends failed says why in status_reason.

Next

• Inside a sandbox: installed tools, network, secrets, files, agents in the box
• Limits and pricing: sizes, plan limits, cost, errors
• Sandboxes API · Exec runs API