Skip to main content
In this quickstart, you will create a repo, use our virtual filesystem, and experiment with versioning. The goal is to show the primitives Mesa provides that can be used for any of your agent workflows.
1

Sign up and create an API key

  1. Create an account at app.mesa.dev.
  2. Create an organization for your product (example: acme).
  3. Generate an API key with admin scope.
Store the key as an environment variable:
export MESA_API_KEY="mesa_..."
API keys are only shown once. Save them in your secrets manager before leaving the dashboard.
See Auth & Permissions for key management and scope details.
2

Install the TypeScript SDK

npm install @mesadev/sdk
3

Create a repo

In Mesa a repository is a directory with its own version history and access controls. It’s common to create a repo for each distinct project in a customer’s workspace.
import { Mesa } from "@mesadev/sdk";

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

const repo = await mesa.repos.create({ name: "test-repo" });
To retrieve an existing repo later:
const repo = await mesa.repos.get({ repo: "test-repo" });
4

Create your first change

Once created, you can interact with repositories in a number of ways. The simplest way is to use the change API to programmatically edit repository contents.
import { Mesa } from "@mesadev/sdk";

const mesa = new Mesa({ apiKey: process.env.MESA_API_KEY });
const repo = await mesa.repos.get({ repo: "test-repo" });

const change = await mesa.changes.create({
  repo: repo.name,
  base_change_id: repo.head_change_id!,
  message: "init",
  author: { name: "UI Agent", email: "agent@acme.dev" },
  files: [
    {
      path: "README.md",
      action: "upsert",
      content: Buffer.from("Hello, world!").toString("base64"),
      encoding: "base64",
    },
  ],
});

const fileContent = await mesa.content.get({
  repo: repo.name,
  change_id: change.id,
  path: "README.md",
})

await mesa.bookmarks.move({
  repo: repo.name,
  bookmark: "main",
  change_id: change.id,
})
5

Use Mesa in a sandbox

Programmatic commits are useful but the most powerful way to use Mesa is using our virtual filesystem within a sandbox.
import { Daytona } from '@daytonaio/sdk'
import { Mesa } from "@mesadev/sdk";

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

const repo = await mesa.repos.create({ name: "test-repo" });

// Create a scoped, short-lived API key for the sandbox
const ephemeralKey = await mesa.apiKeys.create({
  name: "sandbox-session",
  scopes: ["read", "write"],
  expires_in_seconds: 3600, // 1 hour
});

// Create a sandbox
const sandbox = await daytona.create()

// Install the Mesa CLI
await sandbox.process.executeCommand(
  "curl -fsSL https://mesa.dev/install.sh | sh"
);

// Write the Mesa config file
const mesaConfig = `
mount-point = "/home/daytona/mesa/mnt"

[organizations.my-org]
api-key = "${ephemeralKey.key}"
`.trim();

await sandbox.fs.uploadFile(
  Buffer.from(mesaConfig),
  "/home/daytona/.config/mesa/config.toml"
);

// Mount a Mesa filesystem in the sandbox
await sandbox.process.executeCommand('mesa mount --daemonize');
Now any agent in the sandbox can access your repo automatically at ~/mesa/mnt/<org_slug>/test-repo in your sandbox. Any edits within that directory are automatically persisted and you can control the versioning through the SDK.
await sandbox.process.executeCommand("claude 'Edit the README.md file to say Hello, world!'", "~/mesa/mnt/acme/test-repo")
6

Checkpoint your work

You can create changes to checkpoint your work within the virtual filesystem.
// Create a new change from the current bookmark HEAD
const change = await fs.change.new({ repo: "test-repo", bookmark: "main" });
console.log("Change ID:", change.changeOid);
7

Create a bookmark for experimental changes

You can create bookmarks to isolate changes before moving them back to main.
import { Mesa } from "@mesadev/sdk";

const mesa = new Mesa({ apiKey: process.env.MESA_API_KEY });
const repo = await mesa.repos.get({ repo: "test-repo" });

// Create a bookmark outside the sandbox
await mesa.bookmarks.create({
  repo: repo.name,
  name: "my-feature",
  change_id: repo.head_change_id!,
});

// Switch to the new bookmark in the virtual filesystem
await fs.change.edit({ repo: repo.name, bookmark: "my-feature" });
8
You’re now ready to start building complex agent workflows with Mesa.

​
Next steps