> ## 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 with your private key, and orchestrate your workflow.
2. **Inside the sandbox** — install the `mesa` CLI and run `mesa mount --daemonize` with the token in `MESA_ACCESS_TOKEN`.
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](https://docs.mesa.dev/content/mesafs/posix-mount.md).

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

```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 -- --version 0.46.0",
  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 -- --version 0.46.0"
```

```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 -- --version 0.46.0
```

> [!NOTE]
>
> The layout scopes the token: it can reach the repositories the layout declares
> and nothing else. A plain `mesa mount` then shows exactly those repositories
> under the organization browse tree. To mount the layout's own paths instead,
> serialize `workspace.layout()` with `JSON.stringify(...)` in TypeScript or
> `json.dumps(...)` in Python, write it into the sandbox, and mount with
> `mesa mount --layout <file>`.

## 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 -- --version 0.46.0 \
    && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["/usr/local/bin/sandbox-api"]
```

Deploy with `bl deploy`, then reference your template when creating sandboxes:

```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",
}
```

## Mount Mesa

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

```typescript TypeScript theme={null}
import { Mesa, repo } from "@mesadev/sdk";

const mesa = new Mesa({ privateKey: process.env.MESA_PRIVATE_KEY });

// Create a repo (or use an existing one)
const created = await mesa.repos.create({ name: "agent-workspace" });

// Sign a scoped, self-expiring access token for the sandbox. Signed locally
// with your private key, no network call. The private key never enters
// the sandbox.
const workspace = mesa.fs({
  layout: { "/workspace": repo(created.name, { mode: "rw" }) },
  authors: [{ name: "Sandbox Agent", email: "agent@example.com" }],
  ttl: 60 * 60, // 1 hour, max 4 hours
});
const { token } = await workspace.token();

// Start Mesa as a background daemon with the short-lived token.
await sandbox.process.exec({
  command: `MESA_ACCESS_TOKEN=${token} mesa mount --daemonize`,
  waitForCompletion: true,
});

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

```python Python theme={null}
import os
from mesa_sdk import Mesa, repo

mesa = Mesa(private_key=os.environ["MESA_PRIVATE_KEY"])

# Create a repo (or use an existing one)
created = await mesa.repos.create(name="agent-workspace")

# Sign a scoped, self-expiring access token for the sandbox. Signed locally
# with your private key, no network call. The private key never enters
# the sandbox.
workspace = mesa.fs(
    layout={"/workspace": repo(created.name, mode="rw")},
    authors=[{"name": "Sandbox Agent", "email": "agent@example.com"}],
    ttl=60 * 60,  # 1 hour, max 4 hours
)
minted = await workspace.token()

# Start Mesa as a background daemon with the short-lived token.
# Run this command with Blaxel's Python sandbox command runner.
mount_cmd = f"MESA_ACCESS_TOKEN={minted.token} mesa mount --daemonize"

# Your repos are now at ~/.local/share/mesa/mnt/<org>/<repo>
# Run this command with Blaxel's Python sandbox command runner.
agent_cmd = f'cd ~/.local/share/mesa/mnt/{created.org}/{created.name} && claude -p "Implement the feature described in TODO.md"'
```

```bash CLI theme={null}
# Start Mesa as a background daemon.
MESA_ACCESS_TOKEN="$MESA_ACCESS_TOKEN" mesa mount --daemonize

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

> [!WARNING]
>
> An access token is minted once with a fixed TTL and is never refreshed: there is no
> background rotation and no access-token replacement. Tokens default to a 15 minute TTL and max out at 4 hours, so
> mint one whose TTL covers the whole agent session. After it expires, filesystem operations in the sandbox fail
> with authentication errors. To continue past expiry, mint a fresh token on the host (the private key lives only
> outside the sandbox) and remount inside the sandbox with the new token in `MESA_ACCESS_TOKEN`.

## 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 with your private key (which never enters the sandbox) and expires on its own. See [Authentication](https://docs.mesa.dev/content/concepts/authentication.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.