Open-source, secure environment with real-world tools for enterprise-grade agents.
@e2b/python-sdk
2.59.0
Minor Changes
- e5a9fa6: Add
dnsServersto the network options (dns_serversin Python): the DNS servers a sandbox can reach whenallowOutcontains a domain. Leave it out to allow the default, 8.8.8.8, pass a list of IPs to allow those instead, or pass[]to allow none. It only opens the firewall and doesn't change the sandbox's/etc/resolv.conf.updateNetwork/update_networkreset it to the default when it is left out, like the other fields, andgetInfo/get_inforeport it when set.
Patch Changes
- 5a714f0: Deprecate the
apiUrl/api_urlandsandboxUrl/sandbox_urlconnection options and theirE2B_API_URLandE2B_SANDBOX_URLenvironment variables. They keep working for now and will be removed in the next major version. - 61b6b55: Use the unified
https://sandbox.<domain>endpoint for sandbox traffic one2b-tango.dev,e2b-juliett.devandfoxtrot-2.e2b.dev. - 2cd2305: fix(python-sdk): don't crash the build error path on a non-numeric reason.step
2.58.0
Minor Changes
- 3c4c7cf: - JS:
sandbox.commands.streamInput(pid)/sandbox.pty.streamInput(pid)return aCommandInputHandlethat sends ordered stdin/PTY input over oneStreamInputRPC.- Python async:
stream_input(pid)returns anAsyncCommandInputHandle; Python sync:stream_input(pid, data)blocks while it sends an iterable of input.
- Python async:
Patch Changes
- d7ed073: Remove Python 3.10 compatibility shims (Python >=3.11 is already required).
2.57.0
Minor Changes
- a1ad326: Add
tlsto the egress proxy options astrueor{ serverName?, caCert? }(server_name/ca_certin Python);getInfo/get_inforeports it without the CA.
Patch Changes
- f572bc7: Bump
protobuf-py(including nativeprotobuf-py-ext) to 0.6.0 andconnectrpcto 0.12.1 - 999782e: Share the process kill implementation between commands and PTY, share the CLI
--languageoption parser betweentemplate initandtemplate migrate, and drop unused internal exports
2.56.0
Minor Changes
- 547decc: Require Python 3.11 or newer (Python 3.10 is no longer supported).
- 775f017: Balance HTTP/2 streams with pyqwest's native connection pool instead of a Python-side balancer over multiple transports. The pool dials a new connection once every existing one is at the server-advertised concurrent-stream limit, capped at
E2B_MAX_CONNECTIONS(default200) connections per resolved address.E2B_STREAMS_PER_CONNECTIONis removed — the limit now comes from the server'sSETTINGS_MAX_CONCURRENT_STREAMS.
Patch Changes
- Updated dependencies [547decc]
2.55.1
Patch Changes
- 29064bc:
ConnectionConfig.get_sandbox_url/get_sandbox_direct_urltake an optionalport(defaults to the envd port).
2.55.0
Minor Changes
b52cd30: Add
mode: 'full' | 'filesystem'(exported as theSnapshotModetype) tocreateSnapshot/create_snapshot. With'filesystem', only the filesystem is persisted: the snapshot is smaller and faster to take, and sandboxes created from it cold-boot (start fresh from disk) instead of restoring memory. The source sandbox keeps running either way. Omitted, the API default (a full memory snapshot) applies.pause()and thelifecycle.onTimeout/lifecycle["on_timeout"]pause object form accept the samemode. TheirkeepMemory/keep_memoryoption is deprecated in favor of it (keepMemory: falseismode: 'filesystem') and keeps working; passing both is anInvalidArgumentError/InvalidArgumentException.
Patch Changes
- 0894595: Remove dead empty-chunk guards from command output handling; envd never sends empty output chunks, so behavior is unchanged.
2.54.0
Minor Changes
- cc85f69: Replace the third-party Dockerfile parsers (
dockerfile-ast,dockerfile-parse) used byTemplate.fromDockerfile/Template.from_dockerfilewith a built-in parser ported from BuildKit. Quoted and escaped values inENV/ARG/COPY, whitespace insideRUN/CMDarguments, mixed-caseASaliases, comments in line continuations, the# escape=directive,COPY --chmod, heredocs andENTRYPOINT+CMDcombination are now handled consistently in both SDKs. A.dockerignoreline consisting of a lone!is now rejected, as Docker does, instead of being skipped.
Patch Changes
- Updated dependencies [cc85f69]
2.53.1
Patch Changes
- cd4c62b: Publish the changes from the previous release, which was versioned but failed to publish to npm and PyPI.
2.53.0
Minor Changes
1de92fc: Add
SandboxNotRunningError/SandboxNotRunningExceptionandSandboxUnreachableError/SandboxUnreachableExceptionfor envd requests that fail because the sandbox cannot be reached. Both extendTimeoutError/TimeoutException, which these cases raised before, so existinginstanceof TimeoutError/except TimeoutExceptionhandling keeps working.SandboxNotRunning*— the proxy answered502 "The sandbox was not found"(killed, paused or timed out), either directly or from the health probe the SDK runs after a dropped connection or an unexplainedUnavailable(e.g. the sandbox was killed mid-command). Retrying will not help.SandboxUnreachable*— the sandbox is not confirmed stopped but cannot be reached:502 "port is not open", other502s, or a connection failure whose health probe got no answer. The original error is thecause/__cause__.- A connection failure whose health probe finds the sandbox running still raises the original transport error. The probe itself runs without connection retries.
Breaking (JS):
commands.run/connect,pty.create/connectandfiles.watchDiron a gone sandbox now throwSandboxNotRunningErrorinstead ofSandboxNotFoundError, like every other call.SandboxNotFoundErroris only raised by the control plane API.
Patch Changes
8f51c9f: Share the sandbox create/connect/fork response mapping (JS and Python) and the Python
Commands.run/Commands.connecthandle setupb3bb653: Remove the
E2B_USER_AGENT_SOURCEenvironment variable. The SDKs no longer add asource/<value>User-Agent token, append?source=to Code Interpreter requests, or log trace IDs and add(trace_id=…)to error messages when it is set toci, so SDK behavior no longer depends on that variable.Code Interpreter errors for statuses other than 404 and 502 now use the same
<status> <reason>[: <body>]message in JS and Python: JS includes the response body, and Python falls back to the reason phrase when the body is empty.
2.52.1
Patch Changes
- cc29617: Match BuildKit when filtering the template build context with
.dockerignore: a leading**followed by literal characters (e.g.**.txt) now matches at any depth, a negated pattern matching only a parent directory (e.g.src/app.tsthen!src) no longer re-includes the path, and in the JS SDK?and bracket expressions match characters outside the BMP (e.g. emoji) as a single character. - 3ba1d05: Retry a
502response only for operations that are safe to replay: a gateway may answer502after the API already processed the request, so a502from sandbox creation, fork, snapshot or another resource-creatingPOSTis returned instead of being retried (which could create a duplicate).503is still retried for every operation. Secret updates (POST /secrets/{id}) are no longer replayed after a502or a dropped connection, as each update appends a new version.
2.52.0
Minor Changes
2de0cc3: Cap sandbox fork count at 20.
e2b sandbox fork --count, JavaScriptSandbox.fork({ count }), and PythonSandbox.fork(count=...)reject a count outside 1–20 before the API call. Counts from 21 through 100 used to reach the API. Omitting count still leaves the field off the request so the API default applies.03887ad: Apply
.dockerignoreandfileIgnorePatterns/file_ignore_patternsthe way Docker does when copying files into a template, so ignored files are no longer uploaded or included in the files hash:- A pattern that matches a directory (
node_modules,.git,dist/) now excludes everything under it, and a leading/is ignored. !patterns re-include paths; the last matching pattern wins.- In Python, patterns now also apply when the copied path contains
.or..segments (for examplecopy(".")). fileIgnorePatterns/file_ignore_patternsare applied after the.dockerignorelines, so they take precedence.- Absolute patterns pointing into the context directory are treated as relative to it.
- Brace expansion (
{a,b}) is not supported, as in Docker. In JS,fileIgnorePatternssuch as**/*.{env,pem}previously expanded and now match{env,pem}literally; list each pattern separately instead (**/*.env,**/*.pem). - In Python, copying a symlink to a directory copies the link itself instead of the directory's contents, as in JS.
- Copying a path inside an ignored directory now fails with "No files found", as in Docker. An invalid pattern (such as an unterminated
[) now raises an error.
Directory sizes are no longer part of the files hash, since they depend on the filesystem rather than on the copied files. The files hash of
copy()steps that copy directories or are affected by ignore patterns changes once, so those steps are rebuilt on the next build.- A pattern that matches a directory (
2f92cc3: Add an
http_version(Python) /httpVersion(JS) connection option,"1.1"or"2"(default), also settable with theE2B_HTTP_VERSIONenvironment variable, to pin requests to the E2B API, to sandboxes (commands, filesystem, PTY) and to volume content to HTTP/1.1. It can also be bound once on a client:E2B(http_version="1.1")/new E2B({ httpVersion: '1.1' }).
Patch Changes
- 97522f8: Retry control-plane HTTP requests after
502and503responses, in addition to429, and after a network error once the request was written (dropped connection) — except forPOSToperations not known to be safe to replay (sandbox creation, fork, snapshot, volume/secret/API-key/webhook creation), which the server may already have processed. Failures to establish the connection keep being retried for every operation (E2B_CONNECTION_RETRIES).Retry-Afteris honored when the server sends one; otherwise retries back off exponentially with jitter, starting at 0.1 seconds and capped at 10 seconds. The existingretriesoption (default 3,0to disable) and request-timeout budget apply to all of them. - f713914: Sandbox
commands/filestraffic is now balanced across HTTP/2 connections the way the JS SDK's undici agent does it, instead of being sharded into a fixed number of pools by sandbox ID. Every request goes to the connection with the fewest streams in flight to its host; a new connection is dialed only when all existing ones already carryE2B_STREAMS_PER_CONNECTIONstreams to that host (default100), up toE2B_MAX_CONNECTIONS(default200). Envd RPC and HTTP calls share the same connections.E2B_ENVD_POOL_SHARDSand thepool_shardargument of the internal transport factories (get_transport,get_httpx_transport,get_pyqwest_transport,get_envd_transport) are removed. - 4975149: Remove unused internal constants and attributes, and share the command handle setup between
Commands.runandCommands.connect
2.51.0
Minor Changes
5c0f6eb: Remove SDK-side defaults from API request payloads so the API defaults apply when options are omitted. Sandbox create/fork/connect no longer preset a 5-minute timeout, fork no longer presets
count: 1, create no longer presetsallow_internet_access, pause no longer presets keeping memory, and template builds no longer preset CPU/memory. Explicitly provided values are still sent unchanged.Sandbox create and connect now use the v2 API endpoints (
POST /v2/sandboxes,POST /v2/sandboxes/{id}/connect), which defaulttimeoutto 5 minutes and always secure envd access. Thesecureoption onSandbox.createis deprecated: every sandbox is secured, so the option is still accepted but ignored.
Patch Changes
- 5c0f6eb: Remove client-side validation of the fork
countargument. The API validates the requested fork count and rejects invalid values.
2.50.0
Minor Changes
5b015ad: Removed the V1 template build operations and schemas from the generated API clients. The API no longer serves them (runtime
87968fc1e1fa); control planes carrying that change answer410 Gone. Template builds go through the Template SDK.Visible removal, classified minor: the JS
pathsnamespace losesPOST /templates,POST /templates/{templateID},POST /templates/{templateID}/builds/{buildID}andPOST /v2/templates, andcomponents['schemas']losesTemplateLegacy,TemplateBuildRequestandTemplateBuildRequestV2; the Pythone2b.api.client.modelspackage losesTemplateLegacy,TemplateBuildRequestandTemplateBuildRequestV2, ande2b.api.client.api.templatesloses thepost_templates,post_templates_template_id,post_templates_template_id_builds_build_idandpost_v2_templatesmodules. No SDK method accepted or returned them; code that imported these names directly must drop the import.The regenerated clients also pick up a documented
429on most operations, a409on template create (v3), the upload-requestheaderson the build file-upload link,minLength: 1on the v2 build source fields, and a deprecation marker on the always-emptylogsfield of the build status.
Patch Changes
- 956e3ab: Apply the request headers the API returns with a template layer-file upload link. Azure Blob Storage requires
x-ms-blob-typeon the upload request, which its signed URL cannot carry, soCOPYinstructions failed on Azure-backed clusters. GCS- and S3-backed clusters return no headers and are unaffected.
2.49.1
Patch Changes
- 5e418dc: Document that
onResume/on_resumeneeds a control plane that knows the option: an older self-hosted or BYOC control plane drops thememoryfield and restores memory while reporting success, instead of rejecting the request. - 9136603: Retry control-plane HTTP requests up to three times after
429responses using the server's delta-secondsRetry-Afterdelay. Retries can be configured or disabled withretries, and stop when waiting would exhaust the request timeout. Envd requests, including filesystem operations, and volume-content requests are not retried.
2.49.0
Minor Changes
- f842aa8: Expose a configurable minimum free-disk target with
minFreeDiskMbin JavaScript,min_free_disk_mbin Python, and--min-free-disk-mbintemplate create. Omission uses the team default, while explicit zero requests no minimum growth. Growth is best effort and never shrinks an existing filesystem.
2.48.0
Minor Changes
- 08efa36: Add
httpsPorts(JS) /https_ports(Python) to the sandbox network config. Ports listed there have their public URLs proxied to the sandbox over HTTPS — use it when the service listening on the port serves TLS itself. This is not TLS passthrough: traffic is still terminated at the E2B proxy and re-encrypted on the hop to the sandbox, and the backend certificate is not verified, so self-signed certificates work. The configured ports are also returned in the sandbox info network config. - 6b759bf: Add
ServiceBusyError(JavaScript) /ServiceBusyException(Python) for HTTP 503 responses: the API refused the operation because the service or the node running the sandbox is temporarily busy, the sandbox is unchanged, and the call can be retried. A refusedpause()is the first case. The baseSandboxError/SandboxExceptionalso carries the HTTP status asstatusCode/status_codewhen the error came from an API response, so callers can branch on the status without parsing the message. LikeAuthenticationError/AuthenticationException, the new class does not subclass the sandbox base error: it is raised for every 503 whatever the operation, so catch it explicitly.
Patch Changes
- 58c81f1:
onTimeout/on_timeoutandonResume/on_resumenow raiseInvalidArgumentError/InvalidArgumentExceptionfor a value outside their two literals, instead of silently resolving it to the other one. Both are resolved into a boolean before the request is built, so the value never reaches the API and a typo cannot be rejected server-side:on_timeout="Pause"previously resolved tokilland deleted the sandbox and its snapshot at timeout, andon_resume="Reboot"previously restored the memory the caller asked to skip. A nullish value still means "not configured" and leaves the choice to the API.
2.47.0
Minor Changes
- 1980d6b: Add
onResume/on_resumetoSandbox.connect():'reboot'resumes a paused sandbox from its disk state alone, leaving the memory snapshot untouched, for the case where restoring that memory wedges the guest.'restore'stays the default. Where filesystem-only resume is not enabled, a'reboot'that would actually drop memory is rejected with an error rather than silently restoring it. - 043d050: Removed generated types for endpoints the SDKs never exposed. The JS
components['schemas']namespace and the Pythone2b.api.client.modelspackage no longer include the admin, cluster/rig, node, team-API-key and access-token schemas (Node,NodeDetail,NodeMetrics,NodeStatus,NodeStatusChange,MachineInfo,DiskMetrics,Rig*,Admin*,TeamAPIKey,NewTeamAPIKey,CreatedTeamAPIKey,UpdateTeamAPIKey,IdentifierMaskingDetails,VolumeToken; Python additionallyTeam,TeamMetric,MaxTeamMetric,CreatedAccessToken,NewAccessToken). No SDK method ever accepted or returned them, so code that uses the SDK through its methods is unaffected; code that imported these type names directly must drop the import.
2.46.4
Patch Changes
- 6146cd0: Improve reliability for high-concurrency sandbox workloads by spreading envd traffic across four HTTP/2 connection pools. Set
E2B_ENVD_POOL_SHARDSbefore importing the SDK to adjust the pool count.
2.46.3
Patch Changes
- c275393: Improve reliability for high-concurrency sandbox workloads by spreading envd traffic across four HTTP/2 connection pools. Set
E2B_ENVD_POOL_SHARDSbefore importing the SDK to adjust the pool count.
2.46.2
Patch Changes
- 7dd5321: Spread envd traffic across four HTTP/2 connection pools by default so high-concurrency, long-running streams do not all contend for one connection's stream limit. Set
E2B_ENVD_POOL_SHARDSbefore importing the SDK to tune the pool count.
2.46.1
Patch Changes
- d4a7f41: Deprecate the sandbox git module (
sandbox.git) and its public types and errors. Run git through the commands module instead, e.g.sandbox.commands.run('git clone <url> repo'). The module keeps working and will be removed in the next major version.
2.46.0
Minor Changes
- 9d1c90d: Remove client-side API key format validation. The SDK no longer checks that the API key matches the
e2b_hex format — only that a key is present. ThevalidateApiKey/validate_api_keyoption is deprecated and has no effect, and theE2B_VALIDATE_API_KEYenvironment variable is no longer read. The server remains the source of truth for key validity.
Patch Changes
67c06e0: Point the two Code Interpreter README links at
code-interpreting/analyze-data-with-aiinstead of thecode-interpretingsection index. The index has no landing page and 307s to that article, dropping the query string on the way, so the UTM parameters were lost before the reader arrived. Linking at the resolved path keeps them.182b498: Point the README documentation links at
docs.e2b.devinstead ofe2b.dev/docs. The docs site moved to its own subdomain and has no/docspath prefix there, soe2b.dev/docsserves a 308 todocs.e2b.dev/ande2b.dev/docs/code-interpretingmaps todocs.e2b.dev/code-interpreting. The UTM parameters are unchanged and survived the redirect, so this removes a redirect hop rather than fixing broken attribution.b802997: Fix two
network.egressProxy/network["egress_proxy"]cases an untyped caller reaches.The JS SDK had no shape guard:
buildEgressProxyBodyrebuilds the body from the known fields, so anaddressthat was missing or not a string vanished and the caller got an API error about a config they never wrote ({"egressProxy":{}}). It now raisesInvalidArgumentErrornaming the option, the way the Python SDK already did:// InvalidArgumentError: network egressProxy must be an object with a string // 'address' (e.g. 'proxy.example.com:1080'). await Sandbox.create({ network: { egressProxy: 'proxy.example.com:1080' as never }, })A
null/Noneusername or password is now treated as absent instead of being serialized as a JSON null the API rejects — reading a credential out of an unset environment variable is how a caller lands there, and it means the proxy takes no credentials:await Sandbox.create({ network: { egressProxy: { address: 'proxy.example.com:1080', // Unset in the environment; the proxy takes no credentials. username: process.env.PROXY_USER, }, }, })Sandbox.create( network={ "egress_proxy": { "address": "proxy.example.com:1080", "username": os.environ.get("PROXY_USER"), }, }, )
2.45.1
Patch Changes
- b17b726: Stop the shared retrying transports from mirroring streamed request bodies in
memory. pyqwest's retry middleware keeps a non-
bytesbody replayable by copying it as it is sent, so a streamedfiles.writeof a file-like object orvolume.write_filegrew a full in-RAM mirror and peak memory scaled with file size. The transports now declare pyqwest'sRetryMode.UNBUFFERED: a streamed body is replayed only while nothing has been read from it, which is all the SDK's connect-only retry policy needs — aConnectionErroris raised only before the request was written. Connect retries are unchanged, andbytesbodies (unary RPC payloads, in-memory writes) were already replayable without a copy.
2.45.0
Minor Changes
- 8787dfe: Add sorting and new filters to
Sandbox.list. Theorderoption ('asc'/'desc', default'desc') sorts sandboxes by start time across the whole paginated dataset, and the query now supportsstartedAfter/started_after(inclusive lower bound on start time) andtemplate(exact template ID or alias) filters, all applied server-side before pagination. The CLIe2b sandbox listcommand exposes these via--order,--started-after, and--template.
2.44.0
Minor Changes
5759f17: Add an
E2Bclient that binds a connection config once and exposes the resource surfaces off it, so a single process can talk to several API keys, domains or deployments. The classes it exposes are per-client subclasses of the realSandbox/Volume/Template/Secretclasses, so they behave exactly like the top-level ones — per-call options still win over the client's options, which win over the environment variables. The named top-level exports are unchanged and keep reading the environment.Nothing existing changes:
Templateis now theTemplateBaseclass made callable as a factory, soTemplate(...), the statics andinstanceofkeep working, and the default export is stillSandbox.import { E2B } from 'e2b' const { Sandbox, Volume, Template, Secret } = new E2B({ apiKey: 'e2b_***', domain: 'e2b.dev', }) const sandbox = await Sandbox.create() const volume = await Volume.create('my-volume') const exists = await Template.exists('my-template') await Template.build(Template().fromPythonImage('3'), 'my-env') await Secret.create('openai-api-key', 'sk-***')from e2b import E2B client = E2B(api_key="e2b_***", domain="e2b.dev") Sandbox, Volume, Template = client.Sandbox, client.Volume, client.Template Secret = client.Secret sandbox = Sandbox.create() volume = Volume.create("my-volume") exists = Template.exists("my-template") secret = Secret.create("openai-api-key", "sk-***") # Async variants are exposed too. AsyncSandbox = client.AsyncSandbox async_sandbox = await AsyncSandbox.create()
2.43.0
Minor Changes
- f89f8c3: Add Secrets Management to the SDK. The
Secretclass (andAsyncSecretin Python) now manages E2B secrets:createandupdatestore secret values (write-only — no read surface returns them),getInfo/get_infoand the paginatedlistread metadata,existsanddestroyare idempotent existence and lifecycle helpers, andfillformats the${e2b.secrets.name}placeholder that the runtime resolves to the secret's current value.
Patch Changes
- 2be6c12: Internal refactor: the template API operations resolve their connection config through a class-level hook, so a
TemplateBasesubclass can carry bound connection options. No behavior change —Template/AsyncTemplatekeep reading config from per-call options and environment variables. In the Python SDK the terminal template operations (build,build_in_background,get_build_status,exists,alias_exists,assign_tags,remove_tags,get_tags) becameclassmethods, with signatures unchanged for callers. - 05aa03c: Add typed not-found errors for volumes:
VolumeNotFoundError/VolumeNotFoundException(thrown when a volume is not found) andVolumePathNotFoundError/VolumePathNotFoundException(thrown when a path inside a volume is not found). All subclass the existingNotFoundError/NotFoundException, so existing catches keep working.
2.42.0
Minor Changes
7af41e9: Refresh the MCP server types from the current MCP gateway catalog: 49 servers are new (
n8n,neo4j,okta,temporal,proxmox,zscaler, the AWS Labs family, ...), 61 titles and 10 descriptions were rewritten, and 4 servers changed their options (awsDiagram,context7,neo4jCypher,onlyofficeDocspace).Six servers the catalog no longer publishes are gone from
McpServer:postgres,root,tembo,flexprice,triplewhale,cdataConnectcloud.awsDiagramandcontext7now require an option (outputDirandapiKey), soawsDiagram: {}andcontext7: {}stop type-checking, andonlyofficeDocspaceis down tobaseUrlanddocspaceApiKey. The removals also narrowMcpServerName, soTemplate().addMcpServer('postgres')stops compiling. The config is still passed to the gateway as written, so a dropped server can be kept by casting past the type — whether it starts is up to the gateway.import { Sandbox } from 'e2b' const sandbox = await Sandbox.create({ mcp: { n8n: { apiKey: process.env.N8N_API_KEY!, apiUrl: 'https://n8n.example.com/api/v1', }, }, })
Patch Changes
15bd48b: Omit
autoPausefrom the create-sandbox request when no timeout lifecycle is configured, and omitautoPauseMemoryunlesskeepMemory/keep_memorywas chosen. Sending the SDK's local defaults for those fields was indistinguishable from an explicit choice, so the API could not tell "no preference" from a client choice and own its defaults. Explicit values are still always sent:import { Sandbox } from 'e2b' // No timeout lifecycle: autoPause is omitted, the API applies its default. await Sandbox.create() // Explicit action: autoPause: false / autoPause: true, as before. await Sandbox.create({ lifecycle: { onTimeout: 'kill' } }) await Sandbox.create({ lifecycle: { onTimeout: 'pause' } }) // Snapshot kind is only sent when keepMemory is set. await Sandbox.create({ lifecycle: { onTimeout: { action: 'pause', keepMemory: false } }, })from e2b import Sandbox # No timeout lifecycle: auto_pause is omitted, the API applies its default. Sandbox.create() # Explicit action: autoPause: false / autoPause: true, as before. Sandbox.create(lifecycle={"on_timeout": "kill"}) Sandbox.create(lifecycle={"on_timeout": "pause"}) # Snapshot kind is only sent when keep_memory is set. Sandbox.create( lifecycle={"on_timeout": {"action": "pause", "keep_memory": False}} )5367693: Omit
autoResumefrom thePOST /sandboxesrequest whenlifecycle.autoResume/lifecycle["auto_resume"]is not configured, instead of sending the SDK's local default as{ "autoResume": { "enabled": false } }. The API can now tell an unset preference from an explicit opt-out and own the default itself. Explicit values are unchanged on the wire.import { Sandbox } from 'e2b' // autoResume is left out of the request entirely — the API's default applies await Sandbox.create({ lifecycle: { onTimeout: 'pause' } }) // an explicit choice is still sent as before await Sandbox.create({ lifecycle: { onTimeout: 'pause', autoResume: true } })from e2b import Sandbox # auto_resume is left out of the request entirely — the API's default applies Sandbox.create(lifecycle={"on_timeout": "pause"}) # an explicit choice is still sent as before Sandbox.create(lifecycle={"on_timeout": "pause", "auto_resume": True})666241d: Run every persistent HTTP stack in the SDK on one shared pyqwest connection pool instead of four: the control-plane REST API, the envd HTTP API, the envd RPC clients, and the volume content API now all draw from
e2b.api.client_sync/client_async, keyed on the three knobs that are fixed when a pyqwest transport is built — proxy, idle read bound, and HTTP version. reqwest pools per host internally, so one pool serves the API host and every per-sandbox host without interference — and since envd RPC and the envd HTTP API hit the same host, an active sandbox now needs a single HTTP/2 connection instead of one per stack. Streamed downloads keep a pool of their own, the only one carrying the idleread_timeout: reqwest's read timer runs during body send and TTFB, so on a shared pool it would cut off long uploads. No signature changes —get_transportandget_envd_transportkeep thehttp2parameter restored in 2.39.1, and the two are now the same pool per key rather than two.2daced6: Tag the package homepage and README links with UTM parameters (
utm_source=npm/pypi) so registry traffic to e2b.dev is attributed correctly. No functional change.
2.41.0
Minor Changes
6824cdf: Add
network.egressProxy/network["egress_proxy"]for routing a sandbox's outbound TCP through a SOCKS5 proxy you operate ("bring your own proxy"). Tunneling happens on the host after theallowOut/denyOutlists are evaluated, so nothing runs inside the sandbox and code running there can neither see the proxy nor route around it. UDP-based traffic — DNS and QUIC/HTTP3 — is not tunneled.import { Sandbox } from 'e2b' const sandbox = await Sandbox.create({ network: { egressProxy: { address: 'proxy.example.com:1080', username: 'proxy-user', password: 'proxy-password', }, }, })from e2b import Sandbox sandbox = Sandbox.create( network={ "egress_proxy": { "address": "proxy.example.com:1080", "username": "proxy-user", "password": "proxy-password", }, }, )It combines with the rest of the network configuration — here everything except
api.example.comis denied, and the traffic that is allowed goes through your proxy:await Sandbox.create({ network: { allowOut: ['api.example.com'], denyOut: ({ allTraffic }) => [allTraffic], egressProxy: { address: 'proxy.example.com:1080' }, }, })Sandbox.create( network={ "allow_out": ["api.example.com"], "deny_out": lambda ctx: [ctx.all_traffic], "egress_proxy": {"address": "proxy.example.com:1080"}, }, )updateNetwork/update_networksets or replaces the proxy on a sandbox that is already running, with no restart. The update replaces the whole configuration instead of merging into it, so an update that leaves the proxy out stops tunneling — repeat it in every update that should keep it.// Start tunneling on the running sandbox await sandbox.updateNetwork({ allowOut: ['api.example.com'], denyOut: ({ allTraffic }) => [allTraffic], egressProxy: { address: 'proxy.example.com:1080' }, }) // Stop tunneling: an update without egressProxy clears it await sandbox.updateNetwork({})# Start tunneling on the running sandbox sandbox.update_network({ "allow_out": ["api.example.com"], "deny_out": lambda ctx: [ctx.all_traffic], "egress_proxy": {"address": "proxy.example.com:1080"}, }) # Stop tunneling: an update without egress_proxy clears it sandbox.update_network({})getInfo/get_inforeports the proxy the sandbox's egress is currently tunneled through. The password is never returned, so the returnedSandboxEgressProxyInfodoes not have the field at all:const info = await sandbox.getInfo() console.log(info.network?.egressProxy) // { address: 'proxy.example.com:1080', username: 'proxy-user' }info = sandbox.get_info() print((info.network or {}).get("egress_proxy")) # {'address': 'proxy.example.com:1080', 'username': 'proxy-user'}Egress fails closed: when the proxy is unreachable or does not speak SOCKS5, outbound connections fail rather than falling back to a direct connection. The address is validated server-side when the sandbox is created — a rejected create leaves nothing behind. Available on E2B Cloud and in BYOC deployments; a sandbox that names a proxy on a deployment built from the open source
e2b-dev/infrarepository is rejected as unsupported.
Patch Changes
02ba746: Raise the
h2floor to>=4.4.1so it can no longer resolve to a version affected by CVE-2026-71554, where a duplicateHostheader is forwarded to the consuming application and becomes a request smuggling primitive once HTTP/2 is downgraded to HTTP/1.1.e2eebd5: Fix URL encoding of namespaced template names and aliases in the Python SDK.
The endpoints that take a template ID also accept a template name, and names may be namespaced (e.g.
namespace/name). The SDK interpolated them into the request path without encoding, so a call likeTemplate.exists("namespace/name")hit/templates/aliases/namespace/nameinstead of/templates/aliases/namespace%2Fname— the slash split the route rather than staying inside one path segment. Every method that takes a template ID or name, an alias, or a snapshot ID in the path —Template.exists/alias_exists,get_tags, the build/upload/status calls, andSandbox.delete_snapshot(whose snapshot IDs arenamespace/name:tag) — now percent-encodes the value, matching the JavaScript SDK (which already encodes path parameters viaencodeURIComponent).from e2b import Template, Sandbox # Namespaced templates now resolve correctly Template.exists("my-team/my-template") Template.get_tags("my-team/my-template") # Namespaced snapshots can now be deleted Sandbox.delete_snapshot("my-team/my-snapshot:default")
2.40.0
Minor Changes
6248b12: Remove the deprecated
accessToken/access_tokenoption and itsE2B_ACCESS_TOKENenvironment fallback. E2B access tokens are no longer accepted for API authentication, so the SDKs no longer resolve one or send it as anAuthorization: Bearerheader — requests authenticate with the API key alone.If you were relying on the option to send a bearer token to a custom deployment, pass the header directly, which is what the deprecation notice already pointed to:
// Before const sandbox = await Sandbox.create({ accessToken: token }) // After const sandbox = await Sandbox.create({ apiHeaders: { Authorization: `Bearer ${token}` }, })# Before config = ConnectionConfig(access_token=token) # After config = ConnectionConfig(api_headers={"Authorization": f"Bearer {token}"})Note that
Sandbox.envd_access_token/traffic_access_tokenare unrelated per-sandbox tokens and are unaffected.
2.39.1
Patch Changes
- 0d507cd: Restore the
http2parameter onget_transportandget_envd_transport, which the pyqwest migration dropped in 2.38.0.http2=Falseagain returns a transport pinned to HTTP/1.1, on its own connection pool.
2.39.0
Minor Changes
07eb9be: Allow a network rule's
transformto be a callback, so a workload identity token from theiamoption can be injected into egress requests without the SDK ever seeing its value. The callback receives placeholder strings that the egress proxy resolves per request —iam.tokens.awsis${e2b.identity.tokens.aws}on the wire — and referencing a token that is not registered iniam.tokensfails withInvalidArgumentError/InvalidArgumentExceptioninstead of silently sending a placeholder no token will ever replace.updateNetwork/update_networkaccepts the same callbacks, but its payload carries noiamconfig, so token names cannot be checked there and every name resolves to its placeholder.Token names are validated where they are registered and again before they are interpolated: a name cannot be empty or contain
{,}or control characters, since the proxy reads a placeholder up to its first}and a brace in the name would resolve a different token than the one referenced.import { Sandbox, Secret } from 'e2b' const sandbox = await Sandbox.create({ iam: { tokens: { aws: Secret.iamToken({ audience: 'sts.amazonaws.com', tokenType: 'JWT-SVID', }), }, }, network: { allowOut: ({ rules }) => [...rules.keys()], rules: { 'api.internal.example.com': [ { transform: ({ iam }) => ({ headers: { Authorization: `Bearer ${iam.tokens.aws}` }, }), }, ], }, }, })from e2b import Sandbox, Secret sandbox = Sandbox.create( iam={ "tokens": { "aws": Secret.iam_token(audience="sts.amazonaws.com", token_type="JWT-SVID"), }, }, network={ "allow_out": lambda ctx: list(ctx.rules.keys()), "rules": { "api.internal.example.com": [ { "transform": lambda ctx: { "headers": {"Authorization": f"Bearer {ctx.iam.tokens['aws']}"}, }, }, ], }, }, )64b25bb: Add the
iamoption toSandbox.createfor configuring sandbox workload identity, and aSecretclass with aniamToken/iam_tokenmethod for defining the workload tokens. Passing a non-emptytokensmap (name →{ audience, tokenType }) enables workload identity for the sandbox:import { Sandbox, Secret } from 'e2b' const sandbox = await Sandbox.create({ iam: { tokens: { aws: Secret.iamToken({ audience: 'sts.amazonaws.com', tokenType: 'JWT-SVID', }), }, }, })from e2b import Sandbox, Secret sandbox = Sandbox.create( iam={ "tokens": { "aws": Secret.iam_token(audience="sts.amazonaws.com", token_type="JWT-SVID"), }, }, )Plain
{ audience, tokenType }objects ({"audience": ..., "token_type": ...}dicts in Python) are accepted as token values too.
Patch Changes
- 11912ff: Build the envd HTTP API client once per sync
Sandboxand share it across the filesystem, commands, and PTY modules, which now receive it instead of each constructing their own — matchingAsyncSandbox. No behavior change: the pyqwest transport underneath is already cached process-wide per(proxy, for_streaming), so the separate clients shared one connection pool either way.Filesystemstill builds the streaming sibling client whose transport carries the idle read timeout, in both flavors.
2.38.0
Minor Changes
b048369: Move the envd HTTP API client (sandbox file transfers, health checks) onto
pyqwestvia its httpx-compatible transport adapter. envd RPC already runs on pyqwest throughconnectrpc, so all sandbox traffic now shares one HTTP stack built from the same transport pieces (with separate connection pools per use).The per-thread (sync) and per-loop (async) envd httpx clients are gone: the pyqwest transports are thread-safe and loop-independent, so a single client per module serves all threads and event loops.
Timeout semantics through the adapter:
- Streamed downloads (
files.read(format="stream")): arequest_timeoutset explicitly for the call is the deadline for the whole transfer — by default the transfer is unbounded in total, as before. A stalled stream is reclaimed by a 60-second idle read timeout that resets on every chunk.stream_idle_timeoutkeeps working on the async client (applied per read); the sync client cannot interrupt a blocking read, so it relies on the transport-wide idle bound and now ignores the parameter. - Uploads: a buffered upload is bounded by
request_timeoutas a whole-request deadline, and a streamed (file-like) upload carries no client-side timeout (a stalled one is bounded server-side by envd's idle read timeout) — both matching the JS SDK. - Non-streamed reads (
files.read()as text or bytes) and buffered uploads are bounded byrequest_timeoutfor the whole transfer (default 60 seconds), where the previous transport bounded each socket operation and left total duration unbounded. Reading or writing a file too large to transfer inside the deadline now raiseshttpx.ReadTimeout— pass a largerrequest_timeout(or0to disable), or useformat="stream"/file-like data, for large transfers.
E2B_MAX_CONNECTIONSis no longer read: it configured httpx's global connection cap, and the last transport that took one is gone (reqwest has no counterpart — it does not cap concurrent connections).E2B_KEEPALIVE_EXPIRYandE2B_MAX_KEEPALIVE_CONNECTIONSkeep tuning the pools.- Streamed downloads (
a874ced: Move the REST API client (sandbox lifecycle, listing, templates, volumes control plane) onto
pyqwest(Rust reqwest/hyper) via its httpx-compatible transport adapter, replacing the httpx-nativeHTTPTransport/AsyncHTTPTransport. The generated httpx client API is unchanged — only the transport underneath is swapped — so logging event hooks, headers, and redirect handling (follow_redirects,response.history) behave as before.One timeout semantics change: through the adapter,
request_timeoutis a deadline for the whole API call, where the previous transports applied it to each phase (connect, read, write) separately — a slow request could exceed it in total. For the REST API's small JSON exchanges this tightening is whatrequest_timeoutreads as promising;0still disables it.Because pyqwest transports are thread-safe and loop-independent (I/O runs on a Rust runtime), the API connection pool is now shared process-wide per proxy, instead of one pool per thread (sync) or per event loop (async), and
ApiClientno longer maintains per-thread/per-loop httpx client caches — a single httpx client serves all threads and event loops. Connection-establishment failures are retried with backoff (E2B_CONNECTION_RETRIES, default 3), matching the connect-only retries of the previous transports. Timeouts keep raisinghttpx.ReadTimeout(anhttpx.TimeoutException), as before, whether they fire while waiting for the response head or while reading the response body, and connection, network, and protocol failures keep raising theirhttpxcounterparts (httpx.ConnectError,httpx.ReadError,httpx.RemoteProtocolError).proxyfor API calls takes a URL string (e.g.proxy="http://user:pass@localhost:8030", scheme http, https, socks5, or socks5h), anhttpx.URL, or anhttpx.Proxy— including its credentials (sent asProxy-Authorization) and any headers configured for the proxy. The onehttpx.Proxyoption pyqwest cannot express, a per-proxyssl_context, raisesInvalidArgumentExceptionrather than being silently dropped.Low-level HTTP logs stay available: where enabling the
httpcorelogger used to show connection-level detail, pyqwest logs one line per request on thepyqwest.accesslogger and request lifecycle records onpyqwest, both atDEBUGand off unless enabled:import logging logging.basicConfig() logging.getLogger("pyqwest.access").setLevel(logging.DEBUG) # DEBUG pyqwest.access - HTTP Request: POST https://api.e2b.app/sandboxes "HTTP/2 201 Created"The SDK's own
loggeroption is unchanged and independent of these.envd traffic is not affected: RPC (commands, PTY, filesystem watch) already runs on pyqwest via
connectrpc, and the envd HTTP API (file transfers, health checks) keeps its httpx transports.b3a7c9f: Move template build-context uploads (to S3 presigned URLs) onto
pyqwestvia its httpx-compatible transport adapter. Content-Length framing for the streamed archive body is preserved (S3 rejects chunked transfer encoding), and redirects stay with the httpx client instead of being followed inside the transport. The 1-hour upload timeout now bounds the entire upload rather than each socket operation, andverify_ssl=Falseon the client is no longer honored for uploads (pyqwest has no insecure-TLS option).458c2c4: Move the volume content client (
Volume/AsyncVolumefile operations) ontopyqwestvia its httpx-compatible transport adapter, the same stack the REST API client uses. The connection pool is shared process-wide per proxy instead of one pool per thread (sync) or per event loop (async), and connection-establishment failures are retried with backoff (E2B_CONNECTION_RETRIES, default 3), as before.For streamed volume reads (
Volume.read_file(format="stream")), a stalled stream is by default bounded by a transport-wide idle read timeout of 60 seconds that resets on every chunk (still surfaced ashttpx.ReadTimeout; matches the JS SDK's default stream idle timeout).AsyncVolume.read_filekeeps honoring an explicitstream_idle_timeoutper read (including0to disable); the sync client ignores it — it cannot interrupt a blocking read. Passingrequest_timeoutto a streamed read now bounds the whole transfer rather than individual socket operations.The same whole-transfer semantics apply to non-streamed operations:
read_file(format="text"/"bytes")and uploads are bounded byrequest_timeoutas a total deadline (default 1 hour for file content operations), where the previous transports bounded each socket operation and left total duration unbounded. Pass a largerrequest_timeout(or0to disable) for very large transfers on slow links.
Patch Changes
- cab27aa: Kill newly created sandboxes when MCP gateway startup fails. The failure now surfaces as
SandboxError(JS) /SandboxException(Python) with aFailed to start MCP gateway: <stderr>message instead of a bare command exit error.
2.37.1
Patch Changes
- 88f41f3: Align ANSI stripping of template build log messages across both SDKs. The Python SDK's
strip_ansi_escape_codesnow ports the JS SDK'sstripAnsiregex: OSC sequences (hyperlinks, window titles) are matched non-greedily up to the first string terminator — including sequences spanning newlines — and CSI sequences are stripped without requiring a terminator. Both implementations additionally strip the remaining ECMA-48 string controls (DCS/Sixel, SOS, PM, APC) through their string terminator so control payloads no longer leak into cleaned logs. - 998e560: Relax the Python SDK's
wcmatchrequirement from>=10.1,<11to>=10.1,<12soe2bcan be installed alongside packages that already requirewcmatch>=11(for exampledeepagents>=0.7.0), which previously failed to resolve. The SDK only callsglob.glob()withGLOBSTAR | DOTMATCHfor template context matching; wcmatch 11.0's single breaking change affectstranslate()callers using extended-glob capture groups, so it is a no-op here. The template glob test suite passes against 10.1, 10.2.1 and 11.0.
2.37.0
Minor Changes
- 2821fb0: Route volume content requests to a team's custom (BYOC) cluster. When a team is connected to a custom cluster, the volume create and get endpoints now return that cluster's
domain, and the SDK uses it as the destination for volume content requests instead of the defaultapi.<E2B_DOMAIN>host. Teams on the default cluster are unaffected and keep their configured domain.
2.36.0
Minor Changes
- 1504fbc: Add
fromFedoraImage,fromAlpineImage, andfromArchImagebase-image helpers to theTemplatebuilder (from_fedora_image,from_alpine_image,from_arch_imagein the Python SDK), alongside the existingfromUbuntuImage/fromDebianImage/etc. Templates can now start from Fedora, Alpine, and Arch base images (the orchestrator identifies the distro from/etc/os-release). Fedora and Alpine default to pinned tags (fedora:44,alpine:3.24) so builds stay reproducible; Arch defaults tolatestbecause it is a rolling release and provisioning runspacman -Syuregardless.
Patch Changes
- 6733f36: Align the Python SDK's
from_fedora_imageandfrom_alpine_imagedefaults with the JS SDK:fedora:44andalpine:3.24, replacingfedora:42(end-of-life, so its repositories leave the normal mirror network and provisioning can fail) andalpine:3.22. Callers that omit the variant now get the same base image in both SDKs, and both tags are the ones the orchestrator's distro build tests cover. Also corrects the JSTemplateFromImagetype docs, which still named the old defaults. - 45d2679: Regenerate
e2b/sandbox/mcp.pywithdatamodel-code-generator0.64.0: the MCP server option types now use builtin generics (list[str],dict[str, Any]) and are closedTypedDicts, mirroring the spec'sadditionalProperties: false. Raises thetyping-extensionsfloor to>=4.10.0, the first release accepting PEP 728'sclosed. - ee0ad25: Update snapshot docstrings to use project terminology instead of team (e.g. "my-project/my-snapshot", project slug)