Skip to main content
Mesa is a versioned virtual filesystem you can mount inside a Superserve sandbox. Where a cloud bucket gives a sandbox flat object storage, Mesa adds version history and branches, so every edit is committed back and each sandbox can fork its own workspace. This guide covers the full flow: use the Mesa SDK outside the sandbox to set up resources, then the Superserve SDK to mount Mesa inside. Mounting Mesa in a Superserve sandbox takes three steps:
  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 Mesa’s POSIX Mount guide.

Sandbox setup

Superserve sandboxes run on a FUSE-enabled kernel, and the Mesa installer apt-installs fuse3 as a dependency, so the standard Mesa install script works on every Superserve template out of the box. Because Superserve sandboxes are full Firecracker microVMs, you don’t need user_allow_other or chmod 666 /dev/fuse.

Custom template

For faster startup, pre-install the Mesa CLI into a custom Superserve template so each sandbox boots with the Mesa CLI already installed:
Reference it on sandbox creation and skip the runtime install step:

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 Mesa’s Authentication docs 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.
  • Build a custom template for production use. Pre-installing the Mesa CLI avoids the install overhead on every sandbox creation.
  • Mount path follows $HOME. Superserve’s guest agent sets HOME=/home/user, so the mount lands at /home/user/.local/share/mesa/mnt/<org>/<repo>. Use ~/.local/share/mesa/mnt/... and it resolves correctly.