> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Blaxel

> Use Mesa with Blaxel sandboxes for secure agent workflows.

[Blaxel](https://blaxel.ai/) 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](/content/mesafs/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:

<CodeGroup>
  ```typescript TypeScript theme={null}
  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,
  });
  ```

  ```python Python theme={null}
  # 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"
  ```

  ```bash CLI theme={null}
  # 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
  ```
</CodeGroup>

## Debian-based setup (custom template)

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

```dockerfile theme={null}
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:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const sandbox = await SandboxInstance.create({
    image: "your-template:latest",
    region: "us-pdx-1",
  });
  ```

  ```python Python theme={null}
  # Use the same image and region with Blaxel's Python SDK.
  sandbox_options = {
      "image": "your-template:latest",
      "region": "us-pdx-1",
  }
  ```
</CodeGroup>

## Mount Mesa

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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,
  });
  ```

  ```python Python theme={null}
  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"'
  ```

  ```bash CLI theme={null}
  # 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"
  ```
</CodeGroup>

## 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](/content/concepts/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.