Skip to main content
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:
  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 it 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 OS-level Virtualization.

​
Alpine-based setup (default image)

Blaxel’s default image is Alpine-based. The Mesa CLI is distributed as a .deb package, so on Alpine you need to extract it manually using dpkg-deb: 
import { SandboxInstance } from "@blaxel/core";

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

// Install system dependencies.
// 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 dpkg fuse3",
  waitForCompletion: true,
});

// Download the .deb and extract the binary directly (no apt needed).
// Pin to a specific version; update when upgrading Mesa.
await sandbox.process.exec({
  command: [
    'curl -fsSL "https://packages.buildkite.com/mesa-dot-dev/debian-public/any/pool/any/main/m/mesa/mesa_0.20.0_amd64.deb" -o /tmp/mesa.deb',
    "dpkg-deb -x /tmp/mesa.deb /",
    "rm -f /tmp/mesa.deb",
  ].join(" && "),
  waitForCompletion: true,
});

​
Debian-based setup (custom template)

For a cleaner setup, you can build a custom Debian-based Blaxel template that uses the standard Mesa install script. 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",
});

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

// Start Mesa as a background daemon.
// MESA_ORGS configures the org and API key in one step.
await sandbox.process.exec({
  command: `MESA_ORGS=my-org:${ephemeralKey.key} 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/my-repo \
    && claude "Implement the feature described in TODO.md"',
  waitForCompletion: true,
});

​
Tips

  • Use scoped, short-lived API keys. Create a dedicated API key for each sandbox session with only the scopes it needs. See Auth and 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.
  • Prefer the Debian-based template for production use — it avoids the Alpine workarounds and uses the standard install path.