- 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.
- Inside the sandbox — install the
mesaCLI and runmesa mount --daemonizewith the token inMESA_ACCESS_TOKEN. - Run your agent —
cdinto 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.
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>.Custom sandbox template
For faster startup, pre-install Mesa into a custom E2B template. Create a Dockerfile: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 runmesa mount --daemonizein 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.

