Skip to main content

​
Sandboxes

A sandbox is the isolated virtual machine where your AI agent executes its tasks.

​
Sandbox Lifecycle

Runs surface current sandbox info in metadata and thread metadata so that external clients can reattach to desktops (e.g. via VNC). The sandboxStatus field transitions through the following states:
  • initializing → provisioning requested, VM is booting
  • ready → desktop reachable; sandboxId & vncUrl are valid and ready to use
  • restored → an existing sandbox from a previous run was successfully reused
  • failed → provisioning failed; no desktop available

​
Extend Sandbox Lifetime

Sandboxes have a set lifetime to prevent runaway costs. You can extend the lifetime of a sandbox while it is running. POST /api/sandbox/extend Body 
{ 
  "sandboxId": "sandbox_xxx" 
}
Response (200) 
{
  "success": true,
  "message": "Sandbox lifecycle extended by 15 minutes",
  "sandboxId": "sandbox_xxx"
}
Note: Repeated calls before expiry will stack in 15-minute increments.