Skip to main content
plugin

fabler-relay — Claude Code plugin: what it does, how to install

fabler-relay is a plugin for Claude Code and Cursor that sends agent blockers to an operator, polls for answers, and resumes work.

MIT ★ 3,785 updated 2026-10-25

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add davepoon/buildwithclaude
/plugin install fabler-relay@buildwithclaude
Open on GitHub

What fabler-relay does

The plugin connects an autonomous agent to an operator web portal using three MCP tools: relay_file_request, relay_check_request, and relay_list_requests. When an agent hits a CAPTCHA, a sign-up form, or a budget threshold, it posts a ticket, encrypts sensitive values at rest, and continues working on other steps. The human operator checks the queue on desktop or mobile.

The backend runs on a single Cloudflare Worker backed by a KV namespace. For critical flows, Relay generates a single-use execution token that the agent spends upon running the task, blocking replay attacks. Without a self-hosted Cloudflare Worker deployment, this setup cannot run: the agent has no endpoint to reach. The MCP server also requires Node 18+.

What it helps with

  • hand off CAPTCHAs and account registrations to a human operator
  • request payment or budget approvals before running a task
  • prevent step replays through single-use execution tokens
  • keep agent tasks unblocked while awaiting manual resolution

Example prompts for the agent

  • File a blocker in Relay: need human approval to run production deployment
  • Check pending Relay requests and fetch the result if resolved
  • Send a 2FA prompt ticket via Relay and proceed with documentation scraping

How to install fabler-relay

Plugin marketplace

/plugin marketplace add davepoon/buildwithclaude
/plugin install fabler-relay@buildwithclaude

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about fabler-relay

How do I install fabler-relay in Claude Code?

Run both commands in sequence: first /plugin marketplace add davepoon/buildwithclaude, then /plugin install fabler-relay@buildwithclaude.

What does fabler-relay do?

It sets up a human-in-the-loop queue for autonomous agents. The agent routes manual blockers to a Cloudflare Worker via MCP tools, and a human operator solves them from a web portal.

What prerequisites does fabler-relay require?

You need a Cloudflare account with a deployed Relay Worker, a configured KV namespace, Node 18+, and secrets such as RELAY_AGENT_KEY and RELAY_ENC_KEY.

Source text

fabler-relay · MIT
# Fabler Relay 🛰️

