Upgrade to a full sandbox

Upgrade a light instance to a full sandbox, terminating programs, processes and terminals. Files, sandbox ID and name are preserved. Returns HTTP 200 with sandbox detail and a new envdAccessToken; reconnect with it because the old token is revoked. Migration failure preserves source files but does not restart programs. Own face only; E2B ingress returns 404.

Call Create sandbox first and replace sbx_123 with its returned sandboxID.

POST /sandbox/v1/sandboxes/{sandboxID}/upgrade● Supported

Request parameters

sandboxIDstring必填
path: Sandbox ID.
templateIDstring可选
默认 "base"
Target template, default base (node22 alias). Requires an E2B image or returns INVALID_PARAMS. File, process and data-plane operations return 409 during upgrade.

Returns

200

Errors follow the E2B format — see error codes

Response

HTTP 200

Upgraded sandbox detail with a replacement access token

application/json

Name	Type	Description
templateID	string	Identifier of the template from which is the sandbox created
alias	string	Alias of the template
sandboxID	string	Identifier of the sandbox
clientID	string	Identifier of the client
startedAt	string	Time when the sandbox was started
endAt	string	Time when the sandbox will expire
envdVersion	string	Version of the envd running in the sandbox
envdAccessToken	string	Access token used for envd communication
allowInternetAccess	boolean	Whether internet access was explicitly enabled or disabled for the sandbox. Null means it was not explicitly set.
domain	string	Domain returned for sandbox traffic. Build an HTTP service URL as https://<port>-<sandboxID>.<domain> using the returned values, without replacing or stripping the sandboxID suffix.
cpuCount	integer	CPU cores for the sandbox
memoryMB	integer	Memory for the sandbox in MiB
diskSizeMB	integer	Disk size for the sandbox in MiB
metadata	any	Your own string key/value pairs stored with the sandbox; usable as a filter in listSandboxes.
state	string	State of the sandbox
network	object	Network policy of the sandbox: public access, egress allow and deny lists and proxy.
network.allowPublicTraffic	boolean	Specify if the sandbox URLs should be accessible only with authentication.
network.allowOut	array<string>	List of allowed destinations for egress traffic. Each entry can be a CIDR block (e.g. "8.8.8.8/32"), a bare IP address (e.g. "8.8.8.8"), or a domain name (e.g. "example.com", "*.example.com"). Allowed entries always take precedence over denied entries.
network.denyOut	array<string>	List of denied CIDR blocks or IP addresses for egress traffic. Domain names are not supported for deny rules.
network.egressProxy	object	SOCKS5 proxy for sandbox egress. Outbound TCP is tunneled through the proxy after allow/deny filtering; the sandbox is unaware. Domain-matched flows use remote DNS (ATYP=domain).
network.maskRequestHost	string	Specify host mask which will be used for all sandbox requests
network.httpsPorts	array<integer>	Unlike E2B, network.httpsPorts is rejected; omit it and serve plaintext HTTP inside the sandbox. The public port URL still uses HTTPS. The upstream field denotes HTTPS-speaking internal ports, permits self-signed certificates and excludes envd port 49983.
network.rules	object	Per-domain transform rules applied to matching outbound HTTPS requests. Keys may be exact DNS names (for example, "api.example.com") or a leading wildcard (for example, ".example.com"), and are normalized to lowercase on write. Wildcards match subdomains at any depth but not the apex domain; a bare "" is invalid. Exact rules take precedence, followed by the longest matching wildcard suffix, and matching rule sets are not merged. Broad wildcards such as "*.com" are allowed and may expose transformed credentials to every matching destination the sandbox contacts. Rules do not grant network access; configure allowOut separately to permit the destination.
lifecycle	object	Sandbox lifecycle policy returned by sandbox info.
lifecycle.autoResume	boolean	Whether the sandbox can auto-resume.
lifecycle.onTimeout	string	Action taken when the sandbox times out.
volumeMounts	array<object>	Volumes mounted into the sandbox.
volumeMounts[].name	string	Name of the volume
volumeMounts[].path	string	Path of the volume