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 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
`pty`	`readonly`	`Pty`	Module for interacting with the sandbox pseudo-terminals
`sandboxId`	`readonly`	`string`	Unique identifier of the sandbox.

Methods

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, "requestTimeoutMs">): Promise<SandboxInfo>

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

Parameters

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

Returns

Promise<SandboxInfo> information about the sandbox

isRunning()

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

Check if the sandbox is running.

Parameters

Parameter	Type
`opts`?	`Pick`<`ConnectionOpts`, `"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, "requestTimeoutMs">): Promise<void>

Kill the sandbox.

Parameters

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

Returns

Promise<void>

setTimeout()

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

Set the timeout of the 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 .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`, `"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.

connect()

static connect<S>(
   this: S, 
   sandboxId: string, 
opts?: Omit<SandboxOpts, "timeoutMs" | "metadata" | "envs">): Promise<InstanceType<S>>

Connect to an existing sandbox. 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`?	`Omit`<`SandboxOpts`, `"timeoutMs"` \| `"metadata"` \| `"envs"`>	connection options.

Returns

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

Example

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

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

create()

create(this, opts)

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

create(this, template, opts)

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

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.

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): Promise<ListedSandbox[]>

List all running sandboxes.

Parameters

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

Returns

Promise<ListedSandbox[]> list of running sandboxes.

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>

Interfaces

SandboxOpts

Options for creating a new Sandbox.

Properties

accessToken?

optional accessToken: string;

E2B access token to use for authentication.

Default

E2B_ACCESS_TOKEN // environment variable

apiKey?

optional apiKey: string;

E2B API key to use for authentication.

Default

E2B_API_KEY // environment variable

debug?

optional debug: boolean;

Internal If true the SDK starts in the debug mode and connects to the local envd API server.

Default

E2B_DEBUG // environment variable or false

domain?

optional domain: string;

Domain to use for the API.

Default

E2B_DOMAIN // environment variable or e2b.app

envs?

optional envs: Record<string, string>;

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

{}

headers?

optional headers: Record<string, string>;

Additional headers to send with the request.

logger?

optional logger: Logger;

Logger to use for logging messages. It can accept any object that implements Logger interface—for example, console.

metadata?

optional metadata: Record<string, string>;

Custom metadata for the sandbox.

Default

{}

requestTimeoutMs?

optional requestTimeoutMs: number;

Timeout for requests to the API in milliseconds.

Default

30_000 // 30 seconds

secure?

optional secure: boolean;

Secure all traffic coming to the sandbox controller with auth token

Default

false

timeoutMs?

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.

Default

300_000 // 5 minutes

SandboxUrlOpts

Options for sandbox upload/download URL generation.

Properties

user?

optional user: Username;

User that will be used to access the file.

useSignature?

optional useSignature: true;

Use signature for the URL. This needs to be used in case of using secured envd in sandbox.

Default

false

useSignatureExpiration?

optional useSignatureExpiration: number;

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

​Sandbox

​Example

​Properties

​Methods

​downloadUrl()

Parameters

Returns

​getHost()

Parameters

Returns

Example

​getInfo()

Parameters

Returns

​isRunning()

Parameters

Returns

Example

​kill()

Parameters

Returns

​setTimeout()

Parameters

Returns

​uploadUrl()

Parameters

Returns

​connect()

Type Parameters

Parameters

Returns

Example

​create()

create(this, opts)

Type Parameters

Parameters

Returns

Example

Constructs

create(this, template, opts)

Type Parameters

Parameters

Returns

Example

Constructs

​getInfo()

Parameters

Returns

​kill()

Parameters

Returns

​list()

Parameters

Returns

​setTimeout()

Parameters

Returns

​Interfaces

​SandboxOpts

​Properties

​accessToken?

Default

​apiKey?

Default

​debug?

Default

​domain?

Default

​envs?

Default

​headers?

​logger?

​metadata?

Default

​requestTimeoutMs?

Default

​secure?

Default

​timeoutMs?

Default

Sandbox

Example

Properties

Methods

downloadUrl()

getHost()

getInfo()

isRunning()

kill()

setTimeout()

uploadUrl()

connect()

create()

getInfo()

kill()

list()

setTimeout()

Interfaces

SandboxOpts

Properties

accessToken?

apiKey?

debug?

domain?

envs?

headers?

logger?

metadata?

requestTimeoutMs?

secure?

timeoutMs?

SandboxUrlOpts

Properties

user?

useSignature?

useSignatureExpiration?