# Mesa Docs

> A programmable storage layer and virtual filesystem for AI agents.

## Docs

- [Introduction](https://docs.mesa.dev/content/getting-started/introduction.md)
- [Quickstart](https://docs.mesa.dev/content/getting-started/quickstart.md): Create a repository and write your first change.
- [Versioning](https://docs.mesa.dev/content/concepts/versioning.md): Model document history with changes and bookmarks
- [Filesystem](https://docs.mesa.dev/content/concepts/filesystem.md): Understand Mesa's filesystem interface and choose between the POSIX mount and app mount
- [Organizations](https://docs.mesa.dev/content/concepts/organizations.md): Manage organizations and team membership in Mesa.
- [Authentication](https://docs.mesa.dev/content/concepts/authentication.md): Understand Mesa private keys, access tokens, and how commits are attributed.
- [Webhooks](https://docs.mesa.dev/content/concepts/webhooks.md): Programmatically subscribe to events on your organization's repositories.
- [Authentication reference](https://docs.mesa.dev/content/reference/authentication.md): Credential formats, environment variables, token limits, and compatibility behavior.
- [Migrate from API keys](https://docs.mesa.dev/content/getting-started/migrate-from-api-keys.md): Move an existing integration to private keys and short-lived access tokens.
- [Mesa CLI Configuration](https://docs.mesa.dev/content/reference/mesa-cli-configuration.md): Environment variables and options for the Mesa CLI.
- [Limits](https://docs.mesa.dev/content/reference/limits.md): System limits for repositories, files, operations, pagination, and timeouts.
- [POSIX Mount](https://docs.mesa.dev/content/mesafs/posix-mount.md): Expose Mesa repositories as real directories on the host
- [App Mount](https://docs.mesa.dev/content/mesafs/app-mount.md): Run Mesa as an in-process virtual filesystem
- [Layouts](https://docs.mesa.dev/content/mesafs/layouts.md): Mount repositories at the paths you choose
- [Realtime](https://docs.mesa.dev/content/mesafs/advanced/realtime.md): Realtime collaboration in MesaFS
- [Prefetching](https://docs.mesa.dev/content/mesafs/advanced/prefetching.md): How mesa loads your repository in the background to reduce sandbox startup time.
- [.mesaignore](https://docs.mesa.dev/content/mesafs/advanced/mesaignore.md): Control which files mesa keeps locally vs. uploads to VCS.
- [Overview](https://docs.mesa.dev/content/usage-patterns/overview.md): Recommended patterns for using Mesa in agent products.
- [Daytona](https://docs.mesa.dev/content/integrations/sandboxes/daytona.md): Use Mesa with Daytona sandboxes for secure, high-performance agent workflows.
- [E2B](https://docs.mesa.dev/content/integrations/sandboxes/e2b.md): Use Mesa with E2B sandboxes for secure, high-performance agent workflows.
- [Superserve](https://docs.mesa.dev/content/integrations/sandboxes/superserve.md): Use Mesa with Superserve sandboxes for securely running agent harnesses in production.
- [Vercel](https://docs.mesa.dev/content/integrations/sandboxes/vercel.md): Use Mesa with Vercel Sandbox for secure agent workflows.
- [Freestyle](https://docs.mesa.dev/content/integrations/sandboxes/freestyle.md): Use Mesa with Freestyle when your AI needs a whole computer, not just a code runner.
- [Blaxel](https://docs.mesa.dev/content/integrations/sandboxes/blaxel.md): Use Mesa with Blaxel sandboxes for secure agent workflows.
- [Sprites](https://docs.mesa.dev/content/integrations/sandboxes/sprites.md): Use Mesa with Sprites sandboxes for stateful, high-performance agent workflows.
- [Modal](https://docs.mesa.dev/content/integrations/sandboxes/modal.md): Use Mesa with Modal sandboxes.
- [Cloudflare](https://docs.mesa.dev/content/integrations/sandboxes/cloudflare.md): Use Mesa with Cloudflare Workers and containers.
- [GitHub](https://docs.mesa.dev/content/integrations/github/sync.md): Sync repositories between Mesa and GitHub (or any Git server).
- [Overview](https://docs.mesa.dev/content/reference/ts/index.md)
- [tokens.create()](https://docs.mesa.dev/content/reference/ts/tokens-create.md): Sign a short-lived access token locally.
- [whoami()](https://docs.mesa.dev/content/reference/ts/whoami.md): Return the caller's authenticated organization, key metadata, and scopes.
- [org.get()](https://docs.mesa.dev/content/reference/ts/org-get.md): Get metadata for an organization.
- [apiKeys.list()](https://docs.mesa.dev/content/reference/ts/api-keys-list.md): List API keys in an organization.
- [apiKeys.create()](https://docs.mesa.dev/content/reference/ts/api-keys-create.md): Create a scoped Mesa API key.
- [apiKeys.revoke()](https://docs.mesa.dev/content/reference/ts/api-keys-revoke.md): Revoke a Mesa API key by ID.
- [repos.list()](https://docs.mesa.dev/content/reference/ts/repos-list.md): List repositories in an organization.
- [repos.create()](https://docs.mesa.dev/content/reference/ts/repos-create.md): Create a Mesa repository, optionally with a default bookmark or upstream remote.
- [repos.get()](https://docs.mesa.dev/content/reference/ts/repos-get.md): Get a repository by name.
- [repos.update()](https://docs.mesa.dev/content/reference/ts/repos-update.md): Update repository metadata, tags, default bookmark, or upstream remote.
- [repos.delete()](https://docs.mesa.dev/content/reference/ts/repos-delete.md): Delete a repository and its data.
- [mesa.repos.syncUpstream()](https://docs.mesa.dev/content/reference/ts/repos-sync-upstream.md): Sync a repository upstream remote.
- [mesa.repos.getUpstreamSync()](https://docs.mesa.dev/content/reference/ts/repos-get-upstream-sync.md): Get one sync for a repository upstream remote.
- [mesa.repos.listUpstreamSyncs()](https://docs.mesa.dev/content/reference/ts/repos-list-upstream-syncs.md): List syncs for a repository's upstream.
- [content.get()](https://docs.mesa.dev/content/reference/ts/content-get.md): Read a file, symlink, or directory listing from a repository.
- [changes.list()](https://docs.mesa.dev/content/reference/ts/changes-list.md): List changes reachable from a repository bookmark.
- [changes.create()](https://docs.mesa.dev/content/reference/ts/changes-create.md): Create a change on top of an existing base change.
- [changes.get()](https://docs.mesa.dev/content/reference/ts/changes-get.md): Get a change by ID.
- [changes.patch()](https://docs.mesa.dev/content/reference/ts/changes-patch.md): Update a change's metadata, files, or conflict resolutions.
- [diffs.get()](https://docs.mesa.dev/content/reference/ts/diffs-get.md): Compare two changes in a repository.
- [bookmarks.list()](https://docs.mesa.dev/content/reference/ts/bookmarks-list.md): List bookmarks in a repository.
- [bookmarks.create()](https://docs.mesa.dev/content/reference/ts/bookmarks-create.md): Create a bookmark at a change.
- [bookmarks.move()](https://docs.mesa.dev/content/reference/ts/bookmarks-move.md): Move a bookmark to another change.
- [bookmarks.delete()](https://docs.mesa.dev/content/reference/ts/bookmarks-delete.md): Delete a bookmark.
- [bookmarks.merge()](https://docs.mesa.dev/content/reference/ts/bookmarks-merge.md): Merge one bookmark into another.
- [webhookTargets.list()](https://docs.mesa.dev/content/reference/ts/webhook-targets-list.md): List webhook delivery targets.
- [webhookTargets.create()](https://docs.mesa.dev/content/reference/ts/webhook-targets-create.md): Register a webhook delivery target.
- [webhookTargets.update()](https://docs.mesa.dev/content/reference/ts/webhook-targets-update.md): Update a webhook delivery target.
- [webhookTargets.delete()](https://docs.mesa.dev/content/reference/ts/webhook-targets-delete.md): Delete a webhook delivery target.
- [webhooks.on()](https://docs.mesa.dev/content/reference/ts/webhooks-on.md): Register typed local webhook handlers.
- [webhooks.receive()](https://docs.mesa.dev/content/reference/ts/webhooks-receive.md): Verify an incoming webhook request and dispatch registered handlers.
- [mesa.fs()](https://docs.mesa.dev/content/reference/ts/fs-mount.md): Define a layout, mount it as a Mesa virtual filesystem, or mint its token.
- [fs.bash()](https://docs.mesa.dev/content/reference/ts/fs-bash.md): Run shell commands against a mounted Mesa filesystem.
- [fs.change](https://docs.mesa.dev/content/reference/ts/fs-changes.md): Manage active changes inside a mounted Mesa filesystem.
- [fs.bookmark](https://docs.mesa.dev/content/reference/ts/fs-bookmarks.md): Manage bookmarks inside a mounted Mesa filesystem.
- [Overview](https://docs.mesa.dev/content/reference/py/index.md)
- [tokens.create()](https://docs.mesa.dev/content/reference/py/tokens-create.md): Sign a short-lived access token locally.
- [whoami()](https://docs.mesa.dev/content/reference/py/whoami.md): Return the caller's authenticated organization, key metadata, and scopes.
- [org.get()](https://docs.mesa.dev/content/reference/py/org-get.md): Fetch organization metadata.
- [api_keys.list()](https://docs.mesa.dev/content/reference/py/api-keys-list.md): List API keys for an organization.
- [api_keys.create()](https://docs.mesa.dev/content/reference/py/api-keys-create.md): Mint a new Mesa API key.
- [api_keys.revoke()](https://docs.mesa.dev/content/reference/py/api-keys-revoke.md): Revoke an API key by ID.
- [repos.list()](https://docs.mesa.dev/content/reference/py/repos-list.md): List repositories in an organization.
- [repos.create()](https://docs.mesa.dev/content/reference/py/repos-create.md): Create a Mesa repository, optionally with a default bookmark or upstream remote.
- [repos.get()](https://docs.mesa.dev/content/reference/py/repos-get.md): Fetch metadata for one repository.
- [repos.update()](https://docs.mesa.dev/content/reference/py/repos-update.md): Rename a repository, change its default bookmark, or update upstream configuration.
- [repos.delete()](https://docs.mesa.dev/content/reference/py/repos-delete.md): Permanently delete a repository.
- [repos.sync_upstream()](https://docs.mesa.dev/content/reference/py/repos-sync-upstream.md): Enqueue a sync to a repository's configured upstream.
- [repos.get_upstream_sync()](https://docs.mesa.dev/content/reference/py/repos-get-upstream-sync.md): Get one sync for a repository's configured upstream.
- [mesa.repos.list_upstream_syncs()](https://docs.mesa.dev/content/reference/py/repos-list-upstream-syncs.md): List syncs for a repository's upstream.
- [content.get()](https://docs.mesa.dev/content/reference/py/content-get.md): Read a file, symlink, or directory listing from a repository.
- [changes.list()](https://docs.mesa.dev/content/reference/py/changes-list.md): List reachable changes for a repository.
- [changes.create()](https://docs.mesa.dev/content/reference/py/changes-create.md): Create a change on top of an existing base change.
- [changes.get()](https://docs.mesa.dev/content/reference/py/changes-get.md): Fetch a specific change by ID.
- [changes.patch()](https://docs.mesa.dev/content/reference/py/changes-patch.md): Amend metadata, apply file operations, or resolve conflicts on an existing change.
- [diffs.get()](https://docs.mesa.dev/content/reference/py/diffs-get.md): Inspect the diff between two changes.
- [bookmarks.list()](https://docs.mesa.dev/content/reference/py/bookmarks-list.md): List bookmarks in a repository.
- [bookmarks.create()](https://docs.mesa.dev/content/reference/py/bookmarks-create.md): Create a bookmark at an existing change.
- [bookmarks.move()](https://docs.mesa.dev/content/reference/py/bookmarks-move.md): Move a bookmark to a different change.
- [bookmarks.delete()](https://docs.mesa.dev/content/reference/py/bookmarks-delete.md): Delete a bookmark from a repository.
- [bookmarks.merge()](https://docs.mesa.dev/content/reference/py/bookmarks-merge.md): Merge one bookmark into another.
- [webhook_targets.list()](https://docs.mesa.dev/content/reference/py/webhook-targets-list.md): List webhook delivery targets for an organization.
- [webhook_targets.create()](https://docs.mesa.dev/content/reference/py/webhook-targets-create.md): Register a webhook delivery target.
- [webhook_targets.update()](https://docs.mesa.dev/content/reference/py/webhook-targets-update.md): Update a webhook delivery target.
- [webhook_targets.clear_repo_filter()](https://docs.mesa.dev/content/reference/py/webhook-targets-clear-repo-filter.md): Make a webhook target receive events for every repository.
- [webhook_targets.delete()](https://docs.mesa.dev/content/reference/py/webhook-targets-delete.md): Delete a webhook delivery target.
- [mesa.fs()](https://docs.mesa.dev/content/reference/py/fs-mount.md): Define a layout, mount it as a Mesa virtual filesystem, or mint its token.
- [fs.bash()](https://docs.mesa.dev/content/reference/py/fs-bash.md): Run shell commands against a mounted Mesa filesystem.
- [fs.changes](https://docs.mesa.dev/content/reference/py/fs-changes.md): Manage active changes on a mounted Mesa filesystem.
- [fs.bookmarks](https://docs.mesa.dev/content/reference/py/fs-bookmarks.md): Manage bookmarks from a mounted Mesa filesystem.
- [Overview](https://docs.mesa.dev/content/reference/cli-overview.md): Install and get started with the Mesa CLI.
- [Mesa CLI Reference](https://docs.mesa.dev/content/reference/mesa-cli.md): Complete reference for all mesa commands, arguments, and options.
- [Overview](https://docs.mesa.dev/content/api-reference/overview.md): Get started with the Mesa HTTP API.
- [whoami](https://docs.mesa.dev/api-reference/org/get-caller-identity.md): Get the authenticated organization, effective scopes, and API key metadata
- [List API keys](https://docs.mesa.dev/api-reference/org/list-api-keys.md): List all API keys for the organization (key values are not returned)
- [Create API key](https://docs.mesa.dev/api-reference/org/create-api-key.md): Create a new API key for programmatic access
- [Revoke API key](https://docs.mesa.dev/api-reference/org/revoke-api-key.md): Revoke an API key by its ID
- [Update API key tags](https://docs.mesa.dev/api-reference/org/update-api-key-tags.md): Add, update, or remove tags on an API key. Set a tag value to null to remove it.
- [Get organization](https://docs.mesa.dev/api-reference/org/get-organization.md): Get organization metadata and repository counts
- [List webhook targets](https://docs.mesa.dev/api-reference/webhook-target/list-webhook-targets.md): List webhook targets configured for the organization
- [Create webhook target](https://docs.mesa.dev/api-reference/webhook-target/create-webhook-target.md): Create a webhook target for the organization
- [Get webhook target](https://docs.mesa.dev/api-reference/webhook-target/get-webhook-target.md): Get a webhook target by ID
- [Delete webhook target](https://docs.mesa.dev/api-reference/webhook-target/delete-webhook-target.md): Delete a webhook target from the organization
- [Update webhook target](https://docs.mesa.dev/api-reference/webhook-target/update-webhook-target.md): Update a webhook target for the organization. Any provided field replaces its current value; omitted fields are left unchanged. Pass `repo_ids: null` to clear the repo filter and make the target org-wide.
- [List repositories](https://docs.mesa.dev/api-reference/repo/list-repositories.md): List repositories in the organization using cursor pagination
- [Create repository](https://docs.mesa.dev/api-reference/repo/create-repository.md): Create a new repository in the organization
- [List upstream syncs](https://docs.mesa.dev/api-reference/repo/list-upstream-syncs.md): List syncs for the repository upstream, newest first.
- [Sync upstream](https://docs.mesa.dev/api-reference/repo/sync-upstream.md): Enqueue a sync for the repository upstream. Returns the sync, which the worker processes asynchronously. Read `repo.upstream.latest_sync`, fetch `GET /:repo/upstream/syncs/:syncId`, or list `GET /:repo/upstream/syncs` for status.
- [Get upstream sync](https://docs.mesa.dev/api-reference/repo/get-upstream-sync.md): Get one sync for the repository upstream.
- [Get repository](https://docs.mesa.dev/api-reference/repo/get-repository.md): Get metadata for a specific repository
- [Delete repository](https://docs.mesa.dev/api-reference/repo/delete-repository.md): Permanently delete a repository and all its data
- [Update repository](https://docs.mesa.dev/api-reference/repo/update-repository.md): Update repository name, default bookmark, or tags. Tags are patched: omitted keys are unchanged, string values add or update a tag, and null values remove a tag.
- [Bulk update tags](https://docs.mesa.dev/api-reference/repo/bulk-update-tags.md): Bulk set or remove a tag across repositories. This operation is idempotent.
- [Get content](https://docs.mesa.dev/api-reference/content/get-content.md): Get file content or directory listing at a path. Use Accept: application/json for the JSON union response, or Accept: application/octet-stream for raw file bytes. Directory + octet-stream requests return 406 Not Acceptable.
- [List bookmarks](https://docs.mesa.dev/api-reference/bookmark/list-bookmarks.md): List bookmarks in a repository, optionally filtered by a bookmark-name glob
- [Create bookmark](https://docs.mesa.dev/api-reference/bookmark/create-bookmark.md): Create a new bookmark from an existing change id
- [Get bookmark](https://docs.mesa.dev/api-reference/bookmark/get-bookmark.md): Get a single bookmark by name
- [Delete bookmark](https://docs.mesa.dev/api-reference/bookmark/delete-bookmark.md): Delete a bookmark from a repository
- [Move bookmark](https://docs.mesa.dev/api-reference/bookmark/move-bookmark.md): Move an existing bookmark forward to a different change. Backward or sideways moves require allow_backwards.
- [Merge bookmarks](https://docs.mesa.dev/api-reference/bookmark/merge-bookmarks.md): Merge the source bookmark into the target bookmark. The target bookmark is advanced to the merge result.
- [List changes](https://docs.mesa.dev/api-reference/change/list-changes.md): List current reachable changes for a repository bookmark
- [Create change](https://docs.mesa.dev/api-reference/change/create-change.md): Create a new change on top of an existing base change, optionally applying initial file operations. File content must be base64-encoded.
- [Get change](https://docs.mesa.dev/api-reference/change/get-change.md): Retrieve a specific change by its JJ change id
- [Patch change](https://docs.mesa.dev/api-reference/change/patch-change.md): Patch an existing change by updating metadata and/or applying file operations, then snapshot the result into a new change-owned commit. File content must be base64-encoded. When the change is conflicted, `files` writes are refused; submit a `resolutions` array instead to incrementally resolve confli…
- [Get diff](https://docs.mesa.dev/api-reference/change/get-diff.md): Retrieve the diff between two change ids. In the JSON response, conflicted paths are excluded from `entries[]` and surface only in `conflicted_entries[]` (with per-side target/base/source content); the two arrays are mutually exclusive. When the client requests `Accept: text/plain`, the response is…
- [REST API Changelog](https://docs.mesa.dev/content/changelog/rest-api.md): Release history for the REST API.
- [TypeScript SDK Changelog](https://docs.mesa.dev/content/changelog/typescript-sdk.md): Release history for the TypeScript SDK.
- [Python SDK Changelog](https://docs.mesa.dev/content/changelog/python-sdk.md): Release history for the Python SDK.
- [Mesa CLI Changelog](https://docs.mesa.dev/content/changelog/mesa-cli.md): Release history for the Mesa CLI.

## OpenAPI Specs

- [openapi](https://docs.mesa.dev/openapi.json)

## Optional

- [Examples](https://github.com/mesa-dot-dev/examples)