Skip to main content
Sprites (by Fly.io) provides stateful, disposable sandboxes that work well with Mesa. This guide shows the full end-to-end flow: use the Mesa SDK outside the sandbox to set up resources, then use the Sprites 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.

​
Create and mount

Sprites are Debian-based, so the standard Mesa install script works directly. Use execFile("sh", ["-c", ...]) to run shell commands — the SDK’s exec() method splits on whitespace and doesn’t support pipes or &&. 
import { SpritesClient } from "@fly/sprites";
import { Mesa } from "@mesadev/sdk";

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

// --- 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 sprite = await client.createSprite("mesa-sandbox");

// Install the Mesa CLI.
// Sprites exposes /dev/fuse as root-only by default, so we also fix permissions.
await sprite.execFile("sh", [
  "-c",
  [
    "curl -fsSL https://mesa.dev/install.sh | sh",
    "sed -i 's/^#user_allow_other/user_allow_other/' /etc/fuse.conf",
    "chmod 666 /dev/fuse",
  ].join(" && "),
]);

// Start Mesa as a background daemon.
// MESA_ORGS configures the org and API key in one step.
await sprite.execFile("sh", [
  "-c",
  `MESA_ORGS=my-org:${ephemeralKey.key} mesa mount -d -y`,
]);

// --- Run your agent ---

await sprite.execFile("sh", [
  "-c",
  'cd ~/.local/share/mesa/mnt/my-org/agent-workspace \
    && claude "Implement the feature described in TODO.md"',
]);

// Clean up when done
await sprite.destroy();

​
Tips

  • Use execFile, not exec. The Sprites SDK’s exec() method naively splits the command string on whitespace, breaking shell features like pipes (|) and chaining (&&). Always use execFile("sh", ["-c", "your command"]) instead.
  • 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.
  • Don’t forget user_allow_other. See OS-level Virtualization — this is the most common setup issue in sandbox environments.
  • Sprites are stateful. Unlike ephemeral sandboxes, Sprites persist state across connections. You can stop and resume a sprite without losing the Mesa mount — just re-run mesa mount --daemonize after resuming.