Daytona

Daytona provides secure, high-performance 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 and sign a short-lived access token, then use the Daytona SDK to inject that token and mount Mesa inside the sandbox. The general flow for any sandbox integration is:

Outside the sandbox — the orchestrator holds the API key. Use the Mesa SDK (TypeScript or Python) to create repos, then sign a short-lived access token locally with mesa.tokens.create(...). Only the token crosses into the sandbox; the API key never does.
Inside the sandbox — install the mesa CLI, write a config file, and run mesa mount --daemonize with the injected token passed through the MESA_API_KEY environment variable to mount your repos as local directories.
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.

Access tokens are signed locally by whoever holds the API key — there is no server token endpoint and no network round-trip. The token’s scopes and repository restrictions are clamped against the signing key’s permissions on every request, and revoking the API key instantly invalidates every token it signed. For details on FUSE setup, system dependencies, and container configuration, see POSIX Mount.

Image setup

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

# Use the same image commands with Daytona's Python image builder or copy
# them into your Dockerfile.
dockerfile_commands = [
    """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""",
    "RUN sed -i 's/^#user_allow_other/user_allow_other/' /etc/fuse.conf",
]

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
RUN sed -i 's/^#user_allow_other/user_allow_other/' /etc/fuse.conf

Create and mount

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" });

// Sign a self-expiring access token for the sandbox. This is signed locally
// from your API key with no network call. Tokens are not stored anywhere —
// when the TTL elapses, the token is dead. Nothing to revoke.
// Pick a TTL that covers your agent session (max 24 hours).
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 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"
);

// Mount, injecting the scoped token through MESA_API_KEY (which accepts an API
// key or an access token). The raw API key never enters the sandbox.
await sandbox.process.executeCommand(
  `MESA_ORG=my-org MESA_API_KEY=${token} 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"'
);

import os
from mesa_sdk import Mesa

# --- Outside the sandbox: set up Mesa resources ---
mesa = Mesa(api_key=os.environ["MESA_API_KEY"])

# Create a repo (or use an existing one)
repo = await mesa.repos.create(name="agent-workspace")

# Sign a self-expiring access token for the sandbox. This is signed locally
# from your API key with no network call. Tokens are not stored anywhere —
# when the TTL elapses, the token is dead. Nothing to revoke.
# Pick a TTL that covers your agent session (max 24 hours).
minted = await mesa.tokens.create(
    scopes=["read", "write"],
    repos=["my-org/agent-workspace"],
    ttl_seconds=3600,  # 1 hour
)

# --- Inside the sandbox: run these with Daytona's Python command runner ---
# Install the Mesa CLI
install_cmd = "curl -fsSL https://mesa.dev/install.sh | sh"

# Mount, injecting the scoped token through MESA_API_KEY (which accepts an API
# key or an access token). The raw API key never enters the sandbox.
mount_cmd = f"MESA_ORG=my-org MESA_API_KEY={minted.token} mesa mount --daemonize"

# --- Run your agent ---
agent_cmd = 'cd /home/daytona/mesa/mnt/my-org/agent-workspace && claude "Implement the feature described in TODO.md"'

# Install the Mesa CLI
curl -fsSL https://mesa.dev/install.sh | sh

# Mount with the scoped token in this process' environment.
MESA_ORG=my-org MESA_API_KEY="$MESA_API_KEY" mesa mount --daemonize

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

An access token is minted once with a fixed TTL (capped at 24 hours) and is never refreshed: there is no background rotation and no credential hot-swap. Mint a token whose TTL covers the whole agent session. After it expires, filesystem operations in the sandbox fail with authentication errors. To continue past expiry, mint a fresh token on the host (the API key lives only outside the sandbox) and remount inside the sandbox with the new token in MESA_API_KEY.

Tips

Use access tokens, not API keys, inside sandboxes. Tokens expire on their own, can’t be used to sign further credentials, and leave nothing behind to clean up. See Authentication for details.
Pick a TTL that covers the session. The token must outlive your agent’s work. When in doubt, round up — a leaked token is still bounded by its TTL.
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 POSIX Mount — this is the most common setup issue in sandbox environments.

Getting Started

Concepts

MesaFS

Usage Patterns

Integrations

Image setup

Create and mount

Tips

​Image setup

​Create and mount

​Tips

Image setup

Create and mount

Tips