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, sign a short-lived access token, and orchestrate your workflow.
  2. 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.
  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 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,
});

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

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

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