Skip to main content

​
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

PropertyModifierTypeDescription
commandsreadonlyCommandsModule for running commands in the sandbox
filesreadonlyFilesystemModule for interacting with the sandbox filesystem
ptyreadonlyPtyModule for interacting with the sandbox pseudo-terminals
sandboxIdreadonlystringUnique identifier of the sandbox.

​
Methods

​
downloadUrl()

downloadUrl(path: string): string
Get the URL to download a file from the sandbox.
Parameters
ParameterTypeDescription
pathstringpath to the file to download.
Returns
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
ParameterTypeDescription
portnumbernumber 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)

​
isRunning()

isRunning(opts?: Pick<ConnectionOpts, "requestTimeoutMs">): Promise<boolean>
Check if the sandbox is running.
Parameters
ParameterType
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
ParameterTypeDescription
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
ParameterTypeDescription
timeoutMsnumbertimeout in milliseconds.
opts?Pick<SandboxOpts, "requestTimeoutMs">connection options.
Returns
Promise<void>

​
uploadUrl()

uploadUrl(path?: string): 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
ParameterTypeDescription
path?stringthe directory where to upload the file, defaults to user’s home directory.
Returns
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
ParameterTypeDescription
thisS-
sandboxIdstringsandbox 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
ParameterTypeDescription
thisS-
opts?SandboxOptsconnection 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
ParameterTypeDescription
thisS-
templatestringsandbox template name or ID.
opts?SandboxOptsconnection options.
Returns
Promise<InstanceType<S>> sandbox instance for the new sandbox.
Example
const sandbox = await Sandbox.create('<template-name-or-id>')
Constructs
Sandbox

​
kill()

static kill(sandboxId: string, opts?: SandboxApiOpts): Promise<boolean>
Kill the sandbox specified by sandbox ID.
Parameters
ParameterTypeDescription
sandboxIdstringsandbox ID.
opts?SandboxApiOptsconnection options.
Returns
Promise<boolean> true if the sandbox was found and killed, false otherwise.

​
list()

static list(opts?: SandboxApiOpts): Promise<SandboxInfo[]>
List all running sandboxes.
Parameters
ParameterTypeDescription
opts?SandboxApiOptsconnection options.
Returns
Promise<SandboxInfo[]> 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
ParameterTypeDescription
sandboxIdstringsandbox ID.
timeoutMsnumbertimeout in milliseconds.
opts?SandboxApiOptsconnection 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.dev

​
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
{}

​
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

​
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
⌘I