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
sandboxDomainreadonlystringDomain where the sandbox is hosted.
sandboxIdreadonlystringUnique identifier of the sandbox.

​
Methods

​
betaGetMcpToken()

betaGetMcpToken(): Promise<undefined | string>
Beta This feature is in beta and may change in the future. Get the MCP token for the sandbox.
Returns
Promise<undefined | string> MCP token for the sandbox, or undefined if MCP is not enabled.

​
betaGetMcpUrl()

betaGetMcpUrl(): string
Beta This feature is in beta and may change in the future. Get the MCP URL for the sandbox.
Returns
string MCP URL for the sandbox.

​
betaPause()

betaPause(opts?: ConnectionOpts): Promise<boolean>
Beta This feature is in beta and may change in the future. Pause a sandbox by its ID.
Parameters
ParameterTypeDescription
opts?ConnectionOptsconnection options.
Returns
Promise<boolean> sandbox ID that can be used to resume the sandbox.

​
connect()

connect(opts?: SandboxBetaCreateOpts): 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
ParameterTypeDescription
opts?SandboxBetaCreateOptsconnection 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()

​
downloadUrl()

downloadUrl(path: string, opts?: SandboxUrlOpts): Promise<string>
Get the URL to download a file from the sandbox.
Parameters
ParameterTypeDescription
pathstringpath to the file in the sandbox.
opts?SandboxUrlOptsdownload 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
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)

​
getInfo()

getInfo(opts?: Pick<SandboxOpts, "requestTimeoutMs">): Promise<SandboxInfo>
Get sandbox information like sandbox ID, template, metadata, started at/end at date.
Parameters
ParameterTypeDescription
opts?Pick<SandboxOpts, "requestTimeoutMs">connection options.
Returns
Promise<SandboxInfo> information about the sandbox

​
getMetrics()

getMetrics(opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>
Get the metrics of the sandbox.
Parameters
ParameterTypeDescription
opts?SandboxMetricsOptsconnection options.
Returns
Promise<SandboxMetrics[]> List of sandbox metrics containing CPU, memory and disk usage information.

​
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, 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
ParameterTypeDescription
path?stringpath to the file in the sandbox.
opts?SandboxUrlOptsdownload url options.
Returns
Promise<string> URL for uploading file.

​
betaCreate()

betaCreate(this, opts)
static betaCreate<S>(this: S, opts?: SandboxBetaCreateOpts): Promise<InstanceType<S>>
Beta This feature is in beta and may change in the future. Create a new sandbox from the default base sandbox template.
Type Parameters
Type Parameter
S extends typeof Sandbox
Parameters
ParameterTypeDescription
thisS-
opts?SandboxBetaCreateOptsconnection options.
Returns
Promise<InstanceType<S>> sandbox instance for the new sandbox.
Example
const sandbox = await Sandbox.betaCreate()
Constructs
Sandbox
betaCreate(this, template, opts)
static betaCreate<S>(
   this: S, 
   template: string, 
opts?: SandboxBetaCreateOpts): Promise<InstanceType<S>>
Beta This feature is in beta and may change in the future. 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?SandboxBetaCreateOptsconnection options.
Returns
Promise<InstanceType<S>> sandbox instance for the new sandbox.
Example
const sandbox = await Sandbox.betaCreate('<template-name-or-id>')
Constructs
Sandbox

​
betaPause()

static betaPause(sandboxId: string, opts?: SandboxApiOpts): Promise<boolean>
Pause the sandbox specified by sandbox ID.
Parameters
ParameterTypeDescription
sandboxIdstringsandbox ID.
opts?SandboxApiOptsconnection options.
Returns
Promise<boolean> true if the sandbox got paused, false if the sandbox was already paused.

​
connect()

static connect<S>(
   this: S, 
   sandboxId: string, 
opts?: SandboxConnectOpts): Promise<InstanceType<S>>
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
ParameterTypeDescription
thisS-
sandboxIdstringsandbox ID.
opts?SandboxConnectOptsconnection 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()

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

​
getFullInfo()

static getFullInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<object>
Parameters
ParameterType
sandboxIdstring
opts?SandboxApiOpts
Returns
Promise<object>
NameTypeDefault value
cpuCountnumberres.data.cpuCount
endAtDate-
envdAccessTokenundefined | stringres.data.envdAccessToken
envdVersionstringres.data.envdVersion
memoryMBnumberres.data.memoryMB
metadataobject-
name?stringres.data.alias
sandboxDomainundefined | string-
sandboxIdstringres.data.sandboxID
startedAtDate-
state"running" | "paused"res.data.state
templateIdstringres.data.templateID

​
getInfo()

static getInfo(sandboxId: string, opts?: SandboxApiOpts): Promise<SandboxInfo>
Get sandbox information like sandbox ID, template, metadata, started at/end at date.
Parameters
ParameterTypeDescription
sandboxIdstringsandbox ID.
opts?SandboxApiOptsconnection options.
Returns
Promise<SandboxInfo> sandbox information.

​
getMetrics()

static getMetrics(sandboxId: string, opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>
Get the metrics of the sandbox.
Parameters
ParameterTypeDescription
sandboxIdstringsandbox ID.
opts?SandboxMetricsOptssandbox 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
ParameterTypeDescription
sandboxIdstringsandbox ID.
opts?SandboxApiOptsconnection options.
Returns
Promise<boolean> true if the sandbox was found and killed, false otherwise.

​
list()

static list(opts?: SandboxListOpts): SandboxPaginator
List all sandboxes.
Parameters
ParameterTypeDescription
opts?SandboxListOptsconnection options.
Returns
SandboxPaginator paginator for listing 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

​
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.