# E2B Sandboxes

E2B sandboxes for Bijection agent applications

- Package: @bijectionhq/e2b
- Category: Sandboxes
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/e2b/tree/2024f8d7d5fdb7eeb855eb92d57829b05f39a6b2
- Upstream: https://github.com/e2b-dev/e2b-convex/tree/1ed44191acdcd0f9b024e7fd91dd614544bc6821
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/e2b

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/e2b.git
cd e2b
git checkout 2024f8d7d5fdb7eeb855eb92d57829b05f39a6b2
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @e2b/convex; check the Bijection adaptation separately.

A tableless Convex component that provides a V8-compatible E2B client for managing persistent cloud sandboxes inside Convex actions. It handles sandbox lifecycle (create, pause, resume), shell command execution, file operations, and preview hosts without requiring the full Node-oriented E2B SDK. Includes first-class integrations for Convex Agent and the Vercel AI SDK via optional subpackage imports.

### Use cases

- Running isolated shell commands per user session in an AI coding agent, where each session maps to a persistent sandbox identified by scope and key
- Building an agentic workflow with Convex Agent that needs safe, sandboxed code execution with per-thread tool access and optional approval rules
- Serving preview hosts from within a sandbox for live app previews generated by an AI agent during a Convex action
- Reading and writing files inside a sandboxed environment as part of a multi-step AI pipeline, with path restrictions enforced to `/home/user` and `/tmp`
- Integrating AI SDK tool calls into a Convex action that require sandboxed execution, without importing Node-only dependencies into the Convex runtime

### How it works

Install the package and set your E2B API key with `npx convex env set E2B_API_KEY`. Register the component in `convex/convex.config.ts` using `app.use(e2b, ...)` and bind the secret through the app environment. The component is tableless and stores no data in Convex; sandbox identity is tracked via namespaced E2B metadata using hashed scope and key values you provide.

Inside a Convex action, instantiate `new E2B(components.e2b, { template, timeoutMs })` and call `sandboxes.getOrCreate(ctx, { scope, key })` to retrieve or create a sandbox. Subsequent operations like `runCommand` accept the returned `sandboxId` directly to skip redundant resolution. Sandboxes automatically pause on timeout and resume on the next operation, which restarts billing.

For AI integrations, `createAgentTools` from `@e2b/convex/agent` produces thread-aware tools compatible with Convex Agent, while `createAiSdkTools` from `@e2b/convex/ai` produces standard AI SDK tools usable in any action. Both subpackages are optional and have no effect on the core bundle. Command output is bounded to 32 KiB per stream by default, file reads cap at 1 MiB, and writes at 4 MiB, with file tool access restricted to safe paths unless explicitly reconfigured.

### Upstream README

# @e2b/convex

Persistent [E2B](https://e2b.dev) sandboxes for Convex applications and AI agents.

`@e2b/convex` is a tableless Convex component with a small V8-compatible E2B client. It gives Convex actions sandbox lifecycle, commands, bounded file operations, preview hosts, Convex Agent tools, and plain AI SDK tools without shipping the full Node-oriented E2B SDK into the Convex runtime.

> Pre-1.0: validate the package against your E2B template and network policy before production use.

## Install

```sh
npm install @e2b/convex
npx convex env set E2B_API_KEY e2b_your_key
```

Register the component and bind the secret in your Convex app:

```ts
// convex/convex.config.ts
import e2b from "@e2b/convex/convex.config.js";
import { defineApp } from "convex/server";
import { v } from "convex/values";

const app = defineApp({ env: { E2B_API_KEY: v.string() } });
app.use(e2b, { env: { E2B_API_KEY: app.env.E2B_API_KEY } });

export default app;
```

## Run a command

Create the client in a Convex action and identify the sandbox with an application-owned `scope` and `key`:

```ts
// convex/sandbox.ts
import { E2B } from "@e2b/convex";
import { v } from "convex/values";
import { components } from "./_generated/api";
import { action } from "./_generated/server";

const sandboxes = new E2B(components.e2b, {
  template: "base",
  timeoutMs: 10 * 60_000,
});

export const run = action({
  args: { userId: v.string(), sessionId: v.string(), command: v.string() },
  handler: async (ctx, args) => {
    const identity = { scope: args.userId, key: args.sessionId };
    const sandbox = await sandboxes.getOrCreate(ctx, identity);

    return sandboxes.runCommand(ctx, {
      ...identity,
      sandboxId: sandbox.sandboxId,
      command: args.command,
    });
  },
});
```

Calls with the same scope and key reuse the same running or paused sandbox. Resolve it once before parallel work and pass `sandboxId` to subsequent operations.

## Integrations

- **Minimal API:** lifecycle, shell commands, files, directories, and preview hosts.
- **Convex Agent:** `createAgentTools(sandboxes, ...)` from `@e2b/convex/agent` creates thread-aware tools with optional approval rules. Requires `@convex-dev/agent` and `ai`.
- **AI SDK:** `createAiSdkTools(sandboxes, ctx, ...)` from `@e2b/convex/ai` creates standard AI SDK tools inside any Convex action. Requires `ai`.

The core package has no runtime dependency on either; install them only for the integration you use.

Start with the [getting-started guide](docs/getting-started.md), then use the copy-paste [cookbook](docs/cookbook.md). The complete local app in [`example`](example/README.md) includes an xterm.js terminal and a realtime agent chat with visible tool calls.

## Defaults and limits

- Sandboxes pause on timeout and are rediscovered through namespaced E2B metadata. Any operation on a paused sandbox resumes it, which restarts billing.
- Every operation resolves the sandbox first (`getInfo` + `connect`, or a metadata list when `sandboxId` is absent), adding roughly a second per call.
- Scope and key values are hashed before entering E2B metadata.
- Command output is bounded to 32 KiB per stream by default.
- Command output and individual file reads are capped at 1 MiB.
- File reads default to 64 KiB; writes are capped at 4 MiB.
- File tools are restricted to `/home/user` and `/tmp` unless configured otherwise.
- `getHost` is not exposed to an agent unless explicitly enabled.
- Every E2B request is tagged with `e2b-convex/<version>` for integration attribution.

See [security](docs/security.md), [operations](docs/operations.md), and [architecture](docs/architecture.md) before deploying an agent that executes untrusted instructions.

## Status

The package uses E2B's public APIs and includes only the Process and Filesystem protocol descriptors required by the component. The pinned `e2b` package is a development-only protocol source. CI rejects Node built-ins or full-SDK imports in the emitted Convex runtime and a scheduled real-service test watches for protocol drift.

MIT