- Outside the sandbox — use the Mesa SDK (TypeScript or Python) to create repos, sign a short-lived access token, and orchestrate your workflow.
- Inside the sandbox — install the
mesaCLI, pass the token in asMESA_ACCESS_TOKEN, and runmesa mount --daemonize. - 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.
Setup
The example uses two environment variables:Example Code
Freestyle sandboxes are Debian-based by default, so the standard Mesa install script works out of the box.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>.Tips
- Mint the token outside the sandbox. Sign a short-lived, scoped access token with your private key outside the VM and pass only that token as
MESA_ACCESS_TOKEN. Your private key never crosses the sandbox boundary. See Authentication for details. - Pick a TTL that covers the session. Tokens default to a 15 minute TTL and max out at 4 hours, and a mount keeps the token it started with for its whole lifetime. If the token expires mid-session, filesystem operations in the VM start failing with authentication errors; mint a fresh token on the host and remount.
- Install Mesa ahead of time when startup time matters. Installing at runtime is fine for a demo, but preinstalling Mesa and its dependencies makes VM startup faster and more predictable.
- Always use
--daemonize. This keeps Mesa mounted while your shell or agent continues to run. - Don’t forget
user_allow_other. See POSIX Mount for the most common FUSE setup issue in sandbox environments. - Expect mount paths to depend on the VM user. In this example the VM runs as
root, so Mesa mounts under/root/.local/share/mesa/mnt.

