For agents

Working in a Leeway drive

Leeway is a drive. Your agent reaches it three ways, and they are all the same API. Every plan has it, and we never count or charge for an agent.

Start with leeway info --json. It says which drive this is, who you are, what you may do, and what the server can do.

{ "mcpServers": { "leeway": { "command": "leeway", "args": ["mcp"] } } }

Getting the drive onto the machine your agent runs on

• On a Mac, open the Leeway menu and choose Set Up for Your Agent…. It adds Leeway’s MCP server to Claude Code, Codex or Cursor in one click and keeps a copy of the file it changed.
• On a Linux box (the early headless client, amd64 and arm64): paste the same install line, sign in with a code approved at leeway.to/activate with your passkey, or from any signed-in Mac, and keep the drive attached across reboots. Agents then reach the drive at ~/Leeway and through leeway mcp, the same MCP server the Mac ships.
• On Windows (early): in PowerShell, irm https://leeway.to/install.ps1 | iex, then leeway login and leeway install; the drive is a drive letter in Explorer and agents reach it there. WinFsp is needed once (the installer says which build).
• In Claude, with no computer at all: add a connector with the address https://leeway.to/mcp. Leeway asks you to sign in with your passkey and give Claude leeway; from then on Claude has the same tools on the same drive, and its changes carry its name in history.

curl -fsSL https://leeway.to/install | sh
sudo apt-get install -y nfs-common fuse3           # the drive's packages; the line above says which you need
~/.local/bin/leeway login      # shows a code; approve it at leeway.to/activate (passkey) or from a signed-in Mac
~/.local/bin/leeway install    # attaches the drive now and after reboots
~/.local/bin/leeway mcp        # the MCP server, for the client config above

On a box, leeway signs in, attaches the drive and serves agents, and it has the same verbs as the Mac: every leeway VERB … --json line in the recipes below runs there as written, with no Mac needed once the drive is attached. An agent can also use the MCP server above or the HTTP API directly: leeway agent prints the address and token. Releases land on their own while the drive is attached.

A box checks in every few hours like a Mac does: versions and what worked or didn’t, never your files. leeway telemetry off turns it off.

Leeway in Claude

Claude can work in your drive with no computer at all: on claude.ai, in the Claude apps on your phone and desktop, and in Claude Code.

1. Connect. In Claude, open Settings, then Connectors, and add Leeway from Claude’s directory of connectors, or add a custom connector with the address https://leeway.to/mcp.
2. Sign in and choose. Leeway asks for your passkey (or makes you a free drive on the spot), then which drive Claude may use, or one folder in it, and what it may do there.
3. Ask. Claude now has Leeway’s tools on that drive or folder, and every change it makes carries its name, such as “Claude on Mac”, in the drive’s history.

A new drive starts empty, so start by putting something in it. Try: “Write a summary of this conversation to /Notes/summary.md.” “Add a line to it, then show me its earlier version and put that back.” “List what’s in my Leeway drive.” “Read /Notes/plan.md and tell me what’s left to do.” “Fork /Site into a workspace, rewrite the headline in index.html, show me the diff, then publish it.” “What did I delete this week? Bring back the brief.”

What Claude can do

Each tool tells Claude whether it only reads, and whether it can replace or remove something, so Claude can check with you before the ones that can. A write keeps the earlier version, a delete goes to the trash for 30 days, and restore brings either back.

Limits

• Claude sees only the drive or folder you chose, with the permissions you chose. Paths start at /, the top of what it may see.
• read_file returns up to 64 KiB a call and says which range to read next. A single write_file through Claude carries up to about 4 MB of text.
• * These four hand out links to storage that the client fetches or sends to itself over HTTP. Claude Code can, so it has them; Claude on the web, desktop and phone can’t, so Leeway doesn’t offer them there. There, read_file reads any file 64 KiB at a time, and write_file writes a file of up to about 4 MB.
• A call waits at most 30 seconds; longer work comes back as an operation that get_operation waits on.
• The first call after a quiet spell can take a few seconds.

Disconnecting, and your data

Remove Claude at leeway.to/activate?people and its access ends at once. Leeway never sees your conversation: only the tool calls Claude makes, answered in your drive. Privacy has the details, and support answers questions.

Leeway in Codex

In Codex, the command line and the desktop app, Leeway is a plugin. It brings the same tools on the same drive, and skills that teach Codex how to work there:

• Save without overwriting anyone’s change.
• Find what’s there.
• Undo from history.
• Make bigger changes in a workspace, then publish.
• Leave a hand-off note for whoever comes next.

codex plugin marketplace add supersethvos/leeway-codex
codex plugin add leeway@leeway

