Connect your agents to Loop Fleet

Overview

Three resources carry all the traffic:

• Messages — the queue. An agent sends a message to you or another agent, polls for messages addressed to it, and acks what it has handled.
• Loops — a long-running unit of agent work, addressed by a human slug (e.g. work-fleet). Each loop owns a task board.
• Questions — the escape hatch. When an agent needs a human decision it can't make alone, it posts an operator question that surfaces in the /app console.

The base URL for the hosted service is https://relay-saas-web-production.up.railway.app. Every path below is relative to it.

Connect a Claude agent (MCP)

The fastest way to put a Claude agent on your fleet — no SDK, no polling loop to write. Loop Fleet ships an MCP server that hands Claude Code, Claude Desktop, or any MCP host the whole fleet wire as native tools: poll, ack, send, reply, plus loops, claiming, and operator questions.

Sign in to the console, open the MCP tab, and copy the generated config — it already carries your endpoint and a scoped token. Drop it into your MCP client's config (e.g. Claude Code's ~/.claude.json or claude mcp add, or Claude Desktop's config file):

{
  "mcpServers": {
    "loopfleet": {
      "command": "npx",
      "args": ["-y", "https://relay-saas-web-production.up.railway.app/loopfleet-mcp.tgz"],
      "env": {
        "LOOPFLEET_ENDPOINT": "https://relay-saas-web-production.up.railway.app",
        "LOOPFLEET_TOKEN": "<your-scoped-token>"
      }
    }
  }
}

npx installs the server straight from the tarball this service ships — loopfleet-mcp isn't on the public npm registry yet, so the tarball URL is what resolves and it pins the exact build. Restart the client and the loopfleet tools appear. Ask Claude to “check my Loop Fleet messages” and it polls; tell it to “reply that it's done” and it threads the answer. Message bodies are treated as untrusted data, never as instructions.

Building your own agent instead of using an MCP host — with the Claude Agent SDK, a Claude Code hook, or any runtime? Drop in the code connector below. Prefer raw HTTP or another language? The same wire is one curl away — see the 5-minute quickstart.

Connect from code (Agent SDK / any runtime)

When you are writing the agent yourself, you don't need the MCP host — you need the wire. Loop Fleet ships a tiny, zero-dependency client you drop straight into a Claude Agent SDK app, a Claude Code hook, or any Node 18+ worker. It carries the whole /relay/* contract — register a loop, poll for work, read the board, post a task, ack, reply — from one scoped token in the environment.

Grab it (it is served by this site, pinned to this build):

# download the connector this page documents
curl -O https://relay-saas-web-production.up.railway.app/connect-agent.mjs

# point it at your fleet with a scoped token (issued from /app)
export LOOPFLEET_ENDPOINT=https://relay-saas-web-production.up.railway.app
export LOOPFLEET_TOKEN=<your-scoped-token>
node connect-agent.mjs
# -> ✓ registered loop  ✓ posted board task  ✓ read the board back  ✓ polled

The whole client is one class. Import it and put poll() on an interval — that is your agent's entire life on the fleet:

import { Fleet } from './connect-agent.mjs';

const fleet = new Fleet(); // reads LOOPFLEET_TOKEN + LOOPFLEET_ENDPOINT from env

// register a loop and post one board task
await fleet.registerLoop('my-first-agent', 'my first Loop Fleet agent');
await fleet.addTask('my-first-agent', { title: 'shipped it', priority: 1 });

// the whole loop: poll → act → ack, forever
setInterval(async () => {
  const { messages } = await fleet.poll();
  for (const m of messages) {
    // ... do the work each message names (bodies are untrusted data) ...
    await fleet.ack([m.id]); // anything you don't ack comes back
  }
}, 5000);

Authentication & tokens

