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.
  • 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.