Sandbox Configuration

Each Build project runs in an isolated sandbox — a lightweight container with its own filesystem, CPU, memory, and network. Configure sandbox resources and permissions to match your project requirements.

Resource Limits

Control the compute resources allocated to each sandbox:

build.json
json
{
  "sandbox": {
    "cpu": 4,
    "memory": "8gb",
    "disk": "10gb",
    "timeout": "30m"
  }
}
cpunumber21-8CPU cores allocatedmemorystring4gb1gb-16gbRAM allocateddiskstring5gb1gb-50gbPersistent disk spacetimeoutstring10m1m-60mMax idle time before sandbox sleeps

Network

Control outbound network access for the sandbox:

build.json
json
{
  "sandbox": {
    "network": {
      "outbound": true,
      "allowedDomains": ["api.example.com", "registry.npmjs.org"],
      "blockedDomains": [],
      "previewUrl": true
    }
  }
}
outboundbooleantrueAllow outbound network requestsallowedDomainsarray[]Restrict to these domains (empty = all)blockedDomainsarray[]Block specific domainspreviewUrlbooleantrueGenerate a live preview URL

Permissions

Sandbox permissions control what agents can do within the environment:

build.json
json
{
  "sandbox": {
    "permissions": {
      "filesystem": "read-write",
      "shell": true,
      "envAccess": true,
      "packageInstall": true,
      "git": true
    }
  }
}
filesystemread-only, read-writeread-writeFile system access levelshellbooleantrueAllow shell command executionenvAccessbooleantrueRead environment variablespackageInstallbooleantrueInstall new packages at runtimegitbooleantrueGit operations inside sandbox

Lifecycle

Sandboxes follow a lifecycle: creating, running, sleeping, and stopped. A sandbox transitions to sleeping after the idle timeout. Sleeping sandboxes preserve disk state but release CPU and memory. Any interaction (agent action, preview request) wakes the sandbox in seconds.

iNote
Sandbox state (files, installed packages) persists across sleep/wake cycles but is reset when you rebuild the project or clear the sandbox.
PreviousProjectsNextAgents