Documentation

Sandbox

E2B cloud sandbox is a secure and isolated cloud environment. The sandbox allows you to:

Access Linux OS
Create, list, and delete files and directories
Run commands
Run git operations
Run isolated code
Access the internet

Check docs here. Use Sandbox.create to create a new sandbox.

Example

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create()

Properties

Property	Modifier	Type	Description
`commands`	`readonly`	`Commands`	Module for running commands in the sandbox
`files`	`readonly`	`Filesystem`	Module for interacting with the sandbox filesystem
`git`	`readonly`	`Git`	Module for running git operations in the sandbox
`pty`	`readonly`	`Pty`	Module for interacting with the sandbox pseudo-terminals
`sandboxDomain`	`readonly`	`string`	Domain where the sandbox is hosted.
`sandboxId`	`readonly`	`string`	Unique identifier of the sandbox.
`trafficAccessToken?`	`readonly`	`string`	Traffic access token for accessing sandbox services with restricted public traffic.

Methods

betaPause()

betaPause(opts?: SandboxPauseOpts): Promise<boolean>

Parameters

Parameter	Type
`opts`?	`SandboxPauseOpts`

Returns

Promise<boolean>

Deprecated

Use Sandbox.pause instead.

connect()

connect(opts?: SandboxConnectOpts): Promise<Sandbox>

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<Sandbox> A running sandbox instance

Example

const sandbox = await Sandbox.create()
await sandbox.betaPause()

// Connect to the same sandbox.
const sameSandbox = await sandbox.connect()

createSnapshot()

createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>

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 and connection options.

Returns

Promise<SnapshotInfo> snapshot information including the snapshot ID.

Example

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)

downloadUrl()

downloadUrl(path: string, opts?: SandboxUrlOpts): Promise<string>

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<string> URL for downloading file.

getHost()

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

const sandbox = await Sandbox.create()
// Start an HTTP server
await sandbox.commands.exec('python3 -m http.server 3000')
// Get the hostname of the HTTP server
const serverURL = sandbox.getHost(3000)

getInfo()

getInfo(opts?: Pick<SandboxOpts, "signal" | "requestTimeoutMs">): Promise<SandboxInfo>

Get sandbox information like sandbox ID, template, metadata, started at/end at date.

Parameters

Parameter	Type	Description
`opts`?	`Pick`<`SandboxOpts`, `"signal"` \| `"requestTimeoutMs"`>	connection options.

Returns

Promise<SandboxInfo> information about the sandbox

getMcpToken()

getMcpToken(): Promise<undefined | string>

Get the MCP token for the sandbox.

Returns

Promise<undefined | string> MCP token for the sandbox, or undefined if MCP is not enabled.

getMcpUrl()

getMcpUrl(): string

Get the MCP URL for the sandbox.

Returns

string MCP URL for the sandbox.

getMetrics()

