Layouts

A layout composes a mount’s namespace from your repositories: each repository appears at a path you declare, including nested inside another repository’s tree. A layout replaces the default organization browse tree entirely — the mount contains exactly the paths the layout declares, and the canonical /<org>/<repo> paths are not present. Layouts work with both the app mount and the POSIX mount (mesa mount --layout).

Mounting a layout from the SDK

Declare each repository with repo(...) and map absolute paths to declarations. This example mounts an application repository at /workspace with two read-only skills repositories nested inside its tree:

import { Mesa, repo } from "@mesadev/sdk";

const mesa = new Mesa({ apiKey: process.env.MESA_API_KEY });

const fs = await mesa.fs.mount({
  layout: {
    "/workspace": repo("my-app", {
      mode: "rw",
      bookmark: "main",
      subPaths: {
        ".agents/skills": [
          repo("code-review-skill", { mode: "ro", alias: "code-review" }),
          repo("release-notes-skill", { mode: "ro", alias: "release-notes" }),
        ],
      },
    }),
  },
});

// The mount contains exactly what the layout declares
await fs.readdir("/"); // ["workspace"]
await fs.readFile("/workspace/.agents/skills/code-review/SKILL.md");

import os
from mesa_sdk import Mesa, repo

mesa = Mesa(api_key=os.environ["MESA_API_KEY"])

async with mesa.fs.mount(
    layout={
        "/workspace": repo(
            "my-app",
            mode="rw",
            bookmark="main",
            sub_paths={
                ".agents/skills": [
                    repo("code-review-skill", mode="ro", alias="code-review"),
                    repo("release-notes-skill", mode="ro", alias="release-notes"),
                ],
            },
        ),
    },
) as fs:
    # The mount contains exactly what the layout declares
    await fs.readdir("/")  # ["workspace"]
    await fs.read("/workspace/.agents/skills/code-review/SKILL.md")

mode is required on every declaration and has no default: "rw" allows writes, "ro" rejects them with EROFS. The mount mints a least-privilege access token scoped by name to exactly the layout’s repositories — read-only when every declaration is "ro".

mount accepts either a raw path map (as above) or a prepared layout from mesa.fs.createLayout(paths) (TypeScript) / mesa.fs.create_layout(paths) (Python). Either way the declarations are checked as they are built — an empty name, a missing mode, a conflicting revision, or a non-absolute path fails where the layout is defined, and the remaining structural rules are enforced before anything mounts.

The layout file

A layout serializes to JSON — the format mesa mount --layout reads. The document is a pure path map: every top-level key is an absolute mount path, and each value is one repository declaration or an array of them. The file never names an organization; the mount that consumes it supplies one (see Organization resolution).

layout.json

{
  "/workspace": {
    "kind": "repo",
    "name": "my-app",
    "mode": "rw",
    "bookmark": "main",
    "subPaths": {
      ".agents/skills": [
        { "kind": "repo", "name": "code-review-skill", "mode": "ro", "alias": "code-review" },
        { "kind": "repo", "name": "release-notes-skill", "mode": "ro", "alias": "release-notes" }
      ]
    }
  }
}

The SDK produces exactly this form: layout.toString() in TypeScript, str(layout) in Python. A path’s value is one declaration or an array, and the two mean different things:

Single declaration — the repository’s contents appear directly at the path (/workspace/README.md is my-app’s README.md).
Array — each repository appears in its own child directory under the path, named after the repository; alias overrides the directory name.

Declaration fields

Field	Required	Description
`kind`	Yes	Always `"repo"`.
`name`	Yes	Repository name, resolved within the mount’s organization.
`mode`	Yes	`"rw"` or `"ro"`. Read-only repositories reject writes with `EROFS`.
`bookmark`	No	Bookmark to check out. Mutually exclusive with `changeId`.
`changeId`	No	Change ID to check out. Mutually exclusive with `bookmark`.
`alias`	No	Directory-name override. Only valid on array elements.
`subPaths`	No	Map of relative path to declaration(s), mounted beneath this repository’s path.

When neither bookmark nor changeId is set, the mount checks out the repository’s default bookmark. Structural rules:

Top-level keys must be absolute (/-prefixed); subPaths keys must be relative.
/ itself cannot be a mount path.
Path components cannot be . or ...
A repository can appear only once per layout.
Two declarations cannot expand to the same path.

Mounting a layout with the CLI

Pass the file to mesa mount:

