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.

This page is a draft and may be incomplete or change significantly. If you have questions, reach out to us on Discord or open an issue.
Mesa’s virtual filesystem can be mounted inside any Linux-based VM or sandbox environment that supports FUSE. This lets your agents read and write repository files using normal filesystem operations — no cloning required. The general flow 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, write a config file 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 Mesa FUSE.

​
Daytona

Daytona provides secure, high-performance sandboxes that work well with Mesa. This example shows the full end-to-end flow: use the Mesa SDK outside the sandbox to set up resources, then use the Daytona SDK to configure and mount Mesa inside the sandbox. First, ensure that your Daytona image is properly configured. For example, you can use Daytona’s declarative image builder system, which exposes methods like dockerfileCommands. 
// Define a declarative image with Mesa dependencies
const declarativeImage = Image.debianSlim('3.12')
  .dockerfileCommands([
  // Install Mesa required system dependencies
  // These are typically already installed in base images, but you may need to add them explicitly if your image is slim.
  'RUN apt-get update && apt-get install -y --no-install-recommends \
    ca-certificates fuse3 libssl3 openssl \
    && rm -rf /var/lib/apt/lists/* \
    && update-ca-certificates',
  // Enable user_allow_other in FUSE config
  // This is required for non-root users to access the mounted filesystem.
  "RUN sed -i 's/^#user_allow_other/user_allow_other/' /etc/fuse.conf",
])
Now you can use the Daytona SDK to create a new sandbox with your properly configured image and mount MesaFS inside the sandbox. 
import { Daytona } from "@daytonaio/sdk";
import { Mesa } from "@mesadev/sdk";

const mesa = new Mesa({ apiKey: process.env.MESA_API_KEY });
const daytona = new Daytona({ apiKey: process.env.DAYTONA_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 daytona.create(
  {
    image: declarativeImage,
  },
  // ... with any other Daytona sandbox creation options
)

// Install the Mesa CLI
await sandbox.process.executeCommand(
  "curl -fsSL https://mesa.dev/install.sh | sh"
);

// Write the Mesa config file. Tokens go in the secret store, not this file
// — see /reference/mesa-cli-authentication.
const mesaConfig = `
mount-point = "/home/daytona/mesa/mnt"

[secrets]
backend = "plaintext-file"

[organizations.my-org]
`.trim();

await sandbox.fs.uploadFile(
  Buffer.from(mesaConfig),
  "/home/daytona/.config/mesa/config.toml"
);

// Register the token and mount. Sandboxes use the plaintext-file backend.
// See /reference/mesa-cli-authentication.
await sandbox.process.executeCommand(
  `mesa auth set-key --org my-org ${ephemeralKey.key}`
);
await sandbox.process.executeCommand("mesa mount --daemonize");

// --- Run your agent ---

await sandbox.process.executeCommand(
  'cd /home/daytona/mesa/mnt/my-org/agent-workspace \
    && claude "Implement the feature described in TODO.md"'
);
The same pattern applies to any sandbox provider — the only things that change are the provider SDK calls for creating the sandbox, writing files, and executing commands.

​
E2B

Coming soon. Coming soon.

​
Cloudflare

Coming soon.

​
Vercel

Coming soon.

​
Tips

  • Use scoped, short-lived API keys. Create a dedicated API key for each sandbox session with only the scopes it needs. See Auth & Permissions for details.
  • Enable prefetching. Mesa prefetches repository data in the background to reduce latency. This is especially useful in sandboxes where startup time matters. Prefetching is enabled by default, but you can further tune it to your needs in your config.toml.
  • 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 Mesa FUSE — this is the most common setup issue in sandbox environments.