getMetrics(opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>

Get the metrics of the sandbox.

Parameters

Parameter	Type	Description
`opts`?	`SandboxMetricsOpts`	connection options.

Returns

Promise<SandboxMetrics[]> List of sandbox metrics containing CPU, memory and disk usage information.

isRunning()

isRunning(opts?: Pick<ConnectionOpts, "signal" | "requestTimeoutMs">): Promise<boolean>

Check if the sandbox is running.

Parameters

Parameter	Type
`opts`?	`Pick`<`ConnectionOpts`, `"signal"` \| `"requestTimeoutMs"`>

Returns

Promise<boolean> true if the sandbox is running, false otherwise.

Example

const sandbox = await Sandbox.create()
await sandbox.isRunning() // Returns true

await sandbox.kill()
await sandbox.isRunning() // Returns false

kill()

kill(opts?: Pick<SandboxOpts, "signal" | "requestTimeoutMs">): Promise<boolean>

Kill the sandbox.

Parameters

Parameter	Type	Description
`opts`?	`Pick`<`SandboxOpts`, `"signal"` \| `"requestTimeoutMs"`>	connection options.

Returns

Promise<boolean> true if the sandbox was killed, false if the sandbox was not found.

listSnapshots()

listSnapshots(opts?: Omit<SnapshotListOpts, "sandboxId">): SnapshotPaginator

List all snapshots created from this sandbox.

Parameters

Parameter	Type	Description
`opts`?	`Omit`<`SnapshotListOpts`, `"sandboxId"`>	list options.

Returns

SnapshotPaginator paginator for listing snapshots from this sandbox.

pause()

pause(opts?: SandboxPauseOpts): Promise<boolean>

Pause a sandbox by its ID.

Parameters

Parameter	Type	Description
`opts`?	`SandboxPauseOpts`	connection options, plus `keepMemory` to control the snapshot kind. When `opts.keepMemory` is `false`, the in-memory state is dropped and only the filesystem is persisted (a filesystem-only snapshot); resuming such a sandbox cold-boots (reboots) it from disk, losing running processes and open connections. Defaults to `true` (full memory snapshot).

Returns

Promise<boolean> true if the sandbox got paused, false if the sandbox was already paused.

Example

const sandbox = await Sandbox.create()
await sandbox.pause()

// filesystem-only snapshot (resume reboots the sandbox)
await sandbox.pause({ keepMemory: false })

setTimeout()

setTimeout(timeoutMs: number, opts?: Pick<SandboxOpts, "signal" | "requestTimeoutMs">): Promise<void>

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`<`SandboxOpts`, `"signal"` \| `"requestTimeoutMs"`>	connection options.

Returns

Promise<void>

updateNetwork()

updateNetwork(network: SandboxNetworkUpdate, opts?: Pick<SandboxOpts, "signal" | "requestTimeoutMs">): Promise<void>

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`<`SandboxOpts`, `"signal"` \| `"requestTimeoutMs"`>	connection options.

Returns

Promise<void>

uploadUrl()

uploadUrl(path?: string, opts?: SandboxUrlOpts): Promise<string>

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`	download url options.

Returns

Promise<string> URL for uploading file.

betaPause()

static betaPause(sandboxId: string, opts?: SandboxPauseOpts): Promise<boolean>

Parameters

Parameter	Type
`sandboxId`	`string`
`opts`?	`SandboxPauseOpts`

Returns

Promise<boolean>

Deprecated

Use SandboxApi.pause instead.

connect()

static connect<S>(
   this: S, 
   sandboxId: string, 
opts?: SandboxConnectOpts): Promise<InstanceType<S>>

Type Parameters

Type Parameter
`S` extends typeof `Sandbox`

Parameters

Parameter	Type	Description
`this`	`S`	-
`sandboxId`	`string`	sandbox ID.
`opts`?	`SandboxConnectOpts`	connection options.

Returns

Promise<InstanceType<S>> A running sandbox instance

Example

const sandbox = await Sandbox.create()
const sandboxId = sandbox.sandboxId

// Connect to the same sandbox.
const sameSandbox = await Sandbox.connect(sandboxId)

create()

Call Signature

static create<S>(this: S, opts?: SandboxOpts): Promise<InstanceType<S>>

Create a new sandbox from the default base sandbox template.

Type Parameters

Type Parameter
`S` extends typeof `Sandbox`

Parameters

Parameter	Type	Description
`this`	`S`	-
`opts`?	`SandboxOpts`	connection options.

Returns

Promise<InstanceType<S>> sandbox instance for the new sandbox.

Example

const sandbox = await Sandbox.create()

Constructs

Sandbox

Call Signature

static create<S>(
   this: S, 
   template: string, 
opts?: SandboxOpts): Promise<InstanceType<S>>

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<InstanceType<S>> sandbox instance for the new sandbox.

Example

const sandbox = await Sandbox.create('<template-name-or-id>')

Constructs

Sandbox

createSnapshot()

static createSnapshot(sandboxId: string, opts?: CreateSnapshotOpts): Promise<SnapshotInfo>

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 and connection options.

Returns

Promise<SnapshotInfo> snapshot information including the snapshot name that can be used with Sandbox.create().

deleteSnapshot()

static deleteSnapshot(snapshotId: string, opts?: SandboxApiOpts): Promise<boolean>

Delete a snapshot.

Parameters

Parameter	Type	Description
`snapshotId`	`string`	snapshot ID.
`opts`?	`SandboxApiOpts`	connection options.

Returns

Promise<boolean> true if the snapshot was deleted, false if it was not found.

getFullInfo()

static getFullInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>

Parameters

Parameter	Type	Description
`sandboxId`	`string`	sandbox ID.
`opts`?	`SandboxApiOpts`	connection options.

Returns

Promise<SandboxInfo> sandbox information.

Deprecated

Use Sandbox.getInfo instead.

getInfo()

static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>

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<SandboxInfo> sandbox information.

getMetrics()

static getMetrics(sandboxId: string, opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>

Get the metrics of the sandbox.

Parameters

Parameter	Type	Description
`sandboxId`	`string`	sandbox ID.
`opts`?	`SandboxMetricsOpts`	sandbox metrics options.

Returns

Promise<SandboxMetrics[]> List of sandbox metrics containing CPU, memory and disk usage information.

kill()

static kill(sandboxId: string, opts?: SandboxApiOpts): Promise<boolean>

Kill the sandbox specified by sandbox ID.

Parameters

Parameter	Type	Description
`sandboxId`	`string`	sandbox ID.
`opts`?	`SandboxApiOpts`	connection options.

Returns

Promise<boolean> true if the sandbox was found and killed, false otherwise.

list()

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 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()

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()

static pause(sandboxId: string, opts?: SandboxPauseOpts): Promise<boolean>

Pause the sandbox specified by sandbox ID.

Parameters

Parameter	Type	Description
`sandboxId`	`string`	sandbox ID.
`opts`?	`SandboxPauseOpts`	pause options, including `keepMemory` and connection options.

Returns

Promise<boolean> true if the sandbox got paused, false if the sandbox was already paused.

setTimeout()

static setTimeout(
   sandboxId: string, 
   timeoutMs: number, 
opts?: SandboxApiOpts): Promise<void>

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<void>

updateNetwork()

static updateNetwork(
   sandboxId: string, 
   network: SandboxNetworkUpdate, 
opts?: SandboxApiOpts): Promise<void>

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<void>

Interfaces

SandboxUrlOpts

Options for sandbox upload/download URL generation.

Properties

user?

optional user: string;

User that will be used to access the file.

useSignatureExpiration?

optional useSignatureExpiration: number;

Use signature expiration for the URL. Optional parameter to set the expiration time for the signature in seconds.

​Sandbox

​Example

​Properties

​Methods

​betaPause()

Parameters

Returns

Deprecated

​connect()

Parameters

Returns

Example

​createSnapshot()

Parameters

Returns

Example

​downloadUrl()

Parameters

Returns

​getHost()

Parameters

Returns

Example

​getInfo()

Parameters

Returns

​getMcpToken()

Returns

​getMcpUrl()

Returns

​getMetrics()

Parameters

Returns

​isRunning()

Parameters

Returns

Example

​kill()

Parameters

Returns

​listSnapshots()

Parameters

Returns

​pause()

Parameters

Returns

Example

​setTimeout()

Parameters

Returns

​updateNetwork()

Parameters

Returns

​uploadUrl()

Parameters

Returns

​betaPause()

Parameters

Returns

Deprecated

​connect()

Type Parameters

Parameters

Returns

Example

​create()

Call Signature

Type Parameters

Parameters

Returns

Example

Constructs

Call Signature

Type Parameters

Parameters

Returns

Example

Constructs

​createSnapshot()

Parameters

Sandbox

Example

Properties

Methods

betaPause()

connect()

createSnapshot()

downloadUrl()

getHost()

getInfo()

getMcpToken()

getMcpUrl()

getMetrics()

isRunning()

kill()

listSnapshots()

pause()

setTimeout()

updateNetwork()

uploadUrl()

betaPause()

connect()

create()

createSnapshot()

deleteSnapshot()

getFullInfo()

getInfo()

getMetrics()

kill()

list()

listSnapshots()

pause()

setTimeout()

updateNetwork()

Interfaces

SandboxUrlOpts

Properties

user?

useSignatureExpiration?