E2B Sandbox

E2B provides Firecracker-based microVM sandboxes with true pause/resume: the full memory and filesystem state is preserved at zero compute cost while paused. This makes E2B the recommended provider for long-idle sessions and cost-sensitive deployments.

E2B is also the only provider that implements execCommand, making it the reference implementation for one-shot in-box command execution.

How E2B sessions work

When the platform dispatches a session to an e2b pool, E2BSandboxProvider.provision():

Resolves the org's e2b credential (or E2B_API_KEY env var).
Calls POST https://api.e2b.dev/sandboxes with the template ID, env vars, and timeout.
If config.launchRunnerInline is true, calls execCommand to launch donmai agent run in the background.
Returns a SandboxHandle with the E2B sandboxID.

The preferred setup is a custom template that bakes the donmai binary and sets donmai agent run as its start command - the runner starts automatically at boot with no extra round-trip.

Capability profile

Capability	Value
`transportModel`	`dial-in` (E2B envd exposes an exec endpoint)
`supportsFsSnapshot`	true
`supportsPauseResume`	true (full memory + FS, ~1s pause/resume)
`supportsCapacityQuery`	false (FaaS-style, opaque capacity)
`maxConcurrent`	null (tier-gated by E2B)
`maxSessionDurationSeconds`	null (tier-dependent)
`os`	linux
`arch`	x86_64
`idleCostModel`	zero (paused sandboxes cost $0)
`billingModel`	wall-clock (while running)
`supportsGpu`	false
`supportsCustomNetworkPolicy`	false
`egressDefault`	allow-all

The pause/resume + zero-idle combination makes E2B uniquely cost-effective for sessions that spend significant time waiting (e.g. waiting for human approval gates, long CI queues).

Substrate defaults

E2B class defaults do not include language toolchains - the bare base template bakes nothing:

Runtime kinds: npm, python-pip, http, mcp-server, a2a-protocol
Requirement kinds: long-running, network-egress, git, full-history-clone

To add toolchain:go or toolchain:node, bake them into your custom template and add them to the pool's runtime_provides override.

Setting up an E2B pool

Step 1: Add E2B credentials

In Settings → Integrations, find E2B and enter your E2B API key. Alternatively, set E2B_API_KEY in your platform environment.

Step 2: Build a custom E2B template

The bare base template does not include the donmai binary. You must build a custom template:

Create an E2B Dockerfile in your donmai repository at worker/e2b.Dockerfile:

FROM e2bdev/code-interpreter:latest

# Install donmai binary
ARG DONMAI_VERSION=v0.11.0
RUN curl -fsSL "https://github.com/renseiai/donmai/releases/download/${DONMAI_VERSION}/donmai_linux_amd64" \
    -o /usr/local/bin/donmai && chmod +x /usr/local/bin/donmai

# Start command: launch the in-box runner
CMD ["donmai", "agent", "run"]

Build and publish the template using the E2B CLI:

npm install -g @e2b/cli

e2b template build \
  --name donmai-worker \
  --dockerfile worker/e2b.Dockerfile \
  --start-cmd "donmai agent run"

Copy the template ID from the output (e.g. abc123def456).

Create an E2B capacity pool in Settings → Execution → Capacity → New pool → E2B and set templateId to your template ID.

Pool configuration

Config key	Type	Default	Description
`templateId`	string	`base`	E2B template ID. Must be a custom template with donmai binary.
`launchRunnerInline`	boolean	`false`	Launch `donmai agent run` via `execCommand` after provision. Use only if your template's start command cannot be set.

Example pool config

{
  "templateId": "abc123def456",
  "launchRunnerInline": false
}

`execCommand` - E2B's unique capability

E2B is the only sandbox provider that implements execCommand. It uses the E2B SDK's sandbox.commands.run to connect to the sandbox's envd process and run a shell command synchronously:

const result = await provider.execCommand(handle, 'which donmai', {})
// { exitCode: 0, stdout: '/usr/local/bin/donmai\n', stderr: '' }

Key behaviours:

Commands run via /bin/bash, so pipes, && chains, and nohup work as authored.
env parameter injects per-command environment variables (this is the only way to pass env to E2B templates whose start command can't receive create-time envs).
Timeout: 10 minutes (covers toolchain installs like npm ci).
Non-zero exits surface as { exitCode, stdout, stderr } rather than throwing.

execCommand is not the kit-install path. Kit toolchain installs run in-box via the donmai runtime's local shell after it clones the repo. execCommand is for one-shot post-provision use cases only.

Cost events

terminate emits a sandbox-seconds cost event via emitSandboxCostEvent, which records wall-clock usage in the billing ledger. This feeds the Cost per Issue analytics in the factory dashboard.

Pause and resume

E2B pause/resume is handled at the E2B API layer, not by the platform directly. The platform will expose pause/resume controls in a future release. For now, pausing is manual:

# Pause (via E2B CLI)
e2b sandbox pause <sandboxID>

# Resume - the platform can provision from a resumed sandbox ID
# Set config.snapshotId on the pool or use launchRunnerInline: true

Capacity Pools - pool management, runtime_provides overrides
Add a Provider - SandboxProvider interface and execCommand contract
Daytona - alternative cloud workspace provider
Modal - GPU workloads

On this page