> ## Documentation Index > Fetch the complete documentation index at: https://docs.e2b.dev/llms.txt > Use this file to discover all available pages before exploring further. # Sandbox ### Sandbox #### Properties | Property | Modifier | Type | Default value | Description | Inherited from | | - | - | - | - | - | - | | `commands` | `readonly` | `Commands` | `undefined` | Module for running commands in the sandbox | `SandboxBase.commands` | | `display` | `public` | `string` | `':0'` | - | - | | `files` | `readonly` | `Filesystem` | `undefined` | Module for interacting with the sandbox filesystem | `SandboxBase.files` | | ~~`git`~~ | `readonly` | `Git` | `undefined` | Module for running git operations in the sandbox **Deprecated** Run git with `sandbox.commands.run()` instead. The git module will be removed in the next major version. | `SandboxBase.git` | | `pty` | `readonly` | `Pty` | `undefined` | Module for interacting with the sandbox pseudo-terminals | `SandboxBase.pty` | | `sandboxDomain` | `readonly` | `string` | `undefined` | Domain where the sandbox is hosted. | `SandboxBase.sandboxDomain` | | `sandboxId` | `readonly` | `string` | `undefined` | Unique identifier of the sandbox. | `SandboxBase.sandboxId` | | `stream` | `public` | `VNCServer` | `undefined` | - | - | | `trafficAccessToken?` | `readonly` | `string` | `undefined` | Traffic access token for accessing sandbox services with restricted public traffic. | `SandboxBase.trafficAccessToken` | #### Methods ### ~~betaPause()~~ ```ts theme={"theme":"css-variables"} betaPause(opts?: SandboxPauseOpts): Promise ``` ###### Parameters | Parameter | Type | | - | - | | `opts?` | `SandboxPauseOpts` | ###### Returns `Promise` ###### Deprecated Use Sandbox.pause instead. ### connect() ```ts theme={"theme":"css-variables"} connect(opts?: SandboxConnectOpts): Promise ``` Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. Sandbox must be either running or be paused. With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `SandboxConnectOpts` | connection options. | ###### Returns `Promise` A running sandbox instance ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create() await sandbox.betaPause() // Connect to the same sandbox. const sameSandbox = await sandbox.connect() ``` ### createSnapshot() ```ts theme={"theme":"css-variables"} createSnapshot(opts?: CreateSnapshotOpts): Promise ``` Create a snapshot of the sandbox's current state. The sandbox will be paused while the snapshot is being created. The snapshot can be used to create new sandboxes with the same filesystem and state. Snapshots are persistent and survive sandbox deletion. Use the returned `snapshotId` with `Sandbox.create(snapshotId)` to create a new sandbox from the snapshot. ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `CreateSnapshotOpts` | snapshot creation options including optional name, `mode` (`'filesystem'` takes a filesystem-only snapshot; sandboxes created from it cold-boot instead of restoring memory), and connection options. | ###### Returns `Promise` snapshot information including the snapshot ID. ###### Throws SandboxError with `statusCode` 400 when `mode: 'filesystem'` is requested but the feature is not enabled for the team (`snapshot_filesystem_only_disabled`), and with `statusCode` 409 when the sandbox's node runs an orchestrator that predates the option (`snapshot_filesystem_only_unsupported_node`). A full memory snapshot still works in both cases; for 409, pause and resume the sandbox and retry. ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create() await sandbox.files.write('/app/state.json', '{"step": 1}') // Create a snapshot const snapshot = await sandbox.createSnapshot({ name: 'my-snapshot' }) // Create a new sandbox from the snapshot const newSandbox = await Sandbox.create(snapshot.snapshotId) // Filesystem-only snapshot: sandboxes created from it start fresh from disk const fsSnapshot = await sandbox.createSnapshot({ mode: 'filesystem' }) ``` ### doubleClick() ```ts theme={"theme":"css-variables"} doubleClick(x?: number, y?: number): Promise ``` Double left click on the mouse position. ###### Parameters | Parameter | Type | | - | - | | `x?` | `number` | | `y?` | `number` | ###### Returns `Promise` ### downloadUrl() ```ts theme={"theme":"css-variables"} downloadUrl(path: string, opts?: SandboxUrlOpts): Promise ``` Get the URL to download a file from the sandbox. ###### Parameters | Parameter | Type | Description | | - | - | - | | `path` | `string` | path to the file in the sandbox. | | `opts?` | `SandboxUrlOpts` | download url options. | ###### Returns `Promise` URL for downloading file. ### drag() ```ts theme={"theme":"css-variables"} drag(from: [number, number], to: [number, number]): Promise ``` Drag the mouse from the given position to the given position. ###### Parameters | Parameter | Type | Description | | - | - | - | | `from` | \[`number`, `number`] | The starting position as `[x, y]`. | | `to` | \[`number`, `number`] | The ending position as `[x, y]`. | ###### Returns `Promise` ### fork() ```ts theme={"theme":"css-variables"} fork(opts?: SandboxForkOpts): Promise<(Sandbox | Error)[]> ``` Fork the sandbox. The sandbox is checkpointed in place (briefly paused, snapshotted with its full memory state, and resumed — its ID and expiration stay untouched) and `count` new sandboxes are created from that snapshot. All forks boot from the same snapshot, so the snapshot is captured once regardless of count. Each fork succeeds or fails independently — the returned array contains one entry per requested fork, either a running Sandbox instance or an `Error` describing why that fork failed to start (`Promise.allSettled`-style). Per-fork error codes map to the same error classes as other API errors (e.g. 429 to `RateLimitError`). ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `SandboxForkOpts` | fork options — `count`, `timeoutMs` and connection options. | ###### Returns `Promise<(Sandbox | Error)[]>` array with one entry per requested fork — a sandbox instance or an error. ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create() const [fork1, fork2] = await sandbox.fork({ count: 2 }) if (fork1 instanceof Sandbox) { await fork1.commands.run('echo "hello from fork"') } ``` ### getApplicationWindows() ```ts theme={"theme":"css-variables"} getApplicationWindows(application: string): Promise ``` Get the window ID of the window with the given title. ###### Parameters | Parameter | Type | | - | - | | `application` | `string` | ###### Returns `Promise` The ID of the window. ### getCurrentWindowId() ```ts theme={"theme":"css-variables"} getCurrentWindowId(): Promise ``` Get the current window ID. ###### Returns `Promise` The ID of the current window. ### getCursorPosition() ```ts theme={"theme":"css-variables"} getCursorPosition(): Promise ``` Get the current cursor position. ###### Returns `Promise` A object with the x and y coordinates ###### Throws Error if cursor position cannot be determined ### getHost() ```ts theme={"theme":"css-variables"} getHost(port: number): string ``` Get the host address for the specified sandbox port. You can then use this address to connect to the sandbox port from outside the sandbox via HTTP or WebSocket. ###### Parameters | Parameter | Type | Description | | - | - | - | | `port` | `number` | number of the port in the sandbox. | ###### Returns `string` host address of the sandbox port. ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create() // Start an HTTP server await sandbox.commands.run('python3 -m http.server 3000', { background: true }) // Get the hostname of the HTTP server const serverURL = sandbox.getHost(3000) ``` ### getInfo() ```ts theme={"theme":"css-variables"} getInfo(opts?: Pick): Promise ``` Get sandbox information like sandbox ID, template, metadata, started at/end at date. ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `Pick` | connection options. | ###### Returns `Promise` information about the sandbox ### getMcpToken() ```ts theme={"theme":"css-variables"} getMcpToken(): Promise ``` Get the MCP token for the sandbox. ###### Returns `Promise` MCP token for the sandbox, or undefined if MCP is not enabled. ### getMcpUrl() ```ts theme={"theme":"css-variables"} getMcpUrl(): string ``` Get the MCP URL for the sandbox. ###### Returns `string` MCP URL for the sandbox. ### getMetrics() ```ts theme={"theme":"css-variables"} getMetrics(opts?: SandboxMetricsOpts): Promise ``` Get the metrics of the sandbox. ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `SandboxMetricsOpts` | connection options. | ###### Returns `Promise` List of sandbox metrics containing CPU, memory and disk usage information. ### getScreenSize() ```ts theme={"theme":"css-variables"} getScreenSize(): Promise ``` Get the current screen size. ###### Returns `Promise` An ScreenSize object ###### Throws Error if screen size cannot be determined ### getWindowTitle() ```ts theme={"theme":"css-variables"} getWindowTitle(windowId: string): Promise ``` Get the title of the window with the given ID. ###### Parameters | Parameter | Type | Description | | - | - | - | | `windowId` | `string` | The ID of the window. | ###### Returns `Promise` The title of the window. ### isRunning() ```ts theme={"theme":"css-variables"} isRunning(opts?: Pick): Promise ``` Check if the sandbox is running. ###### Parameters | Parameter | Type | | - | - | | `opts?` | `Pick` | ###### Returns `Promise` `true` if the sandbox is running, `false` otherwise. ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create() await sandbox.isRunning() // Returns true await sandbox.kill() await sandbox.isRunning() // Returns false ``` ### kill() ```ts theme={"theme":"css-variables"} kill(opts?: Pick): Promise ``` Kill the sandbox. ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `Pick` | connection options. | ###### Returns `Promise` `true` if the sandbox was killed, `false` if the sandbox was not found. ### launch() ```ts theme={"theme":"css-variables"} launch(application: string, uri?: string): Promise ``` Launch an application. ###### Parameters | Parameter | Type | Description | | - | - | - | | `application` | `string` | The application to launch. | | `uri?` | `string` | The URI to open in the application. | ###### Returns `Promise` ### leftClick() ```ts theme={"theme":"css-variables"} leftClick(x?: number, y?: number): Promise ``` Left click on the mouse position. ###### Parameters | Parameter | Type | | - | - | | `x?` | `number` | | `y?` | `number` | ###### Returns `Promise` ### listSnapshots() ```ts theme={"theme":"css-variables"} listSnapshots(opts?: Omit): SnapshotPaginator ``` List all snapshots created from this sandbox. ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `Omit` | list options. | ###### Returns `SnapshotPaginator` paginator for listing snapshots from this sandbox. ### middleClick() ```ts theme={"theme":"css-variables"} middleClick(x?: number, y?: number): Promise ``` Middle click on the mouse position. ###### Parameters | Parameter | Type | | - | - | | `x?` | `number` | | `y?` | `number` | ###### Returns `Promise` ### mousePress() ```ts theme={"theme":"css-variables"} mousePress(button: "left" | "right" | "middle"): Promise ``` Press the mouse button. ###### Parameters | Parameter | Type | Default value | | - | - | - | | `button` | `"left" \| "right" \| "middle"` | `'left'` | ###### Returns `Promise` ### mouseRelease() ```ts theme={"theme":"css-variables"} mouseRelease(button: "left" | "right" | "middle"): Promise ``` Release the mouse button. ###### Parameters | Parameter | Type | Default value | | - | - | - | | `button` | `"left" \| "right" \| "middle"` | `'left'` | ###### Returns `Promise` ### moveMouse() ```ts theme={"theme":"css-variables"} moveMouse(x: number, y: number): Promise ``` Move the mouse to the given coordinates. ###### Parameters | Parameter | Type | Description | | - | - | - | | `x` | `number` | The x coordinate. | | `y` | `number` | The y coordinate. | ###### Returns `Promise` ### open() ```ts theme={"theme":"css-variables"} open(fileOrUrl: string): Promise ``` Open a file or a URL in the default application. ###### Parameters | Parameter | Type | Description | | - | - | - | | `fileOrUrl` | `string` | The file or URL to open. | ###### Returns `Promise` ### pause() ```ts theme={"theme":"css-variables"} pause(opts?: SandboxPauseOpts): Promise ``` Pause a sandbox by its ID. ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `SandboxPauseOpts` | connection options, plus `mode` to control the snapshot kind. With `mode: 'filesystem'`, the in-memory state is dropped and only the filesystem is persisted; resuming such a sandbox cold-boots (reboots) it from disk, losing running processes and open connections. Defaults to `'full'` (memory and filesystem). | ###### Returns `Promise` `true` if the sandbox got paused, `false` if the sandbox was already paused. ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create() await sandbox.pause() // filesystem-only snapshot (resume reboots the sandbox) await sandbox.pause({ mode: 'filesystem' }) ``` ### press() ```ts theme={"theme":"css-variables"} press(key: string | string[]): Promise ``` Press a key. ###### Parameters | Parameter | Type | Description | | - | - | - | | `key` | `string \| string[]` | The key to press (e.g. "enter", "space", "backspace", etc.). Can be a single key or an array of keys. | ###### Returns `Promise` ### rightClick() ```ts theme={"theme":"css-variables"} rightClick(x?: number, y?: number): Promise ``` Right click on the mouse position. ###### Parameters | Parameter | Type | | - | - | | `x?` | `number` | | `y?` | `number` | ###### Returns `Promise` ### screenshot() ###### Call Signature ```ts theme={"theme":"css-variables"} screenshot(): Promise> ``` Take a screenshot and save it to the given name. ###### Returns `Promise>` A Uint8Array bytes representation of the screenshot. ###### Call Signature ```ts theme={"theme":"css-variables"} screenshot(format: "bytes"): Promise> ``` Take a screenshot and save it to the given name. ###### Parameters | Parameter | Type | Description | | - | - | - | | `format` | `"bytes"` | The format of the screenshot. | ###### Returns `Promise>` A Uint8Array bytes representation of the screenshot. ###### Call Signature ```ts theme={"theme":"css-variables"} screenshot(format: "blob"): Promise ``` Take a screenshot and save it to the given name. ###### Parameters | Parameter | Type | | - | - | | `format` | `"blob"` | ###### Returns `Promise` A Blob representation of the screenshot. ###### Call Signature ```ts theme={"theme":"css-variables"} screenshot(format: "stream"): Promise>> ``` Take a screenshot and save it to the given name. ###### Parameters | Parameter | Type | | - | - | | `format` | `"stream"` | ###### Returns `Promise>>` A ReadableStream of bytes representation of the screenshot. ### scroll() ```ts theme={"theme":"css-variables"} scroll(direction: "down" | "up", amount: number): Promise ``` Scroll the mouse wheel by the given amount. ###### Parameters | Parameter | Type | Default value | Description | | - | - | - | - | | `direction` | `"down" \| "up"` | `'down'` | The direction to scroll. Can be "up" or "down". | | `amount` | `number` | `1` | The amount to scroll. | ###### Returns `Promise` ### setTimeout() ```ts theme={"theme":"css-variables"} setTimeout(timeoutMs: number, opts?: Pick): Promise ``` Set the timeout of the sandbox. This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to `.setTimeout`. Maximum time a sandbox can be kept alive is 24 hours (86\_400\_000 milliseconds) for Pro users and 1 hour (3\_600\_000 milliseconds) for Hobby users. ###### Parameters | Parameter | Type | Description | | - | - | - | | `timeoutMs` | `number` | timeout in **milliseconds**. | | `opts?` | `Pick` | connection options. | ###### Returns `Promise` ### updateNetwork() ```ts theme={"theme":"css-variables"} updateNetwork(network: SandboxNetworkUpdate, opts?: Pick): Promise ``` Update the network configuration of the sandbox. Replaces the current egress configuration atomically — fields that are omitted are cleared on the server. ###### Parameters | Parameter | Type | Description | | - | - | - | | `network` | `SandboxNetworkUpdate` | new network configuration. | | `opts?` | `Pick` | connection options. | ###### Returns `Promise` ### uploadUrl() ```ts theme={"theme":"css-variables"} uploadUrl(path?: string, opts?: SandboxUrlOpts): Promise ``` Get the URL to upload a file to the sandbox. You have to send a POST request to this URL with the file as multipart/form-data. ###### Parameters | Parameter | Type | Description | | - | - | - | | `path?` | `string` | path to the file in the sandbox. | | `opts?` | `SandboxUrlOpts` | upload url options. | ###### Returns `Promise` URL for uploading file. ### wait() ```ts theme={"theme":"css-variables"} wait(ms: number): Promise ``` Wait for the given amount of time. ###### Parameters | Parameter | Type | Description | | - | - | - | | `ms` | `number` | The amount of time to wait in milliseconds. | ###### Returns `Promise` ### waitAndVerify() ```ts theme={"theme":"css-variables"} waitAndVerify( cmd: string, onResult: (result: CommandResult) => boolean, timeout: number, interval: number): Promise ``` Wait for a command to return a specific result. ###### Parameters | Parameter | Type | Default value | Description | | - | - | - | - | | `cmd` | `string` | `undefined` | The command to run. | | `onResult` | `(result: CommandResult) => boolean` | `undefined` | The function to check the result of the command. | | `timeout` | `number` | `10` | The maximum time to wait for the command to return the result. | | `interval` | `number` | `0.5` | The interval to wait between checks. | ###### Returns `Promise` `true` if the command returned the result within the timeout, otherwise `false`. ### write() ```ts theme={"theme":"css-variables"} write(text: string, options: object): Promise ``` Write the given text at the current cursor position. ###### Parameters | Parameter | Type | Description | | - | - | - | | `text` | `string` | The text to write. | | `options` | \{ `chunkSize`: `number`; `delayInMs`: `number`; } | An object containing the chunk size and delay between each chunk of text. | | `options.chunkSize` | `number` | The size of each chunk of text to write. Default is 25 characters. | | `options.delayInMs` | `number` | The delay between each chunk of text. Default is 75 ms. | ###### Returns `Promise` ### ~~betaPause()~~ ```ts theme={"theme":"css-variables"} static betaPause(sandboxId: string, opts?: SandboxPauseOpts): Promise ``` ###### Parameters | Parameter | Type | | - | - | | `sandboxId` | `string` | | `opts?` | `SandboxPauseOpts` | ###### Returns `Promise` ###### Deprecated Use SandboxApi.pause instead. ### connect() ```ts theme={"theme":"css-variables"} static connect( this: S, sandboxId: string, opts?: SandboxConnectOpts): Promise> ``` Connect to a sandbox. If the sandbox is paused, it will be automatically resumed. Sandbox must be either running or be paused. With sandbox ID you can connect to the same sandbox from different places or environments (serverless functions, etc). ###### Type Parameters | Type Parameter | | - | | `S extends typeof Sandbox` | ###### Parameters | Parameter | Type | Description | | - | - | - | | `this` | `S` | - | | `sandboxId` | `string` | sandbox ID. | | `opts?` | `SandboxConnectOpts` | connection options. | ###### Returns `Promise>` A running sandbox instance ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create() const sandboxId = sandbox.sandboxId // Connect to the same sandbox. const sameSandbox = await Sandbox.connect(sandboxId) ``` ### create() ###### Call Signature ```ts theme={"theme":"css-variables"} static create(this: S, opts?: SandboxOpts): Promise> ``` Create a new sandbox from the default `desktop` sandbox template. ###### Type Parameters | Type Parameter | | - | | `S extends typeof Sandbox` | ###### Parameters | Parameter | Type | Description | | - | - | - | | `this` | `S` | - | | `opts?` | `SandboxOpts` | connection options. | ###### Returns `Promise>` sandbox instance for the new sandbox. ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create() ``` ###### Call Signature ```ts theme={"theme":"css-variables"} static create( this: S, template: string, opts?: SandboxOpts): Promise> ``` Create a new sandbox from the specified sandbox template. ###### Type Parameters | Type Parameter | | - | | `S extends typeof Sandbox` | ###### Parameters | Parameter | Type | Description | | - | - | - | | `this` | `S` | - | | `template` | `string` | sandbox template name or ID. | | `opts?` | `SandboxOpts` | connection options. | ###### Returns `Promise>` sandbox instance for the new sandbox. ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create('') ``` ### createSnapshot() ```ts theme={"theme":"css-variables"} static createSnapshot(sandboxId: string, opts?: CreateSnapshotOpts): Promise ``` Create a snapshot from a sandbox. The sandbox will be paused while the snapshot is being created. The snapshot can be used to create new sandboxes with the same state. The snapshot is a persistent image that survives sandbox deletion. ###### Parameters | Parameter | Type | Description | | - | - | - | | `sandboxId` | `string` | sandbox ID to create snapshot from. | | `opts?` | `CreateSnapshotOpts` | snapshot creation options including optional name, `mode` (`'filesystem'` takes a filesystem-only snapshot), and connection options. | ###### Returns `Promise` snapshot information including the snapshot name that can be used with Sandbox.create(). ###### Throws SandboxError with `statusCode` 400 when `mode: 'filesystem'` is requested but the feature is not enabled for the team (`snapshot_filesystem_only_disabled`), and with `statusCode` 409 when the sandbox's node runs an orchestrator that predates the option (`snapshot_filesystem_only_unsupported_node`). A full memory snapshot still works in both cases; for 409, pause and resume the sandbox and retry. ### deleteSnapshot() ```ts theme={"theme":"css-variables"} static deleteSnapshot(snapshotId: string, opts?: SandboxApiOpts): Promise ``` Delete a snapshot. ###### Parameters | Parameter | Type | Description | | - | - | - | | `snapshotId` | `string` | snapshot ID. | | `opts?` | `SandboxApiOpts` | connection options. | ###### Returns `Promise` `true` if the snapshot was deleted, `false` if it was not found. ### fork() ```ts theme={"theme":"css-variables"} static fork( this: S, sandboxId: string, opts?: SandboxForkOpts): Promise<(Error | InstanceType)[]> ``` Fork a running sandbox specified by sandbox ID. The sandbox is checkpointed in place (briefly paused, snapshotted with its full memory state, and resumed — its ID and expiration stay untouched) and `count` new sandboxes are created from that snapshot. All forks boot from the same snapshot, so the snapshot is captured once regardless of count. Each fork succeeds or fails independently — the returned array contains one entry per requested fork, either a running Sandbox instance or an `Error` describing why that fork failed to start (`Promise.allSettled`-style). Per-fork error codes map to the same error classes as other API errors (e.g. 429 to `RateLimitError`). ###### Type Parameters | Type Parameter | | - | | `S extends typeof Sandbox` | ###### Parameters | Parameter | Type | Description | | - | - | - | | `this` | `S` | - | | `sandboxId` | `string` | sandbox ID. | | `opts?` | `SandboxForkOpts` | fork options — `count`, `timeoutMs` and connection options. | ###### Returns `Promise<(Error | InstanceType)[]>` array with one entry per requested fork — a sandbox instance or an error. ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create() const [fork1, fork2] = await Sandbox.fork(sandbox.sandboxId, { count: 2 }) if (fork1 instanceof Sandbox) { await fork1.commands.run('echo "hello from fork"') } ``` ### ~~getFullInfo()~~ ```ts theme={"theme":"css-variables"} static getFullInfo(sandboxId: string, opts?: SandboxApiOpts): Promise ``` ###### Parameters | Parameter | Type | Description | | - | - | - | | `sandboxId` | `string` | sandbox ID. | | `opts?` | `SandboxApiOpts` | connection options. | ###### Returns `Promise` sandbox information. ###### Deprecated Use Sandbox.getInfo instead. ### getInfo() ```ts theme={"theme":"css-variables"} static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise ``` Get sandbox information like sandbox ID, template, metadata, started at/end at date. ###### Parameters | Parameter | Type | Description | | - | - | - | | `sandboxId` | `string` | sandbox ID. | | `opts?` | `SandboxApiOpts` | connection options. | ###### Returns `Promise` sandbox information. ### getMetrics() ```ts theme={"theme":"css-variables"} static getMetrics(sandboxId: string, opts?: SandboxMetricsOpts): Promise ``` Get the metrics of the sandbox. ###### Parameters | Parameter | Type | Description | | - | - | - | | `sandboxId` | `string` | sandbox ID. | | `opts?` | `SandboxMetricsOpts` | sandbox metrics options. | ###### Returns `Promise` List of sandbox metrics containing CPU, memory and disk usage information. ### kill() ```ts theme={"theme":"css-variables"} static kill(sandboxId: string, opts?: SandboxApiOpts): Promise ``` Kill the sandbox specified by sandbox ID. ###### Parameters | Parameter | Type | Description | | - | - | - | | `sandboxId` | `string` | sandbox ID. | | `opts?` | `SandboxApiOpts` | connection options. | ###### Returns `Promise` `true` if the sandbox was found and killed, `false` otherwise. ### list() ```ts theme={"theme":"css-variables"} static list(opts?: SandboxListOpts): SandboxPaginator ``` List sandboxes. By default (no `query.state` set in `opts`), returns sandboxes in both `running` and `paused` states. To filter by state, pass `opts.query.state = [...]`. ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `SandboxListOpts` | connection options, plus optional `query` to filter by metadata / state / start time / template, `order` to sort by start time across the whole result set (not within a page), and `limit` / `nextToken` for pagination. | ###### Returns `SandboxPaginator` a SandboxPaginator that yields pages of sandboxes (running and paused by default). Iterate pages via `await paginator.nextItems()` while `paginator.hasNext` is `true`. ### listSnapshots() ```ts theme={"theme":"css-variables"} static listSnapshots(opts?: SnapshotListOpts): SnapshotPaginator ``` List all snapshots. ###### Parameters | Parameter | Type | Description | | - | - | - | | `opts?` | `SnapshotListOpts` | list options including filters and pagination. | ###### Returns `SnapshotPaginator` paginator for listing snapshots. ### pause() ```ts theme={"theme":"css-variables"} static pause(sandboxId: string, opts?: SandboxPauseOpts): Promise ``` Pause the sandbox specified by sandbox ID. ###### Parameters | Parameter | Type | Description | | - | - | - | | `sandboxId` | `string` | sandbox ID. | | `opts?` | `SandboxPauseOpts` | pause options, including `mode` and connection options. | ###### Returns `Promise` `true` if the sandbox got paused, `false` if the sandbox was already paused. ### setTimeout() ```ts theme={"theme":"css-variables"} static setTimeout( sandboxId: string, timeoutMs: number, opts?: SandboxApiOpts): Promise ``` Set the timeout of the specified sandbox. After the timeout expires the sandbox will be automatically killed. This method can extend or reduce the sandbox timeout set when creating the sandbox or from the last call to Sandbox.setTimeout. Maximum time a sandbox can be kept alive is 24 hours (86\_400\_000 milliseconds) for Pro users and 1 hour (3\_600\_000 milliseconds) for Hobby users. ###### Parameters | Parameter | Type | Description | | - | - | - | | `sandboxId` | `string` | sandbox ID. | | `timeoutMs` | `number` | timeout in **milliseconds**. | | `opts?` | `SandboxApiOpts` | connection options. | ###### Returns `Promise` ### updateNetwork() ```ts theme={"theme":"css-variables"} static updateNetwork( sandboxId: string, network: SandboxNetworkUpdate, opts?: SandboxApiOpts): Promise ``` Update the network configuration of a running sandbox. Replaces the current egress configuration atomically — fields that are omitted are cleared on the server. ###### Parameters | Parameter | Type | Description | | - | - | - | | `sandboxId` | `string` | sandbox ID. | | `network` | `SandboxNetworkUpdate` | new network configuration. | | `opts?` | `SandboxApiOpts` | connection options. | ###### Returns `Promise` ## Interfaces ### SandboxOpts Configuration options for the Sandbox environment. SandboxOpts #### Properties ### allowInternetAccess? ```ts theme={"theme":"css-variables"} optional allowInternetAccess: boolean; ``` Allow sandbox to access the internet. If set to `False`, it works the same as setting network `denyOut` to `[0.0.0.0/0]`. ### apiHeaders? ```ts theme={"theme":"css-variables"} optional apiHeaders: Record; ``` Additional headers to send with E2B API requests. ### apiKey? ```ts theme={"theme":"css-variables"} optional apiKey: string; ``` E2B API key to use for authentication. ###### Default ```ts theme={"theme":"css-variables"} E2B_API_KEY // environment variable ``` ### display? ```ts theme={"theme":"css-variables"} optional display: string; ``` Display identifier. ### domain? ```ts theme={"theme":"css-variables"} optional domain: string; ``` Domain to use for the API. ###### Default E2B\_DOMAIN // environment variable or `e2b.app` ### dpi? ```ts theme={"theme":"css-variables"} optional dpi: number; ``` Dots per inch (DPI) setting for the display. ### envs? ```ts theme={"theme":"css-variables"} optional envs: Record; ``` Custom environment variables for the sandbox. Used when executing commands and code in the sandbox. Can be overridden with the `envs` argument when executing commands or code. ###### Default ```ts theme={"theme":"css-variables"} {} ``` ### ~~headers?~~ ```ts theme={"theme":"css-variables"} optional headers: Record; ``` Additional headers to send with the request. ###### Deprecated Use `apiHeaders` instead. ### httpVersion? ```ts theme={"theme":"css-variables"} optional httpVersion: HttpVersion; ``` HTTP version for requests to the E2B API and to sandboxes (commands, filesystem, PTY). `'2'` multiplexes streams over shared connections; `'1.1'` pins them to HTTP/1.1 with one connection per concurrent request — for example when an intermediary on the path retires or mishandles long-lived HTTP/2 connections. Only applies in Node. ###### Default E2B\_HTTP\_VERSION // environment variable or `'2'` ### iam? ```ts theme={"theme":"css-variables"} optional iam: SandboxIamOpts; ``` Sandbox workload identity configuration. Providing a non-empty `tokens` map enables workload identity for the sandbox. Registered tokens are exposed to SandboxNetworkOpts.rules `transform` callbacks as `iam.tokens.` placeholders, which the egress proxy resolves per request. ###### Example ```ts theme={"theme":"css-variables"} const sandbox = await Sandbox.create({ iam: { tokens: { aws: Secret.iamToken({ audience: 'sts.amazonaws.com', tokenType: 'JWT-SVID', }), }, }, }) ``` ### lifecycle? ```ts theme={"theme":"css-variables"} optional lifecycle: SandboxLifecycle; ``` Sandbox lifecycle configuration. ### logger? ```ts theme={"theme":"css-variables"} optional logger: Logger; ``` Logger to use for logging messages. It can accept any object that implements `Logger` interface—for example, console. ### mcp? ```ts theme={"theme":"css-variables"} optional mcp: McpServer$1; ``` MCP server to enable in the sandbox ###### Default ```ts theme={"theme":"css-variables"} undefined ``` ### metadata? ```ts theme={"theme":"css-variables"} optional metadata: Record; ``` Custom metadata for the sandbox. ###### Default ```ts theme={"theme":"css-variables"} {} ``` ### network? ```ts theme={"theme":"css-variables"} optional network: SandboxNetworkOpts; ``` Sandbox network configuration ### proxy? ```ts theme={"theme":"css-variables"} optional proxy: string; ``` Proxy URL to use for requests. In case of a sandbox it applies to all requests made to the returned sandbox. ###### Example ```ts theme={"theme":"css-variables"} 'http://user:pass@127.0.0.1:8080' ``` ### requestTimeoutMs? ```ts theme={"theme":"css-variables"} optional requestTimeoutMs: number; ``` Timeout for requests to the API in **milliseconds**. ###### Default ```ts theme={"theme":"css-variables"} 60_000 // 60 seconds ``` ### resolution? ```ts theme={"theme":"css-variables"} optional resolution: [number, number]; ``` The screen resolution in pixels, specified as \[width, height]. ### retries? ```ts theme={"theme":"css-variables"} optional retries: number; ``` Number of control-plane API retries after a 429, 502 or 503 response or a failure to establish the connection (refused, DNS, unreachable host). Any other network error (dropped connection, opaque browser/Workers `TypeError`) is retried too. A 502 and those network errors are not retried for operations that create a resource (e.g. sandbox creation) or append to one (secret update), as the server may already have processed them. A 429 is retried only with a valid, non-negative integer delta-seconds `Retry-After` header (HTTP-date and malformed values are not retried). 502 and 503 honor such a `Retry-After` when present; otherwise they and connection failures use exponential backoff with jitter starting at 100 ms (capped at 10 s). Retry waits use a 60-second total limit when request timeouts are disabled. ###### Default ```ts theme={"theme":"css-variables"} 3 ``` ### sandboxUrl? ```ts theme={"theme":"css-variables"} optional sandboxUrl: string; ``` Sandbox URL. Used for local development ### ~~secure?~~ ```ts theme={"theme":"css-variables"} optional secure: boolean; ``` ###### Deprecated Every sandbox secures envd access; this option is accepted for backward compatibility and ignored. ### signal? ```ts theme={"theme":"css-variables"} optional signal: AbortSignal; ``` An optional `AbortSignal` that can be used to cancel the in-flight request. When the signal is aborted, the underlying `fetch` is aborted and the returned promise rejects with an `AbortError`. ### template? ```ts theme={"theme":"css-variables"} optional template: string; ``` Sandbox template name or ID. ###### Default 'base' (or 'mcp-gateway' when `mcp` option is set) ### timeoutMs? ```ts theme={"theme":"css-variables"} optional timeoutMs: number; ``` Timeout for the sandbox in **milliseconds**. Maximum time a sandbox can be kept alive is 24 hours (86\_400\_000 milliseconds) for Pro users and 1 hour (3\_600\_000 milliseconds) for Hobby users. ### ~~validateApiKey?~~ ```ts theme={"theme":"css-variables"} optional validateApiKey: boolean; ``` Whether to validate the format of the E2B API key on the client side. ###### Deprecated The API key format is no longer validated on the client side; this option has no effect. ### volumeMounts? ```ts theme={"theme":"css-variables"} optional volumeMounts: Record; ``` Volume mounts for the sandbox. The keys are mount paths inside the sandbox and the values are either a `Volume` instance or a string representing the volume name. ###### Default ```ts theme={"theme":"css-variables"} undefined ```