Create a sandbox (E2B)
E2B's `POST /v2/sandboxes`. Claims a warm microVM of the template (`base`, `code-interpreter`, `agent` or `browser`; E2B's default `base`), with `envVars`, `metadata` and `timeout` (seconds, default 300, at most the plan's limit). `autoPause: true` pauses the sandbox at its timeout instead of stopping it. Egress: `allow_internet_access: false` or `network.denyOut: ["0.0.0.0/0"]` alone denies all; that `denyOut` with `network.allowOut` hosts allows only those hosts (ports 80 and 443 unless named). The key needs `sandboxes:run` as well as `sandboxes:write` (`403` without it), since the answer's `envdAccessToken` grants `sandboxes:run` on the new sandbox. `Idempotency-Key` (the SDKs send one): a repeat with the same key and body from the same key returns the same sandbox with a new envd access token (the earlier one stays valid 60 seconds), for 24 hours; the token itself is never stored. Bills `sandboxes.vcpu_ms` and `sandboxes.gib_ms` while the sandbox runs.
POST
/compat/e2b/v2/sandboxes
E2B's `POST /v2/sandboxes`. Claims a warm microVM of the template (`base`, `code-interpreter`, `agent` or
`browser`; E2B's default `base`), with `envVars`, `metadata` and `timeout` (seconds, default 300, at most
the plan's limit). `autoPause: true` pauses the sandbox at its timeout instead of stopping it. Egress:
`allow_internet_access: false` or `network.denyOut: ["0.0.0.0/0"]` alone denies all; that `denyOut` with
`network.allowOut` hosts allows only those hosts (ports 80 and 443 unless named). The key needs
`sandboxes:run` as well as `sandboxes:write` (`403` without it), since the answer's `envdAccessToken`
grants `sandboxes:run` on the new sandbox.
`Idempotency-Key` (the SDKs send one): a repeat with the same key and body from the same key returns the
same sandbox with a new envd access token (the earlier one stays valid 60 seconds), for 24 hours; the
token itself is never stored. Bills `sandboxes.vcpu_ms` and `sandboxes.gib_ms` while the sandbox runs.
Authentication
Bearer Token (b3os_sk_ API key or b3os_pat_ token)
Header Parameters
Idempotency-Key
string
optional
header
A value the SDKs send to make the create safe to retry. A repeat with the same key and body from the same key returns the same sandbox, with a new envd access token, for 24 hours; another body with the same key is refused with `409`. The token is never stored.
Request Body required
application/jsontemplateID
string
`base` (default), `code-interpreter`, `agent` or `browser`, or a template's `tpl_` id.
timeout
integer
Seconds until the sandbox ends (default 300).
metadata
object
envVars
object
autoPause
boolean
Pause instead of stopping at the timeout.
autoPauseMemory
boolean
`false` (a filesystem-only pause) is refused.
autoResume
object
Refused when `enabled` is true.
allow_internet_access
boolean
network
object
`allowOut` hosts, and `denyOut: ["0.0.0.0/0"]`; other fields are refused.
mcp
object
Refused.
volumeMounts
object[]
Refused.
Array of:
object
iam
object
Refused.
Responses
201
The sandbox, running, with its envd access token.
application/jsonsandboxID
string
REQUIRED
templateID
string
REQUIRED
clientID
string
REQUIRED
envdVersion
string
REQUIRED
The envd protocol version the SDKs check features against.
envdAccessToken
string
REQUIRED
The envd access token (`b3os_et_…`): valid at most 1 hour, while the sandbox is running or paused and the key that minted it is not revoked. Returned only here and by connect.
domain
string | null
400
A malformed value, or an option B3OS cannot honor named in the message (`invalid_request`, `unsupported_option`).
401
Missing or invalid B3OS key in `X-API-KEY` (`unauthorized`).
403
The key lacks a scope the operation needs (`forbidden`).
404
No such live sandbox, template or file (`sandbox_not_found`, `template_not_found`, `file_not_found`).
429
Over a limit of the organization (`limit_exceeded`, `rate_limited`); `Retry-After` says when.
curl -X POST 'https://beta-api.b3os.org/compat/e2b/v2/sandboxes' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "templateID": "base", "timeout": 300, "metadata": { "run": "demo" }, "envVars": { "GREETING": "hello" }}'const response = await fetch('https://beta-api.b3os.org/compat/e2b/v2/sandboxes', { method: 'POST', headers: { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ "templateID": "base", "timeout": 300, "metadata": { "run": "demo" }, "envVars": { "GREETING": "hello" } })});const data = await response.json();console.log(data);import requestsheaders = { 'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://beta-api.b3os.org/compat/e2b/v2/sandboxes', headers=headers, json={ "templateID": "base", "timeout": 300, "metadata": { "run": "demo" }, "envVars": { "GREETING": "hello" }})print(response.json())
201
Response
{ "sandboxID": "sbx-01m5t68q1b590rj801nbzsqzkk", "templateID": "base", "clientID": "b3os", "envdVersion": "0.5.7", "envdAccessToken": "b3os_et_BeHVb2oQkV3ZzHdpPJ2b0rlwxn6jQe7fT1sfJk0Uf2c", "domain": null}API Playground
Try this endpoint
POST
/compat/e2b/v2/sandboxes