1. Sign in and choose. Run codex mcp login leeway, or choose Connect on the Leeway plugin in the Codex app. Leeway asks for your passkey (or makes you a free drive on the spot), then which drive Codex may use, or one folder in it, and what it may do there.
2. Ask. Try: “Save a short summary of this session to /Notes/summary.md in my Leeway drive.” Every change Codex makes carries its name, such as “Codex on Mac”, in the drive’s history.

Codex can also send its own HTTP requests, so it gets the four tools for big files that Claude’s apps don’t. Codex’s default sandbox keeps commands offline, though, and those four need to go online. So for a big file Codex asks you first, or reads and writes it in pieces. The plugin’s source is at github.com/supersethvos/leeway-codex. Remove Codex at leeway.to/activate?people and its access ends at once.

How the drive works

• Paths start at /, the top of what you may see. A token made for /Projects/app sees that folder as / and cannot learn about anything outside it. On the Mac, a path inside the mounted drive works too.
• Every file has a rev that changes when its contents change. Send it back with --if-match and your write fails with CONFLICT instead of overwriting someone else’s change.
• Saved, then durable. A write answers once the drive has it, and everyone reading the drive sees it. It is durable once its bytes are in Leeway’s storage, safe from this Mac failing. leeway sync PATH or put --durable waits for that.
• Workspaces are forks of a folder that cost no extra data. Edit under /.workspaces/<id>/, look at workspace diff, then workspace publish. Publishing never overwrites a live change: both versions are kept.
• History. Overwritten files keep earlier versions; deleted files and folders go to the trash. versions, deleted and restore bring them back.
• Kept on hand. pin PATH keeps a file or folder on this Mac; pins shows progress. Only ready means it is all here.
• Long work waits up to --wait (90 seconds by default; MCP calls at most 30). If it is not done you get an operation, and leeway operation ID keeps waiting. The work continues either way.
• Retries. Send --idempotency-key K on a write and a retry with the same key returns the first answer instead of doing the work twice.

Five recipes

1. Read, change, write back without losing anyone’s edit

rev=$(leeway stat /notes.md --json | jq -r .rev)
leeway cat /notes.md > notes.md            # edit notes.md
leeway put /notes.md notes.md --if-match "$rev" --json
# CONFLICT (exit 75): someone changed it. Read it again, merge,
# retry with error.details.current_rev.

Create-only: put --if-none-match fails with ALREADY_EXISTS if something is there.

2. Work in a workspace, then publish

ws=$(leeway workspace create /Projects/app --json | jq -r .id)
leeway put /.workspaces/$ws/src/main.py main.py --json
leeway workspace diff $ws --json            # conflict:true = also changed live
leeway workspace publish $ws --dry-run --json
leeway workspace publish $ws --json          # conflicts[] lists what was kept beside

--on-conflict fail publishes nothing when anything conflicts. Publishing again is safe. workspace drop throws it away; its files go to the trash.

3. Make sure it is in storage before you report done

leeway sync /Projects/app/build --json       # {"durable":true,...}

4. Follow changes with a cursor

cursor=$(leeway changes --json | jq -r .cursor)    # "now"
leeway changes --since "$cursor" --prefix /Projects --wait 30s --json
# keep the returned cursor for next time; or stream with: leeway watch /Projects

CURSOR_EXPIRED means the cursor can’t be picked up again: list the folder again, then take a fresh cursor.

5. Coordinate with other agents using a lease

lease=$(leeway lease take /Projects/app/plan.md --holder "agent-7" --ttl 120s --json)
token=$(echo "$lease" | jq .fencing_token)
leeway put /Projects/app/plan.md plan.md --fencing-token "$token" --json
leeway lease renew "$(echo "$lease" | jq -r .lease_id)" --ttl 120s --json
leeway lease release "$(echo "$lease" | jq -r .lease_id)" --json

LEASE_HELD tells you who holds it and until when. Writes that carry a fencing token lose to a newer lease, so a stalled agent cannot clobber the next one.

Undo, and access for another agent

leeway rm prints a deleted_id; leeway restore ID brings it back beside anything now in its place. leeway versions PATH then leeway restore --version ID puts an earlier version back, and what it replaces becomes a version itself.

To give another agent a bounded view: leeway token mint --root /Projects/app --scope read --scope write --ttl 24h --json returns the secret once. Hand it over in the environment, never on a command line.

Errors

Every error is {"error":{"code","message","hint","retryable","retry_after_ms","details"},"request_id"}. Read code; hint says what to do next.

Exit 75 with an operation instead of an error means the work is still running.