Customizing sandboxes at runtime

Install packages, upload files, and configure E2B sandboxes at runtime when you can’t bake everything into a template.

Templates define a sandbox’s base environment, but many workloads need dynamic configuration — different packages per user, files uploaded at request time, or settings that change between runs. This guide covers patterns for customizing sandboxes at runtime without modifying your template.

When to use runtime customization vs. templates

Use case	Template	Runtime
Same packages for every sandbox	Yes
Packages vary per user or request		Yes
Static config files, shared across sandboxes	Yes
User-uploaded files or per-request data		Yes
Secrets that change per request		Yes

When in doubt: if every sandbox needs it, put it in a template. If it varies per user or request, handle it at runtime.

Install packages at runtime

Use sandbox.commands.run() to install packages after the sandbox starts. This is useful when different users or requests need different dependencies.

JavaScript & TypeScript

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create()

// Install Python packages
await sandbox.commands.run('pip install pandas numpy matplotlib')

// Install system packages
await sandbox.commands.run('sudo apt-get update && sudo apt-get install -y ffmpeg')

// Install Node.js packages
await sandbox.commands.run('npm install express')

For packages you install in every sandbox, add them to a template instead. Template-based installs are faster because they’re baked into the sandbox image.

Speed up repeated installs with snapshots

If multiple sandboxes need the same runtime setup, install once and snapshot the result. New sandboxes start from the snapshot with everything already installed.

JavaScript & TypeScript

import { Sandbox } from 'e2b'

// First time: install and snapshot
const sandbox = await Sandbox.create()
await sandbox.commands.run('pip install pandas numpy scikit-learn')

const snapshot = await sandbox.createSnapshot()
console.log('Snapshot ID:', snapshot.snapshotId)

// Later: start from snapshot — packages are already installed
const fast = await Sandbox.create(snapshot.snapshotId)

Upload files at sandbox start

Use sandbox.files.write() to upload configuration files, scripts, or user data into the sandbox.

JavaScript & TypeScript

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create()

// Upload a configuration file
await sandbox.files.write('/home/user/config.json', JSON.stringify({
  apiEndpoint: 'https://api.example.com',
  maxRetries: 3,
}))

// Upload a script
await sandbox.files.write('/home/user/analyze.py', `
import json
with open('config.json') as f:
    config = json.load(f)
print(f"Connecting to {config['apiEndpoint']}")
`)

// Run the uploaded script
const result = await sandbox.commands.run('cd /home/user && python analyze.py')
console.log(result.stdout)

Use environment variables

Pass per-request configuration through environment variables. You can set them globally at sandbox creation or per command.

JavaScript & TypeScript

import { Sandbox } from 'e2b'

// Set environment variables at creation
const sandbox = await Sandbox.create({
  envs: {
    API_KEY: 'sk-user-123-key',
    ENVIRONMENT: 'production',
  },
})

// Or set per command
const result = await sandbox.commands.run('echo $CUSTOM_VAR', {
  envs: { CUSTOM_VAR: 'hello' },
})
console.log(result.stdout) // "hello"

Use start_cmd for initialization

If your template supports a start command, you can override it at runtime to customize sandbox initialization.

JavaScript & TypeScript

import { Sandbox } from 'e2b'

const sandbox = await Sandbox.create('my-template', {
  startCmd: 'python /home/user/setup.py && nginx -g "daemon off;"',
})

Combine patterns

For complex setups, combine multiple approaches. Here’s an example setting up a data analysis sandbox per user:

JavaScript & TypeScript

import { Sandbox } from 'e2b'

async function createAnalysisSandbox(userId, dataUrl, packages) {
  const sandbox = await Sandbox.create({
    timeoutMs: 10 * 60 * 1000,
    lifecycle: {
      onTimeout: 'pause',
      autoResume: true,
    },
    envs: {
      USER_ID: userId,
      DATA_URL: dataUrl,
    },
  })

  // Install user-specific packages
  if (packages.length > 0) {
    await sandbox.commands.run(`pip install ${packages.join(' ')}`)
  }

  // Upload analysis script
  await sandbox.files.write('/home/user/run.py', `
import os, urllib.request
urllib.request.urlretrieve(os.environ['DATA_URL'], '/home/user/data.csv')
print(f"Data downloaded for user {os.environ['USER_ID']}")
  `)

  await sandbox.commands.run('python /home/user/run.py')
  return sandbox
}