MESA_ORG=my-org MESA_API_KEY=mesa_... mesa mount --layout=layout.json --daemonize

Layout paths appear under the mount root: with the file above, the workspace is at ~/.local/share/mesa/mnt/workspace. The file is validated while arguments are parsed — a missing file, invalid JSON, or a rule violation fails immediately, before any mount work.

Organization resolution

The layout file never names an organization, so the mount needs exactly one from its context:

The SDK resolves every repository name within the client’s organization.
The CLI uses the organization MESA_ORG selects; without MESA_ORG, its single configured organization.

If the CLI has no organization configured, or several are configured (for example via MESA_ORGS) and MESA_ORG does not select one, the mount fails with an error pointing at MESA_ORG. Every repository in the layout must belong to that one organization; cross-org layouts are not supported.

Running the mount elsewhere

A common shape: your backend composes the layout and holds the API key, while the mount runs in a sandbox that should only ever see a scoped, short-lived credential. mesa.fs.define bundles a layout with the operations that flow needs — the layout itself serializes to layout.json, and getToken() / get_token() mints the layout’s least-privilege access token.

const definition = await mesa.fs.define({
  "/workspace": repo("my-app", { mode: "rw", bookmark: "main" }),
});

// In your backend: mint the layout-scoped token
const { token } = await definition.getToken({ ttl: 3600 });

// In the sandbox: write the layout file and mount with the token
sandbox.writeFile("layout.json", definition.layout.toString());
sandbox.exec("mesa mount --layout=layout.json --daemonize", {
  env: { MESA_ORG: "my-org", MESA_ACCESS_TOKEN: token },
});

definition = await mesa.fs.define(
    {"/workspace": repo("my-app", mode="rw", bookmark="main")}
)

# In your backend: mint the layout-scoped token
token = (await definition.get_token(ttl=3600)).token

# In the sandbox: write the layout file and mount with the token
sandbox.write_file("layout.json", str(definition.layout))
sandbox.exec(
    "mesa mount --layout=layout.json --daemonize",
    env={"MESA_ORG": "my-org", "MESA_ACCESS_TOKEN": token},
)

The same definition also mounts in-process: await definition.mount() in TypeScript, async with definition.mount() as fs: in Python. To mint a token without a definition, call mesa.fs.createToken(layout, { ttl }) / mesa.fs.create_token(layout, ttl=...) directly. The token helpers validate the layout against the structural rules above before minting, so a structurally invalid layout fails at token time with the same error the mount would report. Repository names are not resolved until mount time — a layout naming a nonexistent repository still mints a token and fails when the mount resolves it.

In the sandbox environment, set only MESA_ORG and MESA_ACCESS_TOKEN, and leave both MESA_API_KEY and MESA_ORGS unset. Each outranks MESA_ACCESS_TOKEN as a credential, so a leftover value would silently replace the scoped token you minted.

ttl is the token lifetime in seconds. API-key clients default to one hour and allow up to 24 hours; TypeScript private-key clients default to 15 minutes and allow up to four hours. There is no refresh — once the token expires, the mount stops authenticating.

Repository boundaries

Nesting changes where repositories appear, not how they behave. Each declaration stays its own repository with its own history, and the deepest mount owns each subtree:

Writes route to the repository that owns the path: a write under a nested mount lands in the nested repository, never in the repository it sits inside.
Renames cannot cross repositories — rename across a boundary returns EXDEV. Tools like mv fall back to copy-and-delete, which writes to both repositories.
The directory at a nested mount’s path cannot itself be renamed or removed.
mode is enforced per repository: a read-write repository can nest read-only ones, and only the read-only subtrees reject writes with EROFS.
Intermediate directories a layout introduces (for example /tools/internal on the way to /tools/internal/cli) are read-only scaffolding.

For the full list of mesa mount flags, see the CLI reference.

Getting Started

Concepts

MesaFS

Usage Patterns

Integrations

Mounting a layout from the SDK

The layout file

Declaration fields

Mounting a layout with the CLI

Organization resolution

Running the mount elsewhere

Repository boundaries

​Mounting a layout from the SDK

​The layout file

​Declaration fields

​Mounting a layout with the CLI

​Organization resolution

​Running the mount elsewhere

​Repository boundaries

Mounting a layout from the SDK

The layout file

Declaration fields

Mounting a layout with the CLI

Organization resolution

Running the mount elsewhere

Repository boundaries