Blaxel

Blaxel provides lightweight sandboxes that work well with Mesa. This guide shows the full end-to-end flow: set up Mesa inside a Blaxel sandbox and mount your repos as local directories. The general flow for any sandbox integration is:

Outside the sandbox — use the Mesa SDK (TypeScript or Python) to create repos, sign a short-lived access token with your private key, and orchestrate your workflow.
Inside the sandbox — install the mesa CLI and run mesa mount --daemonize with the token in MESA_ACCESS_TOKEN.
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 POSIX Mount.

Alpine-based setup (default image)

Blaxel’s default image is Alpine-based. The Mesa install script handles Alpine natively — it detects the architecture, adds the correct APK repository, and installs Mesa:

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.create({ region: "us-pdx-1" });

// Install system dependencies and Mesa.
// gcompat (not libc6-compat) is required — the Mesa daemon's gRPC
// connections deadlock under libc6-compat's musl shim.
await sandbox.process.exec({
  command: "apk add --no-cache curl ca-certificates gcompat fuse3 && curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0",
  waitForCompletion: true,
});

# Install system dependencies and Mesa.
# gcompat (not libc6-compat) is required — the Mesa daemon's gRPC
# connections deadlock under libc6-compat's musl shim.
# Run this command with Blaxel's Python sandbox command runner.
install_cmd = "apk add --no-cache curl ca-certificates gcompat fuse3 && curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0"

# Install system dependencies and Mesa.
# gcompat (not libc6-compat) is required — the Mesa daemon's gRPC
# connections deadlock under libc6-compat's musl shim.
apk add --no-cache curl ca-certificates gcompat fuse3
curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0

The layout scopes the token: it can reach the repositories the layout declares and nothing else. A plain mesa mount then shows exactly those repositories under the organization browse tree. To mount the layout’s own paths instead, serialize workspace.layout() with JSON.stringify(...) in TypeScript or json.dumps(...) in Python, write it into the sandbox, and mount with mesa mount --layout <file>.

Debian-based setup (custom template)

If you prefer Debian, you can build a custom Blaxel template with Mesa pre-installed. Create a Dockerfile:

FROM debian:bookworm-slim
COPY --from=ghcr.io/blaxel-ai/sandbox:latest /sandbox-api /usr/local/bin/sandbox-api
RUN apt-get update && apt-get install -y curl fuse3 ca-certificates \
    && curl -fsSL https://mesa.dev/install.sh | sh -s -- --version 0.46.0 \
    && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["/usr/local/bin/sandbox-api"]

Deploy with bl deploy, then reference your template when creating sandboxes:

const sandbox = await SandboxInstance.create({
  image: "your-template:latest",
  region: "us-pdx-1",
});

# Use the same image and region with Blaxel's Python SDK.
sandbox_options = {
    "image": "your-template:latest",
    "region": "us-pdx-1",
}

Mount Mesa

Once the CLI is installed (via either method), configure and mount:

import { Mesa, repo } from "@mesadev/sdk";

const mesa = new Mesa({ privateKey: process.env.MESA_PRIVATE_KEY });

// Create a repo (or use an existing one)
const created = await mesa.repos.create({ name: "agent-workspace" });

// Sign a scoped, self-expiring access token for the sandbox. Signed locally
// with your private key, no network call. The private key never enters
// the sandbox.
const workspace = mesa.fs({
  layout: { "/workspace": repo(created.name, { mode: "rw" }) },
  authors: [{ name: "Sandbox Agent", email: "agent@example.com" }],
  ttl: 60 * 60, // 1 hour, max 4 hours
});
const { token } = await workspace.token();

// Start Mesa as a background daemon with the short-lived token.
await sandbox.process.exec({
  command: `MESA_ACCESS_TOKEN=${token} mesa mount --daemonize`,
  waitForCompletion: true,
});

// Your repos are now at ~/.local/share/mesa/mnt/<org>/<repo>
await sandbox.process.exec({
  command: `cd ~/.local/share/mesa/mnt/${created.org}/${created.name} \
    && claude -p "Implement the feature described in TODO.md"`,
  waitForCompletion: true,
});

import os
from mesa_sdk import Mesa, repo

mesa = Mesa(private_key=os.environ["MESA_PRIVATE_KEY"])

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

# Sign a scoped, self-expiring access token for the sandbox. Signed locally
# with your private key, no network call. The private key never enters
# the sandbox.
workspace = mesa.fs(
    layout={"/workspace": repo(created.name, mode="rw")},
    authors=[{"name": "Sandbox Agent", "email": "agent@example.com"}],
    ttl=60 * 60,  # 1 hour, max 4 hours
)
minted = await workspace.token()

# Start Mesa as a background daemon with the short-lived token.
# Run this command with Blaxel's Python sandbox command runner.
mount_cmd = f"MESA_ACCESS_TOKEN={minted.token} mesa mount --daemonize"

# Your repos are now at ~/.local/share/mesa/mnt/<org>/<repo>
# Run this command with Blaxel's Python sandbox command runner.
agent_cmd = f'cd ~/.local/share/mesa/mnt/{created.org}/{created.name} && claude -p "Implement the feature described in TODO.md"'

# Start Mesa as a background daemon.
MESA_ACCESS_TOKEN="$MESA_ACCESS_TOKEN" mesa mount --daemonize

# Your repos are now at ~/.local/share/mesa/mnt/<org>/<repo>
cd ~/.local/share/mesa/mnt/my-org/agent-workspace
claude -p "Implement the feature described in TODO.md"

An access token is minted once with a fixed TTL and is never refreshed: there is no background rotation and no access-token replacement. Tokens default to a 15 minute TTL and max out at 4 hours, so mint one 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 private key lives only outside the sandbox) and remount inside the sandbox with the new token in MESA_ACCESS_TOKEN.

Tips

Use scoped, short-lived access tokens. Sign a dedicated token for each sandbox session with only the scopes it needs — it’s signed locally with your private key (which never enters the sandbox) and expires on its own. See Authentication 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.
Alpine works out of the box. The install script handles Alpine natively, so the default Blaxel image works without workarounds. Use a custom Debian template only if you have other reasons to prefer Debian.

Getting Started

Concepts

Reference

MesaFS

Usage Patterns

Integrations

Alpine-based setup (default image)

Debian-based setup (custom template)

Mount Mesa

Tips

​Alpine-based setup (default image)

​Debian-based setup (custom template)

​Mount Mesa

​Tips

Alpine-based setup (default image)

Debian-based setup (custom template)

Mount Mesa

Tips