Skip to main content
E2B provides open-source, secure cloud sandboxes for AI agents. This guide shows the full end-to-end flow: use the Mesa SDK outside the sandbox to set up resources, then use the E2B SDK to configure and mount Mesa inside the sandbox. The general flow for any sandbox integration is:
  1. Outside the sandbox — use the Mesa SDK (TypeScript or Python) to create repos, sign a short-lived access token, and orchestrate your workflow.
  2. Inside the sandbox — install the mesa CLI, configure it with a short-lived access token, and run mesa mount --daemonize to mount your repos as local directories.
  3. Run your agent — cd into the mount path and launch your agent (e.g. Claude Code, Codex, or a custom agent). Any file edits are automatically persisted back to Mesa.
For details on FUSE setup, system dependencies, and container configuration, see POSIX Mount.

​
Sandbox setup

E2B sandboxes are Debian-based by default, so the standard Mesa install script works out of the box. You can also build a custom sandbox template with Mesa pre-installed to skip the install step at runtime. 
import { Sandbox } from "e2b";
import { Mesa } from "@mesadev/sdk";

const mesa = new Mesa({ apiKey: process.env.MESA_API_KEY });

// --- Outside the sandbox: set up Mesa resources ---

// Create a repo (or use an existing one)
const repo = await mesa.repos.create({ name: "agent-workspace" });

// Sign a scoped, self-expiring access token for the sandbox. Signed locally
// from your API key with no network call — your API key never enters the sandbox.
const { token } = await mesa.tokens.create({
  scopes: ["read", "write"],
  repos: ["my-org/agent-workspace"],
  ttl_seconds: 3600, // 1 hour
});

// --- Inside the sandbox: install and mount Mesa ---

const sandbox = await Sandbox.create();

// Install Mesa dependencies and the CLI.
// E2B exposes /dev/fuse as root-only by default, so we also fix permissions.
await sandbox.commands.run(
  [
    "apt-get update",
    "apt-get install -y --no-install-recommends ca-certificates curl fuse3 gpg",
    "sed -i 's/^#user_allow_other/user_allow_other/' /etc/fuse.conf",
    "chmod 666 /dev/fuse",
    "curl -fsSL https://mesa.dev/install.sh | sh -s -- --yes",
  ].join(" && "),
  { user: "root" }
);

// Start Mesa as a background daemon. MESA_ORG configures the org; MESA_API_KEY
// accepts an API key OR an access token — we pass the short-lived token minted
// above, so the raw API key never enters the sandbox.
await sandbox.commands.run("mesa mount -d -y", {
  envs: {
    MESA_ORG: "my-org",
    MESA_API_KEY: token,
  },
});

// --- Run your agent ---

await sandbox.commands.run(
  'cd ~/.local/share/mesa/mnt/my-org/agent-workspace \
    && claude "Implement the feature described in TODO.md"'
);

​
Custom sandbox template

For faster startup, pre-install Mesa into a custom E2B template. Create a Dockerfile: 
FROM e2b/base:latest
RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates curl fuse3 gpg \
    && curl -fsSL https://mesa.dev/install.sh | sh -s -- --yes \
    && sed -i 's/^#user_allow_other/user_allow_other/' /etc/fuse.conf \
    && chmod 666 /dev/fuse \
    && rm -rf /var/lib/apt/lists/*
Build and deploy with e2b template build, then reference your template when creating sandboxes: 
const sandbox = await Sandbox.create({ template: "my-mesa-template" });

​
Tips

  • Use scoped, short-lived access tokens. Sign a dedicated token for each sandbox session with only the scopes it needs — it’s signed locally from your API key (which never enters the sandbox) and expires on its own. See Authentication for details.
  • Use --daemonize. Always run mesa mount --daemonize in sandbox environments so Mesa runs as a background process and doesn’t block your agent’s terminal.
  • Don’t forget user_allow_other. See POSIX Mount — this is the most common setup issue in sandbox environments.
  • Build a custom template for production use — pre-installing Mesa avoids the install overhead on every sandbox creation.