agentsync (remote)

agentsync-remote

_Part of the xylem stack._

A Cloudflare Worker MCP server that makes claude.ai on your phone a peer in the agentsync coordination mesh — the same claims.json, the same agentsync branch, the same overlap and compare-and-swap rules as local agentsync, with no git and no local clone.

Your laptop's Claude Code (local agentsync) and your phone's claude.ai (agentsync-remote) claim work against the one shared claims.json. Two transports, one mesh. A local peer and this remote peer are indistinguishable in claims.json except by their agent id.

Sibling, not a fork. This is a second *transport* onto the same

coordination file as local agentsync

— not a variant of it. See DESIGN.md for how git push-as-CAS

becomes GitHub-contents-API-as-CAS.

What it gives you

Seven tools over Streamable HTTP MCP:

Deploy your own (one click, no command line)

Self-host this Worker in your own Cloudflare account. Every step is a click path — you never touch a terminal.

1. Click Deploy to Cloudflare

Click the button above. Cloudflare will:

• fork agentsync-remote into your GitHub account,
• create the Worker in your Cloudflare account, and
• connect Workers Builds so future pushes to your fork redeploy automatically.

There are no databases or other resources to provision — this Worker keeps no state of its own (everything lives in your GitHub repo), so the deploy is just the Worker itself.

During the deploy dialog Cloudflare shows the Worker's variables. Set:

Finish the deploy. (If you skipped setting REPO here, you can set it later in the dashboard — see below.)

2. Make a GitHub token, then add the two Worker secrets

The Worker reads two secrets. These are not part of the deploy dialog — you add them once in the dashboard after the first deploy.

First, make the GitHub token (this is the GH_PAT value):

GitHub → Settings → Developer settings → Fine-grained personal access tokens → Generate new token:

• Repository access: *Only select repositories* → pick only your coordination repo (the one you put in REPO).
• Permissions → Repository permissions → Contents: Read and write.
• Nothing else. Generate it and copy the token.

Then add both secrets to the Worker:

Cloudflare dashboard → Workers & Pages → your Worker → Settings → Variables and Secrets → Add → type Secret → add each, then Deploy:

While you're on this screen, confirm the `REPO` variable points at your coordination repo (set it here if you skipped it in the deploy dialog).

Until AUTH_TOKEN is set the Worker answers every request with 404 (it

fails closed). Until GH_PAT is set the tools return a clear error naming the

missing secret. This is by design — an unconfigured endpoint looks like it

doesn't exist.

3. Add the connector in claude.ai

Find your Worker's URL: Workers & Pages → your Worker shows it, in the form https:// . .workers.dev.

claude.ai (web) → Settings → Connectors → Add custom connector. Paste your Worker URL with /mcp/ and your AUTH_TOKEN appended:

https://<your-worker-name>.<your-subdomain>.workers.dev/mcp/<AUTH_TOKEN>

The token in the path *is* the auth — there is no separate login.

4. Test it

Ask Claude: "call survey". You should get the coordination board back (empty claims on a fresh mesh — the Worker bootstraps the branch and file for you, so a brand-new empty repo needs no manual setup).

🔒 Security — the connector URL is a credential

The connector URL embeds your AUTH_TOKEN in the path (…/mcp/ ). Anyone who has that URL can call your Worker and read/write your coordination file. Treat the whole URL like a password:

• Don't paste it into screenshots, issues, chats, or commits.
• Anyone with the URL is a peer in your mesh — share it only with agents/people you trust.
• Rotating the token invalidates old URLs. To revoke access, change AUTH_TOKEN in Settings → Variables and Secrets and redeploy; every old …/mcp/ URL immediately returns 404. Update the connector in claude.ai with the new URL.

GH_PAT is likewise a credential — scope it to *only* your coordination repo with *only* Contents: Read and write, so a leak can't reach anything else.

Why the token is in the URL path, and what that costs you

This is a deliberate design choice, not an oversight. claude.ai custom connectors do not reliably send custom headers, so an Authorization: header — the obvious alternative — cannot be depended on. Putting the credential in the path is what makes the connector work at all.

Be clear about the price, because it is not the same as a header:

• URLs get recorded in places request bodies never do. Browser history, shell history, proxy and CDN access logs, crash reports, bug reports, screenshots, "copy link" buttons, and agent session transcripts. During the audit that produced this section, the connector URLs for these Workers were found in ~54 occurrences across 13 local session transcripts on a single machine — none pasted deliberately; they were simply part of the tool configuration an agent echoed back.
• The Worker itself does not log it. Every log line records the route as /mcp/***. The leak surface is everything *around* the Worker, which is exactly what you cannot audit.
• A leaked token makes the holder a full peer in your mesh — able to claim, force-claim over you, release your claims, and post to the mailbox — with no second factor and no per-caller identity. There is nothing to revoke except the token, and no log that will tell you who used it.

Practical guidance:

1. Rotate on a schedule, not just on suspicion — assume the URL has been recorded somewhere you don't control. Rotation is cheap: change AUTH_TOKEN, update the connector.
2. Rotate immediately if you've shared a terminal recording, a transcript, a screen capture, or a bug report from a machine where the connector is configured.
3. Use a long random token (32+ bytes, e.g. openssl rand -hex 32). The comparison is constant-time in both content *and* length, so length is not observable — but entropy is still your only defence against guessing.
4. If you ever get the chance to use a header or OAuth instead, take it. This tradeoff is forced by the client, not preferred.

Cross-transport walkthrough — two transports, one mesh

This is the whole point. The laptop and the phone coordinate through one file.

On the PC (local agentsync, Claude Code):

> agentsync claim --task "refactor auth" --touches src/auth --branch feature/auth

{"status": "claimed", ...} # writes claims["laptop"] on the agentsync branch

On the phone (claude.ai + agentsync-remote):

You: call survey

Claude: laptop is active — task "refactor auth", touches src/auth, branch feature/auth.

You: claim task "tidy auth helpers", touches src/auth/helpers.ts Claude: blocked. Overlap with an active peer claim: laptop — "refactor auth" — shared_files: ["src/auth/helpers.ts"] Narrow touches, wait, or re-call with force=true.

You: mailbox "Taking src/auth/helpers.ts once you land the refactor — ok?" to "laptop" Claude: posted.

Back on the PC, the desktop agent (or you) reads the note via survey / mailbox, answers it, and releases:

> agentsync mailbox "go for it, helpers are stable now"

agentsync release --note "refactor landed"

{"status": "released"} # laptop's claim -> status "done"

### ⚠️ Known gap: the mailbox is currently WRITE-ONLY across tiers

The "Back on the PC" step above does not work yet. This Worker's

mailbox() writes a top-level notes[] array into claims.json, and the

local Python agentsync server has no concept of `notes` — it exposes no

mailbox tool, and its survey() returns only me, branch, partners

and stale_claims. A note posted from the phone lands in the file correctly

and is simply never surfaced to a desktop peer.

That matters more than a missing feature normally would, because the

repository-level agent instructions tell agents to raise judgment calls

*through this mailbox*. An escape hatch that silently swallows the question

is worse than no escape hatch: the agent believes it has asked and waits, or

proceeds, on a question nobody will ever see.

Until the local side lands, read the mailbox from the remote peer

(mailbox with no message, or survey), or read claims.json on the

coordination branch directly.

The local-side change required (in the Python agentsync package — a

separate repo, deliberately not modified here):

1. Parse and preserve `notes`. The claims-file reader must round-trip the

top-level notes key. Today an unrecognised key risks being dropped on

the next local write, which would *delete* remote peers' notes. Preserving

unknown top-level keys is the minimum safe change and should land first,

independently.

2. Surface notes in `survey()` — add a notes field alongside

partners/stale_claims, defaulting to [].

3. Add a local `mailbox(message=None, to=None)` tool mirroring this one:

append {from, to, message, at} under the same compare-and-swap the local

claim writes already use, and cap retention at the 200 most recent notes

(this Worker evicts oldest-first at that bound — the two sides must agree,

or they will fight over the file).

The on-disk shape is already compatible in both directions: this Worker only

emits notes when non-empty, so a claims.json wi