E2B

When working with E2B sandboxes, follow these recommended defaults:

• Template: Use the base template unless a specific requirement dictates otherwise.
• Shell Execution: Prefer bash -lc for executing multi-command strings via the CLI or SDK to ensure the environment is correctly loaded.
• File Storage: Store temporary files in /tmp or the current working directory within the sandbox.
• Code Execution: For workloads specifically requiring code execution (e.g., run_code or runCode), use the Code Interpreter SDK instead of standard sandbox commands.

E2B infrastructure can be self-hosted using Terraform. Supported cloud providers include:

• AWS
• Google Cloud (GCP)

Refer to the self-hosting guide for detailed instructions.

For specialized code execution (e.g., running Python snippets and getting results), install the dedicated Code Interpreter SDK.

Installation

• JavaScript/TypeScript: npm i @e2b/code-interpreter
• Python: pip install e2b-code-interpreter

Usage (TypeScript) Use sandbox.runCode() to execute code strings. The result contains the output text.

Usage (Python) Use sandbox.run_code() to execute code strings.

import { Sandbox } from '@e2b/code-interpreter'

const sandbox = await Sandbox.create()
const execution = await sandbox.runCode('x = 1; x += 1; x')
console.log(execution.text)  // outputs 2

To use E2B sandboxes and APIs provisioned through Stripe Projects, you must first add E2B to your Stripe project and then pull the managed environment variables.

Note: Do not use stripe projects env --json to extract keys for runtime use, as secret values like E2B_API_KEY may be redacted. Instead, use stripe projects env --pull --yes to download a .env file and extract the required variables manually.

# Add E2B to the current Stripe project
stripe projects add e2b/sandboxes

# Pull provisioned credentials to a .env file
stripe projects env --pull --yes

If the E2B CLI is not installed or the shell shim is broken, you can install it globally using npm. This requires Node 20 or newer.

if ! e2b --version >/dev/null 2>&1; then
  npm install -g @e2b/cli
fi

The E2B CLI allows you to create, execute commands in, and resume sandboxes.

Create a sandbox

Use the --detach flag for non-interactive work. This returns a sandbox ID immediately instead of attaching an interactive terminal.

e2b sandbox create base --detach

Execute commands

Use -- before your shell command to prevent the CLI from parsing your shell flags. For multi-command execution, it is recommended to use bash -lc.

e2b sandbox exec <sandbox_id> -- bash -lc 'pwd && ls -la'

Run long-running processes

Run processes in the background and write a PID file within the sandbox to track them:

e2b sandbox exec <sandbox_id> -- bash -lc 'nohup python server.py >server.log 2>&1 & echo $! >server.pid'

Resume a sandbox

e2b sandbox resume <sandbox_id>

You can install the E2B SDK for either JavaScript/TypeScript or Python to start managing sandboxes.

JavaScript / TypeScript

npm i e2b

Python

pip install e2b

To use E2B, you must obtain an API key from the E2B dashboard and set it as an environment variable named E2B_API_KEY.

1. Sign up at e2b.dev.
2. Retrieve your key from the E2B Dashboard.
3. Set the environment variable: E2B_API_KEY=e2b_***

The E2B CLI resolves the projectId (or teamId) using the following precedence order:

1. CLI Flag: The --project flag (note: --team is deprecated).
2. Environment Variable: The E2B_PROJECT_ID environment variable (note: E2B_TEAM_ID is deprecated).
3. User Config: The projectId defined in your local config file (~/.e2b/config.json).

Important Note on Precedence: To prevent mismatches between an environment-provided API key and a local config file, the CLI will only fall back to the projectId in your local config file if the E2B_API_KEY environment variable is not set.

A CommandHandle is returned when you run a command with { background: true } or use Commands.connect(pid). It allows you to manage the lifecycle and I/O of a running process.

Common methods on CommandHandle:

• wait(): Returns a Promise<CommandResult> that resolves when the process exits.
• sendStdin(data, opts): Sends data to the process's standard input.
• closeStdin(opts): Signals EOF to the process (only if the command was started with stdin: true).
• kill(): Terminates the process.
• onStdout / onStderr: Listeners for process output streams.