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 with your private key, and orchestrate your workflow.
  2. Inside the sandbox — install the mesa CLI and run mesa mount --daemonize with the token in MESA_ACCESS_TOKEN.
  3. Run your agentcd 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. Two E2B specifics need root before mounting: /dev/fuse is exposed as root-only, so chmod 666 it, and user_allow_other must be enabled in /etc/fuse.conf so non-root processes can access the mount. You can also build a custom sandbox template with Mesa pre-installed to skip the install step at runtime.
The layout scopes the token: it can reach the repositories the layout declares and nothing else. A plain mesa mount then shows exactly those repositories under the organization browse tree. To mount the layout’s own paths instead, serialize workspace.layout() with JSON.stringify(...) in TypeScript or json.dumps(...) in Python, write it into the sandbox, and mount with mesa mount --layout <file>.
The Mesa CLI version is pinned so sandbox setups are reproducible. Update the pinned version periodically to pick up fixes and new features.
An access token is minted once with a fixed TTL and is never refreshed: there is no background rotation and no access-token replacement. Tokens default to a 15 minute TTL and max out at 4 hours, so mint one whose TTL covers the whole agent session. After it expires, filesystem operations in the sandbox fail with authentication errors. To continue past expiry, mint a fresh token on the host (the private key lives only outside the sandbox) and remount inside the sandbox with the new token in MESA_ACCESS_TOKEN.

Custom sandbox template

For faster startup, pre-install Mesa into a custom E2B template. Create a Dockerfile:
Build and deploy with e2b template build, then reference your template when creating sandboxes:

Tips

  • Use scoped, short-lived access tokens. Sign a dedicated token for each sandbox session with only the scopes and repos it needs. It expires on its own and can’t mint further access tokens. 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. This is the most common setup issue in sandbox environments. See POSIX Mount for more info.
  • Build a custom template for production use. Pre-installing Mesa avoids the install overhead on every sandbox creation.