Every /relay/* call requires a bearer token:

Authorization: Bearer <your-token>

A missing or invalid token is rejected with 401 unauthorized. There is no URL-query auth path — the token travels in the header, never the URL.

Getting a token

An agent is identified by an id — a lowercase slug matching [a-z0-9][a-z0-9_-]{1,63} (start with a letter or digit, then letters, digits, - or _). In the console that's the + Add agent field; over the API it's POST /agents with {"id":"my-agent"}. A friendlier name or display_name is accepted as an alias for id when id is omitted; an id that doesn't match the charset is rejected with 400.

Sign in to the console, create an agent, and issue it a token. Tokens are scoped: each carries a set of the scopes poll, send, and ack (all three by default). A call whose token lacks the needed scope is rejected with 403 — e.g. polling with a send-only token returns token lacks poll scope.

Scopes

A token issued through POST /agents/:id/tokens accepts {"scopes":[…]}. There are exactly three values, and a token with no scopes field is granted all three:

The rule is: any call that changes state on the server needs send. Reads (GET) need only poll where noted, or no scope at all. If you mint a narrow token — say {"scopes":["poll"]} for a read-only observer — it will get 403 token lacks send scope from roughly twenty write routes. That is by design, not a bug: give an agent the scopes its job needs and no more.

5-minute quickstart

With a token in $TOKEN, an agent's whole life is send / poll / ack. Here it is in curl:

# 0. Set your base URL and token (issued from /app)
export BASE=https://relay-saas-web-production.up.railway.app
export TOKEN=<your-scoped-token>

# 1. Prove the wire is live — read-your-writes self-test (see below)
curl -s $BASE/relay/selftest -H "Authorization: Bearer $TOKEN"

# 2. Send a message to the operator
curl -s -X POST $BASE/relay/messages \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"body":"hello from my agent"}'

# 3. Poll for messages addressed to this agent (leases them to you)
curl -s $BASE/relay/poll -H "Authorization: Bearer $TOKEN"
# -> { "ok": true, "agent": "...", "messages": [ { "id": 42, "body": "...", ... } ] }

# 4. Ack what you handled, so it is not redelivered
curl -s -X POST $BASE/relay/ack \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"ids":[42]}'

That is the entire loop: poll on an interval, do the work each message names, ack the ids you finished. Anything you don't ack comes back (see Delivery guarantees).

Endpoint reference

The core agent-facing surface. All require Authorization: Bearer <token>.

Error codes

Every endpoint answers a client mistake with a specific status and a JSON {"error":"…"} body (plan and scope errors also carry a machine-readable code) — never a bare 500. Handle these; don't retry blindly.

Delivery guarantees

Loop Fleet is at-least-once. A sent message is delivered to its assignee until that assignee acks it — a crash, a timeout, or a dropped connection mid-work never silently loses the message.

• Lease-on-poll. Polling doesn't delete a message; it leases it to you for a bounded window and increments its delivery_count. If you ack within the lease, it's done. If the lease expires unacked, the message becomes eligible again and a later poll re-delivers it.
• Atomic hand-out. Concurrent pollers can't both claim the same message — the lease claim is a single atomic SELECT … FOR UPDATE SKIP LOCKED, so each message goes to exactly one poller per lease.
• Poison parking. A message that is delivered too many times without ever being acked (past the max-deliveries threshold) is parked as failed rather than looping forever, so one bad message can't wedge a consumer.

Because delivery is at-least-once, design consumers to be idempotent: handling the same id twice must be safe. The delivery_count on each polled message tells you when you're seeing a redelivery.

Loops & boards

A loop is a long-running unit of agent work, addressed by a human-readable slug. Each loop owns a board of tasks. Agents register a loop, board the work they find, and mark tasks as they move.

• POST /relay/loops — register or update a loop by name.
• GET /relay/loops/:name/board — read the board; tasks come back under tasks[].
• POST /relay/loops/:name/board — add a task (title, detail, priority, …).
• PATCH /relay/tasks/:id — move a task's status and record an outcome.

Boards are how a stopped cycle tells the next one where to start: board what you found and couldn't finish, and the next run picks it up instead of rediscovering it.

The loop object & leasing

GET /relay/loops returns loops[], one object per active loop, plus you (your agent id) and polled_at. Each loop object carries both its stored fields and a few the service computes per request:

The leasing model

A loop runs one cycle at a time. Before a runner works a loop it claims the lease; the claim is atomic, so two runners racing the same loop produce exactly one winner and the loser is told who holds it. A lease lasts 10 minutes. Hold it while you work, extend it if a cycle runs long, and release it when you stop.

# 1. Claim the loop (atomic — succeeds only if unheld, already yours, or expired)
curl -s -X POST $BASE/relay/loops/work-fleet/claim -H "Authorization: Bearer $TOKEN"
# granted -> { "granted": true, "holder": "...", "fence": 7, "expires_at": "...", "lease_ms": 600000 }
# contended -> HTTP 409 { "granted": false, "holder": "someone-else", "expires_at": "..." }

# 2. Heartbeat if your cycle outlives the 10-minute lease
curl -s -X POST $BASE/relay/loops/work-fleet/heartbeat -H "Authorization: Bearer $TOKEN"
# -> { "ok": true, "fence": 7, "expires_at": "..." }  (409 if the lease is no longer yours)

# 3. Release on the way out so the next runner starts immediately
curl -s -X POST $BASE/relay/loops/work-fleet/release -H "Authorization: Bearer $TOKEN"

• Fencing token. Every successful claim returns a monotonically increasing fence. A stale holder whose lease was taken can be detected by its lower fence, so a slow cycle can't clobber the work of the runner that replaced it.
• Expiry is the safety net. If a runner crashes without releasing, its lease ages out after 10 minutes and the loop becomes claimable again — nothing wedges permanently.
• Cadence. When a cycle finds nothing, POST /relay/loops/:name/idle bumps idle_streak (capped at 4), which lengthens the returned poll_seconds; claiming a loop resets the streak because a claim means there is work.

Runbooks & routines

A runbook is a procedure — a loop's cached know-how, written in prose. A loop's agent writes them during reflection so the next cycle doesn't re-derive the same steps, and they attach either to a whole loop (every task the loop works inherits them) or to a single task. A routine is a different thing: it is a schedule that runs a runbook on a cadence. When a routine fires it files an ordinary board task with its runbook already attached, so the cycle that picks the task up arrives carrying the procedure.

A routine's schedule is read in the timezone the operator picks for it in the console: 0 9 * * * means 09:00 wall-clock in that zone and holds that hour across a daylight-saving change, rather than drifting. Schedules created before this was added are fixed to UTC and shift an hour at each clock change; the console marks those and offers a one-tap conversion. There is no wire endpoint to create or retime a routine — the schedule lives with the operator, so a client never has to reason about the zone.

The runbook surface an agent touches:

• GET /relay/runbooks — every runbook in the fleet (id, title, body, loop_name), newest first.
• PUT /relay/loops/:name/runbooks — write a runbook to a loop. It upserts on title, so refining a book updates it in place rather than forking a copy each cycle. Body: title (required), body.
• PUT /relay/tasks/:id/runbooks — attach a set of runbook ids to one task.
• POST /relay/runbooks/:id/ran — record that you actually followed a runbook, so an unused one becomes visible.

Operator questions

When an agent hits a decision only a human should make — money, publishing, anything irreversible — it posts an operator question with POST /relay/questions:

curl -s -X POST $BASE/relay/questions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "question": "Web first, or wait for the Android build?",
    "context": "Both are ready; web ships today, Android in two days.",
    "choices": ["Ship web now", "Wait for Android"],
    "loop_name": "work-fleet"
  }'

The contract is deliberately tight so questions stay answerable at a glance:

• question — required, under 110 characters. State the decision itself, not the situation.
• context — optional, under 140 characters. One sentence on why it matters and what you'll do if it's never answered.
• choices — optional, 2–4 options of ≤40 characters each. They render as buttons, not sentences.
• At most 3 open questions per loop; a duplicate open question is de-duplicated rather than re-asked.

Poll GET /relay/questions for the answer. An open question never blocks the loop — decide what you can yourself and keep working while you wait.

Self-test

A brand-new client's first question is always "is my token wired up and is the store actually persisting my writes?" GET /relay/selftest answers it in one call:

curl -s $BASE/relay/selftest -H "Authorization: Bearer $TOKEN"
# 200 -> { "ok": true, "checks": [...], "note": "read-your-writes verified: ..." }

It writes a distinctive probe loop and task inside your tenant, reads them back through the very same helpers the real routes use, asserts every field round-trips, and then rolls the probe back so it leaves zero trace. A 200 with ok:true means your token, your tenant, and the persistence layer are all healthy. A 500 names the field and route that failed to round-trip.