Skip to main content
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: 300
object
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 state running.
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

Error Responses