Superserve

Superserve provides sandboxes powered by Firecracker microVMs and optimized to run agent harnesses in production. This guide shows the full end-to-end flow: use the Mesa SDK outside the sandbox to set up resources, then use the Superserve SDK to configure and mount Mesa inside the sandbox. The general flow for any sandbox integration is:

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 mesa CLI, pass the token in as MESA_ACCESS_TOKEN, and run mesa mount --daemonize.
Run your agent — cd into the mount path and launch your agent (ex. 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

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.

import { Sandbox } from "@superserve/sdk";
import { Mesa, repo } from "@mesadev/sdk";

const mesa = new Mesa({ privateKey: process.env.MESA_PRIVATE_KEY });

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

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

// Sign a scoped, self-expiring access token for the sandbox. Signed locally
// from your private key with no network call — your private key never enters the sandbox.
const workspace = mesa.fs({
  layout: { "/workspace": repo("agent-workspace", { mode: "rw" }) },
  authors: [{ name: "Sandbox Agent", email: "agent@example.com" }],
  ttl: 60 * 60, // 1 hour; max 4 hours
});
const { token } = await workspace.token();

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

const sandbox = await Sandbox.create({ fromTemplate: "superserve/base" });

// Install the Mesa CLI. The installer apt-installs fuse3 as a dependency.
await sandbox.commands.run("curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0");

// Start Mesa as a background daemon with the short-lived token.
await sandbox.commands.run("mesa mount --daemonize", {
  env: {
    MESA_ACCESS_TOKEN: token,
  },
});

// --- Run your agent ---

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

import os
from mesa_sdk import Mesa, repo

# --- Outside the sandbox: set up Mesa resources ---
mesa = Mesa(private_key=os.environ["MESA_PRIVATE_KEY"])

# Create a repo (or use an existing one)
created = await mesa.repos.create(name="agent-workspace")

# Sign a scoped, self-expiring access token for the sandbox. Signed locally
# from your private key with no network call — your private key never enters the sandbox.
workspace = mesa.fs(
    layout={"/workspace": repo("agent-workspace", mode="rw")},
    authors=[{"name": "Sandbox Agent", "email": "agent@example.com"}],
    ttl=60 * 60,  # 1 hour; max 4 hours
)
minted = await workspace.token()

# --- Inside the sandbox: run these with Superserve's Python command runner ---
# Install the Mesa CLI. The installer apt-installs fuse3 as a dependency.
install_cmd = "curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0"

# Start Mesa as a background daemon with the short-lived token.
mount_cmd = "mesa mount --daemonize"
mount_env = {"MESA_ACCESS_TOKEN": minted.token}

# --- Run your agent ---
agent_cmd = 'cd ~/.local/share/mesa/mnt/my-org/agent-workspace && claude -p "Implement the feature described in TODO.md"'

# Install the Mesa CLI. The installer apt-installs fuse3 as a dependency.
curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0

# Start Mesa as a background daemon.
MESA_ACCESS_TOKEN="$MESA_ACCESS_TOKEN" mesa mount --daemonize

# --- Run your agent ---
cd ~/.local/share/mesa/mnt/my-org/agent-workspace
claude -p "Implement the feature described in TODO.md"

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 template

For faster startup, pre-install the Mesa CLI into a custom Superserve template so each sandbox boots with the Mesa CLI already installed:

import { Template } from "@superserve/sdk";

const template = await Template.create({
  name: "agent-with-mesa",
  vcpu: 2,
  memoryMib: 2048,
  diskMib: 4096,
  from: "ubuntu:24.04",
  steps: [
    { run: "apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git && rm -rf /var/lib/apt/lists/*" },
    { run: "curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0" },
  ],
});

await template.waitUntilReady();

# Use the same template steps with Superserve's Python template API.
template_steps = [
    "apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git && rm -rf /var/lib/apt/lists/*",
    "curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0",
]

FROM ubuntu:24.04
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git \
    && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0

Reference it on sandbox creation and skip the runtime install step:

const sandbox = await Sandbox.create({ fromTemplate: "agent-with-mesa" });

await sandbox.commands.run("mesa mount --daemonize", {
  env: {
    MESA_ACCESS_TOKEN: token,
  },
});

# Reference the prebuilt template in Superserve's Python SDK, then run:
mount_cmd = "mesa mount --daemonize"
mount_env = {"MESA_ACCESS_TOKEN": minted.token}

MESA_ACCESS_TOKEN="$MESA_ACCESS_TOKEN" mesa mount --daemonize

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 with your private key (which never enters the sandbox) and expires on its own. 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 sandbox start failing with authentication errors; mint a fresh token on the host and remount.
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.

Getting Started

Concepts

Reference

MesaFS

Usage Patterns

Integrations

Sandbox setup

Custom template

Tips

​Sandbox setup

​Custom template

​Tips

Sandbox setup

Custom template

Tips