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.

Command snippets

When you already have a Vercel sandbox, these are the commands that run inside it:

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.