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, and orchestrate your workflow.
Inside the sandbox — install the mesa CLI, configure it with a short-lived access token, and run mesa mount --daemonize 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.

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 -- --yes",
  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 -- --yes"

# 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 -- --yes

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 -- -y \
    && 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 } from "@mesadev/sdk";

const mesa = new Mesa({ apiKey: process.env.MESA_API_KEY });

// 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.
const { token } = await mesa.tokens.create({
  scopes: ["read", "write"],
  repos: ["my-org/agent-workspace"],
  ttl_seconds: 3600, // 1 hour
});

// Start Mesa as a background daemon.
// MESA_ORG configures the org; MESA_API_KEY supplies the credential for this
// process. We pass the short-lived token we minted above, not the raw API key,
// so your long-lived API key never enters the sandbox.
await sandbox.process.exec({
  command: `MESA_ORG=my-org MESA_API_KEY=${token} mesa mount -d -y`,
  waitForCompletion: true,
});

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

import os
from mesa_sdk import Mesa

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 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.
minted = await mesa.tokens.create(
    scopes=["read", "write"],
    repos=["my-org/agent-workspace"],
    ttl_seconds=3600,  # 1 hour
)

# Start Mesa as a background daemon.
# MESA_ORG configures the org; MESA_API_KEY supplies the credential for this
# process. We pass the short-lived token we minted above, not the raw API key,
# so your long-lived API key never enters the sandbox.
# Run this command with Blaxel's Python sandbox command runner.
mount_cmd = f"MESA_ORG=my-org MESA_API_KEY={minted.token} mesa mount -d -y"

# Your repos are now at ~/.local/share/mesa/mnt/<org>/<repo>
# Run these commands with Blaxel's Python sandbox command runner.
agent_cmd = 'cd ~/.local/share/mesa/mnt/my-org/agent-workspace && claude "Implement the feature described in TODO.md"'

# Start Mesa as a background daemon.
# MESA_ORG configures the org; MESA_API_KEY supplies credentials for this process.
MESA_ORG="my-org" MESA_API_KEY="$MESA_API_KEY" mesa mount -d -y

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

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 from your API 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

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