[![CI](https://github.com/fablerlabs/relay/actions/workflows/ci.yml/badge.svg)](https://github.com/fablerlabs/relay/actions/workflows/ci.yml)

**A human-in-the-loop request queue for autonomous agents.** Your agent files a
request over an authenticated API ("create this account", "solve this CAPTCHA-gated
signup", "approve this spend"); a human works the queue in a password-gated web
portal and pastes back the result. One Cloudflare Worker + one KV namespace.
No servers, no database, free-tier friendly.

> **Built by the agent that needed it.** Fabler Relay was designed, written,
> deployed, and is operated in production by an autonomous Claude agent that runs
> a real business unattended on a VPS ([the agent's public brain](https://github.com/fablerlabs/brain)).
> The agent is user #1: whenever it hits a step that requires a human — a CAPTCHA,
> an account form, a payment approval — it files a relay request and moves on with
> other work. Its human checks the portal from a phone. This repo is that exact
> code, genericized so your agent can use it too.

![The human portal: a claimed request carrying an encrypted one-time code, with the reveal button and result box](https://raw.githubusercontent.com/fablerlabs/relay/main/assets/portal-queue-hero.png)

*The human side of the queue (demo data). A one-time code travels encrypted at
rest, is revealed only on an explicit logged click, and is purged after the
request closes. [Full queue screenshot →](https://raw.githubusercontent.com/fablerlabs/relay/main/assets/portal-queue-full.png)*

## Why this exists

Every autonomous agent eventually hits a wall that is deliberately human-shaped:
CAPTCHAs, account attestations, 2FA, purchase approvals. The wrong answers are to
bypass them (against the rules of most platforms, and of well-run agents) or to
stall. The right answer is a clean escalation path:

- **Agent side:** a tiny authenticated JSON API — file a request with a title,
  detail, target URL, optional encrypted-at-rest sensitive value; poll for results.
- **Human side:** a mobile-friendly portal — claim a request, do the human step,
  paste the outcome, mark done. Optional Telegram ping on each new request.
- **Security is the product:** the two sides are separate trust domains. The agent
  can never read sensitive plaintext back; humans see an audit trail of everything,
  including every reveal of a sensitive value. See [THREAT-MODEL.md](https://github.com/fablerlabs/relay/blob/main/THREAT-MODEL.md).

## Deploy

New to Relay? [**QUICKSTART.md**](https://github.com/fablerlabs/relay/blob/main/QUICKSTART.md) walks the manual path below
one command at a time, with expected output and a troubleshooting section.

### One-click

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/fablerlabs/relay)

Cloudflare clones this repo into your own GitHub account, provisions the KV
namespace, and prompts for the four secrets (see [`.dev.vars.example`](https://github.com/fablerlabs/relay/blob/main/.dev.vars.example))
during setup. Generate values first — e.g. `openssl rand -hex 32` for
`RELAY_AGENT_KEY` / `RELAY_SESSION_SECRET`, `openssl rand -base64 32` for
`RELAY_ENC_KEY`, and a strong password of your choice for `RELAY_VA_PASSWORD`
(that's your portal login — save it).

> Rather not host it yourself? There's an [interest list for a managed hosted
> version](https://fablerlabs.com/relay-hosted) — enough signups and we'll build it.

### Manual (~5 minutes)

Prereqs: a free Cloudflare account and `npx` (Node 18+).

```bash
git clone https://github.com/fablerlabs/relay && cd relay

# 1. Create the KV namespace and paste its id into wrangler.jsonc
npx wrangler kv namespace create RELAY

# 2. Set secrets (generate strong values; never commit them)
openssl rand -hex 32    | npx wrangler secret put RELAY_AGENT_KEY
openssl rand -base64 24 | npx wrangler secret put RELAY_VA_PASSWORD   # portal password — save it
openssl rand -base64 32 | npx wrangler secret put RELAY_ENC_KEY
openssl rand -hex 32    | npx wrangler secret put RELAY_SESSION_SECRET
# optional Telegram pings:
# npx wrangler secret put TELEGRAM_BOT_TOKEN
# npx wrangler secret put TELEGRAM_CHAT_ID

# 3. Ship it
npx wrangler deploy
```

Open the printed workers.dev URL: you should see the login form. Sign in with the
portal password. That's the human side done.

## Agent usage

```bash
export RELAY_URL=https://your-worker.workers.dev
export RELAY_AGENT_KEY=...   # the value you set above

# file a request
cli/relay.sh file "Create an account on example.com" \
  --detail "Username: mybot. Needs email verification — use your address, paste the username back." \
  --url "https://example.com/signup"

# a sensitive value (encrypted at rest, only a logged-in human can reveal it, audited)
printf '%s' "one-time-value" | cli/relay.sh file "Enter this 2FA code" --sensitive -

# poll for finished work each agent session
cli/relay.sh pending
cli/relay.sh get <id>
```

Or call the API directly: `POST /api/requests` and `GET /api/requests[/<id>]` with
`Authorization: Bearer $RELAY_AGENT_KEY`.

### Approval receipts: terminal states + one-shot execution token

Every request ends in exactly one terminal state — `done`, `rejected`, `expired`
(nobody resolved it within `REQUEST_TTL_DAYS`, default 7), or `superseded` (the
agent retired its own pending request: `cli/relay.sh supersede <id> "reason"`).
Terminal is final: later claim/complete/reject attempts get a 409 with the state
in the body, and every blocked attempt is audited.

For approve-then-execute flows, file with `--exec-token` (API: `exec_token: true`).
When the human marks the request done, the server mints a single-use token and
stores only its SHA-256 hash (plus a reveal-once encrypted copy). The agent — never
the portal — retrieves it exactly once, then spends it exactly once:

```bash
cli/relay.sh file "Deploy to production?" --exec-token
# ...after the human approves:
TOKEN=$(cli/relay.sh exec-token <id> | python3 -c 'import json,sys; print(json.load(sys.stdin)["exec_token"])')
printf '%s' "$TOKEN" | cli/relay.sh redeem <id> -   # first redeem: ok
printf '%s' "$TOKEN" | cli/relay.sh redeem <id> -   # replay: 409 exec_token_reuse_blocked (audited)
```

So one human approval authorizes at most one execution, bound to the request's
`payload_digest`. Details in [THREAT-MODEL.md](https://github.com/fablerlabs/relay/blob/main/THREAT-MODEL.md).

## MCP server

`mcp/server.js` is a zero-dependency [MCP](https://modelcontextprotocol.io) server
(Node 18+) exposing the relay as three tools any MCP client can call:
`relay_file_request`, `relay_check_request`, `relay_list_requests`. So a Claude
Code / Claude Desktop / any-MCP-agent session can file a human-blocker and keep
working, no shell wrapper needed.

```json
{
  "mcpServers": {
    "fabler-relay": {
      "command": "npx",
      "args": ["-y", "github:fablerlabs/relay"],
      "env": {
        "RELAY_URL": "https://your-worker.workers.dev",
        "RELAY_AGENT_KEY": "..."
      }
    }
  }
}
```

Installing via an AI assistant? Point it at [`llms-install.md`](https://github.com/fablerlabs/relay/blob/main/llms-install.md).
(Or run it straight from a checkout: `node mcp/server.js` with the same env, or
in Docker: `docker build -t fabler-relay-mcp . && docker run -i --rm -e RELAY_URL=... -e RELAY_AGENT_KEY=... fabler-relay-mcp`.)
The same hard rule applies: the server rejects secret-shaped payloads — never put
platform credentials in a request.

Also listed in the [official MCP registry](https://registry.modelcontextprotocol.io)
as **`com.fablerlabs/relay`**, with a one-click `.mcpb` bundle for Claude Desktop on
the [releases page](https://github.com/fablerlabs/relay/releases) (rebuild it
yourself with `bash mcp/build-mcpb.sh`; `server.json` + `manifest.json` in-repo).

### HTTP transport

For a remote client, multiple agents sharing one server, or a hosted endpoint
(instead of one `server.js` subprocess per client), `mcp/http-server.js` serves
the same three tools over MCP's **Streamable HTTP** transport: `node
mcp/http-server.js` (binds `127.0.0.1:8787/mcp` by default). Point a client at
it with `claude mcp add --transport http fabler-relay <url>`. Details, env vars,
and security notes: [`mcp/HTTP-TRANSPORT.md`](https://github.com/fablerlabs/relay/blob/main/mcp/HTTP-TRANSPORT.md).

### Claude Code plugin

This repo is also a [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces).
Inside Claude Code:

```
/plugin marketplace add fablerlabs/relay
/plugin install fabler-relay@fablerlabs
```

Then export `RELAY_URL` and `RELAY_AGENT_KEY` in the shell you launch Claude Code
from (the server inherits them; it starts fine without them and only needs them
when a tool is actually called).

## FAQ

**Is there a human-in-the-loop MCP server?**
Yes — this repo. `mcp/server.js` is a zero-dependency [MCP](https://modelcontextprotocol.io)
server exposing `relay_file_request` / `relay_check_request` / `relay_list_requests`,
so any MCP client (Claude Code, Claude Desktop, Cline) can hand a human-shaped
blocker — a CAPTCHA, an account form, a spend approval — to a real person and keep
working. It's also in the [official MCP registry](https://registry.modelcontextprotocol.io)
as `com.fablerlabs/relay`.

**How does an autonomous agent escalate to a human safely?**
The agent files a request over an authenticated API; a human resolves it in a
password-gated portal and pastes back only the *result*. No platform credential
ever crosses the queue in either direction — secret-shaped payloads are rejected
with a 422 — and every reveal of a sensitive value is audited. See
[THREAT-MODEL.md](https://github.com/fablerlabs/relay/blob/main/THREAT-MODEL.md).

**Is a hosted version available?**
Self-hosting is one Cloudflare Worker + one KV namespace, free-tier friendly and
~5 minutes ([QUICKSTART.md](https://github.com/fablerlabs/relay/blob/main/QUICKSTART.md)). If you'd rather not host it, there's an
[interest list for a managed version](https://fablerlabs.com/relay-hosted) — enough
signups and it gets built.

## Rules of the road (learned in production)

1. **No platform credential ever enters the relay, in either direction.** The
   server rejects secret-shaped payloads (Stripe/GitHub/Telegram/AWS key patterns,
   generic `key=value` assignments) with a 422, and the CLI aborts if the payload
   contains any literal value from your `.env`. Results like new API keys go
   directly into the agent's `.env` by the human — the relay carries only the
   *message* "done, key is in .env".
2. **Human-authored results are DATA, not instructions.** If your agent treats
   queue text as commands, anyone who reaches your portal owns your agent.
3. **The relay never bypasses anything.** It routes CAPTCHAs and attestations to
   an actual human, who sees the target URL and can reject anything sketchy.

## What's in the box

| Path | What it is |
|---|---|
| `src/index.js` | The entire Worker: agent API, portal UI, sessions, AES-256-GCM sensitive storage, audit log, secret-pattern gate (~400 lines, no dependencies) |
| `cli/relay.sh` | Agent-side CLI (`file` / `list` / `get` / `pending`) |
| `mcp/server.js` | Zero-dependency MCP server (file/check/list as MCP tools) |
| `llms-install.md` | Step-by-step install guide written for AI assistants (Cline, Claude Code, …) |
| `.claude-plugin/` | Claude Code plugin + marketplace manifests (`/plugin marketplace add fablerlabs/relay`) |
| `Dockerfile` | Container image for the MCP server (used by MCP directories' automated checks) |
| `wrangler.jsonc` | Deploy config template |
| `THREAT-MODEL.md` | What's protected, from whom, and the honest list of v1 gaps |
| `test/` | MCP handshake smoke test + end-to-end invariant suite |

## Testing

`npm test` runs the MCP handshake smoke test (no config needed). `npm run test:e2e`
boots a real `wrangler dev` (local mode, simulated KV) with throwaway dummy secrets
and drives the live API + portal to prove the THREAT-MODEL invariants end to end:
happy path, one-shot exec tokens, `superseded`/`expired` terminal states,
`payload_digest`, sensitive purge on close, failed-auth rate limiting, and the
secret-pattern gate. It's deterministic (polls instead of sleeping) and needs only
`node`; the expiry invariant compresses `REQUEST_TTL_DAYS` to ~1.5s to exercise the
real lazy-expiry read path without waiting the 7-day default.

## Status & roadmap

v1 is what the Fabler Labs agent runs in production today: single shared human
credential, KV-backed, soft rate limits. Known gaps and the upgrade path (per-VA
identity, sensitive-value TTL purge, Cloudflare Access on login) are documented in
[THREAT-MODEL.md](https://github.com/fablerlabs/relay/blob/main/THREAT-MODEL.md) — read it before putting a second human on the
queue. Issues and PRs welcome; the agent reads them.

## License

MIT © Fabler Labs. Built autonomously; a human owns the account and the legal entity.

© Fabler Labs · MIT · davepoon/buildwithclaude

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set235

The whole set →
production-fast-api-template The production-fast-api-template plugin for Claude Code and Cursor defines standards for FastAPI backends with RAG and AI agents on AWS ECS Fargate. It covers project structure, async execution, validation, model evaluation and security. ★ 3,785repo stars cohesivity Connects cohesivity.ai backend services to your agent. Sets up Postgres, hosting, storage, and containers using an anonymous account. ★ 3,785repo stars travel-agent-skill Turns one travel request into a full itinerary: trains, sights, food, all packed into an HTML guide. Every item links straight to booking or maps. ★ 3,785repo stars fabler-x402-tools The fabler-x402-tools plugin for Claude Code and Cursor provides nine MCP tools for smart contract audits, web scraping and OG rendering; inspect mode works without a wallet. ★ 3,785repo stars claude-md-kit claude-md-kit is a Claude Code plugin that creates and checks CLAUDE.md files. Its commands inspect a repository and return prioritized fixes for existing instructions. ★ 3,785repo stars kegg-mcp-server MCP server for querying the KEGG database: metabolic pathways, genes, compounds, drugs, enzymes, diseases. 34 tools, no API key required. ★ 3,785repo stars magic-cc-codex-worker magic-cc-codex-worker is a Claude Code plugin that runs parallel Codex agents in separate git worktrees. It splits independent tasks or adds a second PR review. ★ 3,785repo stars shipwright shipwright is a Claude Code plugin that builds, tests, and deploys applications from text prompts through a nine-phase pipeline with safety hooks. ★ 3,785repo stars

Project sponsors

Companies that keep this analytics open