Skip to main content
Vercel Sandbox provides isolated Linux sandboxes for running agent workflows. This guide shows the full end-to-end flow: use the Mesa SDK outside the sandbox to set up resources, then use the Vercel Sandbox 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 FUSE access, and start mesa mount as a detached sandbox command.
  3. Run your agent — run commands in the Mesa mount path (e.g. Claude Code, Codex, or a custom agent). Any file edits are automatically persisted back to Mesa.
For general information on FUSE setup, system dependencies, and container configuration, see POSIX Mount.

Sandbox setup

Vercel sandboxes run on Amazon Linux 2023, so install FUSE with dnf. The Mesa installer supports RPM-based Linux distributions, so the standard install script works on Vercel. Unlike shell-oriented sandbox SDKs, Vercel’s runCommand object form expects cmd to be the executable and args to be its arguments. Use sh -c only when you intentionally need shell syntax like pipes or redirection.
import { Sandbox } from "@vercel/sandbox";
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" });

// Sign a scoped, self-expiring access token for the sandbox. Signed locally
// from your API key with no network call — your API key never enters the
// sandbox. Scope it to the repos the session needs, as full `org/repo` names.
const { token } = await mesa.tokens.create({
  scopes: ["read", "write"],
  repos: ["my-org/agent-workspace"],
  ttl_seconds: 3600, // 1 hour
});

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

const sandbox = await Sandbox.create({
  teamId: process.env.VERCEL_TEAM_ID,
  projectId: process.env.VERCEL_PROJECT_ID,
  token: process.env.VERCEL_TOKEN,
});

// Install the Mesa CLI.
await sandbox.runCommand({
  cmd: "sh",
  args: ["-c", "curl -fsSL https://mesa.dev/install.sh | sh"],
});

// Install FUSE and enable non-root access to the FUSE mount.
await sandbox.runCommand({
  cmd: "dnf",
  args: ["install", "-y", "fuse3"],
  sudo: true,
});

await sandbox.runCommand({
  cmd: "sh",
  args: [
    "-c",
    [
      "echo user_allow_other >> /etc/fuse.conf",
      "chmod 666 /dev/fuse",
    ].join("\n"),
  ],
  sudo: true,
});

// Start Mesa as a detached command so it keeps the mount process alive.
// MESA_API_KEY accepts an API key or an access token; we pass the scoped token
// so the raw API key never enters the sandbox.
await sandbox.runCommand({
  cmd: "mesa",
  args: ["mount", "-y"],
  detached: true,
  env: {
    MESA_ORG: "my-org",
    MESA_API_KEY: token,
  },
});

// --- Run your agent ---

await sandbox.runCommand({
  cmd: "sh",
  args: ["-c", 'claude "Implement the feature described in TODO.md"'],
  cwd: "/home/user/.local/share/mesa/mnt/my-org/agent-workspace",
});

Command snippets

When you already have a Vercel sandbox, these are the commands that run inside it:
# Install the Mesa CLI.
curl -fsSL https://mesa.dev/install.sh | sh

# Install FUSE and enable non-root access.
sudo dnf install -y fuse3
sudo sh -c 'echo user_allow_other >> /etc/fuse.conf && chmod 666 /dev/fuse'

# Start Mesa as a long-running mount process. MESA_API_KEY accepts an API key
# or an access token; pass the scoped token you minted outside the sandbox.
MESA_ORG="my-org" MESA_API_KEY="$MESA_TOKEN" mesa mount -y

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

Example

For a runnable TypeScript example with a small interactive shell, see packages/examples/vercel-shell.

Tips

  • Use scoped, short-lived API keys. Create a dedicated API key for each sandbox session with only the scopes it needs. See Authentication for details.
  • Use Vercel’s detached commands. Run mesa mount -y with detached: true instead of mesa mount --daemonize; this lets Vercel keep the long-running mount process alive.
  • Run commands from the mount path. Set cwd to ~/.local/share/mesa/mnt/<org>/<repo> when running your agent command.
  • Configure FUSE explicitly. Vercel sandboxes need fuse3, user_allow_other, and non-root access to /dev/fuse.