Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt

Use this file to discover all available pages before exploring further.

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:
  1. Outside the sandbox — use the Mesa SDK (TypeScript or Python) to create repos, manage API keys, and orchestrate your workflow.
  2. Inside the sandbox — install the mesa CLI, configure it with your API key, 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 OS-level Virtualization.

​
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 } from "@mesadev/sdk";

const mesa = new Mesa({ apiKey: process.env.MESA_API_KEY });

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

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

// Create a scoped, short-lived API key for the sandbox
const ephemeralKey = await mesa.apiKeys.create({
  name: "sandbox-session",
  scopes: ["read", "write"],
  expires_in_seconds: 3600, // 1 hour
  // Optional: scope the key to a specific repo for better security
  // repo_ids: [repoId1, repoId2, ...],
});

// --- 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 -- --yes"
);

// Start Mesa as a background daemon.
// MESA_ORGS configures the org and API key in one step; on first boot
// it writes them into ~/.config/mesa/config.toml so you don't need to
// repeat them.
await sandbox.commands.run("mesa mount -d -y", {
  env: {
    MESA_ORGS: `my-org:${ephemeralKey.key}`,
  },
});

// --- Run your agent ---

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

​
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 -- --yes" },
  ],
});

await template.waitUntilReady();
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 -d -y", {
  env: {
    MESA_ORGS: `my-org:${ephemeralKey.key}`,
  },
});

​
Tips

  • Use scoped, short-lived API keys. Create a dedicated API key for each sandbox session with only the scopes it needs. See Auth and Permissions 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.