Skip to main content

Documentation Index

Fetch the complete documentation index at: https://e2b-squash-sandbox-pages.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Sandboxes stay running as long as you need them. When their timeout expires, they can automatically pause to save resources — preserving their full state so you can resume at any time. You can also configure an explicit timeout or shut down a sandbox manually.
Sandboxes can run continuously for up to 24 hours (Pro) or 1 hour (Base). For longer workloads, use pause and resume — pausing resets the runtime window, and your sandbox’s full state is preserved indefinitely.

​
Timeouts

Every sandbox has a configurable timeout that determines how long it stays running. You set it at creation time in milliseconds (JavaScript) or seconds (Python). 
import { Sandbox } from 'e2b'

// Create a sandbox and keep it running for 60 seconds.
// 🚨 Note: The units are milliseconds.
const sandbox = await Sandbox.create({
  timeoutMs: 60_000,
})

​
Change timeout at runtime

You can change the sandbox timeout when it’s running by calling the setTimeout method in JavaScript or set_timeout method in Python. When you call the set timeout method, the sandbox timeout will be reset to the new value that you specified. This can be useful if you want to extend the sandbox lifetime when it’s already running. You can for example start with a sandbox with 1 minute timeout and then periodically call set timeout every time user interacts with it in your app. 
import { Sandbox } from 'e2b'

// Create a sandbox and keep it running for 60 seconds.
const sandbox = await Sandbox.create({ timeoutMs: 60_000 })

// Change the sandbox timeout to 30 seconds.
// 🚨 The new timeout will be 30 seconds from now.
await sandbox.setTimeout(30_000)

​
Retrieve sandbox information

You can retrieve sandbox information like sandbox ID, template, metadata, started at/end at date by calling the getInfo method in JavaScript or get_info method in Python. 
import { Sandbox } from 'e2b'

// Create a sandbox and keep it running for 60 seconds.
const sandbox = await Sandbox.create({ timeoutMs: 60_000 })

// Retrieve sandbox information.
const info = await sandbox.getInfo()

console.log(info)

// {
//   "sandboxId": "iiny0783cype8gmoawzmx-ce30bc46",
//   "templateId": "rki5dems9wqfm4r03t7g",
//   "name": "base",
//   "metadata": {},
//   "startedAt": "2025-03-24T15:37:58.076Z",
//   "endAt": "2025-03-24T15:42:58.076Z"
// }

​
Metadata

Metadata lets you attach arbitrary key-value pairs to a sandbox. This is useful for associating sandboxes with user sessions, storing custom data, or looking up sandboxes later via Sandbox.list(). You specify metadata when creating a sandbox and can access it later through listing sandboxes. 
import { Sandbox } from 'e2b'

// Create sandbox with metadata.
const sandbox = await Sandbox.create({
  metadata: {
    userId: '123',
  },
})

// List running sandboxes and access metadata.
const paginator = await Sandbox.list()
const runningSandboxes = await paginator.nextItems()
// Will print:
// {
//   'userId': '123',
// }
console.log(runningSandboxes[0].metadata)
You can also filter sandboxes by metadata.

​
List sandboxes

You can list sandboxes using the Sandbox.list() method. The method supports pagination and returns both running and paused sandboxes.
Once you have information about a running sandbox, you can connect to it using the Sandbox.connect() method.
import { Sandbox, SandboxInfo } from 'e2b'

const sandbox = await Sandbox.create(
  {
    metadata: {
      name: 'My Sandbox',
    },
  },
)

const paginator = Sandbox.list()

// Get the first page of sandboxes (running and paused)
const firstPage = await paginator.nextItems()

const runningSandbox = firstPage[0]

console.log('Running sandbox metadata:', runningSandbox.metadata)
console.log('Running sandbox id:', runningSandbox.sandboxId)
console.log('Running sandbox started at:', runningSandbox.startedAt)
console.log('Running sandbox template id:', runningSandbox.templateId)

// Get the next page of sandboxes
const nextPage = await paginator.nextItems()

​
Filter sandboxes

Filter sandboxes by their current state. The state parameter can contain either “running” for running sandboxes or “paused” for paused sandboxes, or both. 
import { Sandbox } from 'e2b'

// Create a sandbox.
const sandbox = await Sandbox.create()

// List sandboxes that are running or paused.
const paginator = Sandbox.list({
  query: {
    state: ['running', 'paused'],
  },
})

const sandboxes = await paginator.nextItems()
You can also filter sandboxes by metadata key-value pairs specified during creation. 
import { Sandbox } from 'e2b'

// Create sandbox with metadata.
const sandbox = await Sandbox.create({
  metadata: {
    env: 'dev',
    app: 'my-app',
    userId: '123',
  },
})

// List all sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
const paginator = Sandbox.list({
  query: {
    metadata: { userId: '123', env: 'dev' },
  },
})

const sandboxes = await paginator.nextItems()

​
Advanced pagination

For more granular pagination, you can set custom per-page item limit (default and maximum is 100) and specify an offset parameter (nextToken or next_token) to start paginating from. 
import { Sandbox } from 'e2b'

const paginator = Sandbox.list({
  limit: 100,
  nextToken: '<base64-encoded-token>',
})

// Additional paginator properties
// Whether there is a next page
paginator.hasNext

// Next page token
paginator.nextToken

// Fetch the next page
await paginator.nextItems()
You can fetch all pages by looping through the paginator while checking if there is a next page (using hasNext or has_next property) and fetching until there are no more pages left to fetch: 
import { Sandbox } from 'e2b'

const paginator = Sandbox.list()

// Loop through all pages
const sandboxes: SandboxInfo[] = []
while (paginator.hasNext) {
  const items = await paginator.nextItems()
  sandboxes.push(...items)
}

​
Connect to a sandbox

If you have a running sandbox, you can connect to it using the Sandbox.connect() method and start controlling it with the SDK. This is useful for reusing the same sandbox instance after a period of inactivity, or for resuming a paused sandbox.

​
1. Get the sandbox ID

To connect to a running sandbox, you first need to retrieve its ID. You can do this by calling the Sandbox.list() method. 
import { Sandbox } from 'e2b'

const sbx = await Sandbox.create()

// Get all running sandboxes
const paginator = await Sandbox.list({
  query: { state: ['running'] },
})

const runningSandboxes = await paginator.nextItems()
if (runningSandboxes.length === 0) {
  throw new Error('No running sandboxes found')
}

// Get the ID of the sandbox you want to connect to
const sandboxId = runningSandboxes[0].sandboxId

​
2. Connect to the sandbox

Now that you have the sandbox ID, you can connect to the sandbox using the Sandbox.connect() method. 
import { Sandbox } from 'e2b'

const sandbox = await Sandbox.connect(sandboxId)

// Now you can use the sandbox as usual
// ...
const result = await sandbox.commands.run("whoami")
console.log(`Running in sandbox ${sandbox.sandboxId} as "${result.stdout.trim()}"`)

​
Shutdown sandbox

You can shutdown the sandbox any time even before the timeout is up by calling the kill method. 
import { Sandbox } from 'e2b'

// Create a sandbox and keep it running for 60 seconds.
const sandbox = await Sandbox.create({ timeoutMs: 60_000 })

// Shutdown the sandbox immediately.
await sandbox.kill()