Create Sandbox
Sandbox API
Create Sandbox
Create a new isolated sandbox sandbox.
POST
Create Sandbox
Provisions a new sandbox VM through the orchestrator. The API waits until the VM
reports a guest IP address before returning — typically 1–5 seconds. The returned
object contains tokens and connection details needed by the SDK.
Request Body
string
Template name to base the sandbox on. Becomes the sandbox
name and is
prefixed with tpl- for the template_id. Defaults to an empty string
(which uses the default base image).Example: "base"integer
Auto-kill timeout in seconds. When the timeout expires the sandbox state is
set to
killed and the VM is terminated. Pass 0 to disable auto-kill.Example: 300object
Environment variables to inject into the sandbox VM. Keys and values must
be strings.Example:
{ "OPENAI_API_KEY": "sk-..." }object
Arbitrary key-value metadata stored with the sandbox. Useful for tagging
sandboxes by project, run ID, or agent name.Example:
{ "project": "my-agent", "run_id": "run-001" }Resource allocation (vCPUs, memory, disk) is fixed at the template level —
the request-level
resources field is currently rejected with HTTP 403. Use
templates to size sandboxes instead.object
Outbound network access controls.
object
Full SecurityPolicy object (PII config, injection defense, transformation rules,
audit config). Passed as a JSON object and stored verbatim. See the
Security section for the complete schema.
object
Controls what happens when the sandbox timeout fires.
Response
Returns a Sandbox object with staterunning.
string
Unique sandbox identifier. Format:
sbx-<8 chars>.string
Template ID used. Format:
tpl-<name>.string
Always
"running" on a freshly created sandbox.string
Bearer token for direct envd daemon access. Used internally by the SDK.
string
Bearer token for the security proxy. Used internally by the SDK.
string
Internal IP address of the sandbox VM.
integer
Port on which envd listens. Typically
49983.string
UTC timestamp of sandbox creation.
Example
Response