# FlowState Relay setup: instructions for AI agents

You are an AI agent helping your user reach their own FlowState (a local MCP server) from cloud AI apps through FlowState Relay. Follow the steps in order; each says how to check it. Plain text: https://flowstatemcp.com/setup/agents.md. For people: https://flowstatemcp.com/setup.

## Rules

- **Ask first** Ask the user before you install anything, change an app's config, start a long-running process, or create a scheduled or auto-start task. Say exactly what you will run.
- **No secrets in chat** Never ask the user to paste a secret into the chat: not the enroll code, the owner passphrase, a per-app key or token, or a device token. The user types those into their own terminal.
- **Never print the device token** It is stored owner-only in the relay folder inside FlowState's data folder. Don't open, print, copy or log the files there. `FS relay status` says `Device token: stored (not shown)`; that is all you need.
- **Plain words** If a step fails, stop and tell the user what failed and what to do next. Don't work around it silently.
- **Wrong package** Don't `pip install flowstate` from PyPI: that name belongs to an unrelated project. FlowState is installed from its GitHub repository; its setup script installs it into `.venv` in the FlowState folder.

## Facts

- **Address** `https://<handle>.fsmcp.com/mcp`, where `<handle>` is given at enroll.
- **Limits** 1 device per account. An enroll code works once and is valid for 15 minutes. 5 codes per account per hour.
- **Beta** 10 spots. When full, enroll puts the user on a waitlist, first come, first served; a spot that opens is held 48 hours for the first in line.
- **Account** Only the user can sign in: https://flowstatemcp.com/signin (Google, GitHub or a 6-digit email code). Enroll codes come from https://flowstatemcp.com/account.
- **Price** Free for 6 months from signup; then beta members keep half price (Relay $3/mo, Hosted $6/mo). Billing is not live: never promise a checkout.
- **Privacy** TLS passthrough: the TLS key is made on the user's computer and never leaves it; the relay sees only connection times, client addresses and byte counts.
- **Security** How FlowState, the relay and the account site are secured, and their limits: https://flowstatemcp.com/security

## 1. Install or update FlowState

The relay agent is part of FlowState 2.2.0 and newer. New install: follow https://github.com/dialectforge/FlowState/blob/main/AGENTS.md. Short form (needs Python 3.11+ and git; `PY` is `python3` on macOS/Linux, `python` or `py -3` on Windows; ask the user which apps to pass to `--clients`):

```
git clone https://github.com/dialectforge/FlowState.git FlowState
cd FlowState
PY setup_flowstate.py --clients claude-desktop --schedule-backups --no-offsite --install-skill --dry-run
PY setup_flowstate.py --clients claude-desktop --schedule-backups --no-offsite --install-skill --verify
```

Already installed: ask the user, then update it in the FlowState folder, passing the same `--clients` the user chose before:

```
git pull
PY setup_flowstate.py --clients claude-desktop --schedule-backups --no-offsite --install-skill --verify
```

The database is kept. Check: `--verify` reports that start_here answered. From here on, `FS` means `.venv\Scripts\python -m flowstate` on Windows and `.venv/bin/python -m flowstate` on macOS/Linux, run in the FlowState folder.

## 2. Check for the relay agent

```
FS relay --help
```

If it lists enroll, run and status, the relay agent is installed. If it fails because `relay` is not a valid choice, this FlowState is older than 2.2.0: update it (step 1), then check again. Get it only from https://github.com/dialectforge/FlowState, nowhere else.

## 3. Account and enroll code (the user)

Ask the user to sign in at https://flowstatemcp.com/signin, open https://flowstatemcp.com/account and press Get an enroll code. Tell them it works once, for 15 minutes, and not to paste it to you.

## 4. Owner passphrase (the user, once)

The user runs this in their own terminal. It prompts for a passphrase (12+ characters); don't run it for them and don't pipe input to it.

```
FS remote passphrase
```

Check: `FS remote status` shows `Owner passphrase: set`.

## 5. Enroll (the user)

The user runs this in their own terminal, with their code:

```
FS relay enroll --code <code>
```

Success prints `Enrolled. Your relay address: https://<handle>.fsmcp.com/mcp` and then `Certificate obtained for ...`. The address is not a secret: read it from `FS relay status` (the `URL:` line) or ask the user for it.

## 6. Run the relay agent

Ask before starting it. It keeps running and logs to its terminal.

```
FS relay run
```

It runs FlowState's public listener on 127.0.0.1:8768 (`--port` to change), the tunnel, certificate renewal and a daily Certificate Transparency check. FlowState has no built-in auto-start: after a restart, `FS relay run` must be started again. Tell the user that. You may offer to make it start at sign-in with the OS's own tools (Windows Task Scheduler, a macOS launchd LaunchAgent, a Linux systemd user service) that run `FS relay run` in the FlowState folder; the human guide has each one (https://flowstatemcp.com/setup#run). Create it only after the user says yes, then stop any copy you started by hand, and tell them how to remove it.

## 7. Check it worked

```
FS relay status
```

Expect `Relay: ON`, `URL: https://<handle>.fsmcp.com/mcp`, `Device token: stored (not shown)`, `Certificate: valid until ...` and `Tunnel: connected ...`. Exit code 2 means a Certificate Transparency warning: show the user the warning lines exactly as printed.

Health check through the relay (no token needed; on Windows use `curl.exe`):

```
curl -s https://<handle>.fsmcp.com/health
```

Expect `{"ok": true, "service": "flowstate"}`.

MCP initialize without a token (macOS/Linux shell):

```
curl -si -X POST https://<handle>.fsmcp.com/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-check","version":"1"}}}'
```

Expect status 401 with a `WWW-Authenticate: Bearer` header that points to `/.well-known/oauth-protected-resource`. That is correct: the request reached FlowState through the relay, and FlowState asks for sign-in. A closed connection, a TLS error or a timeout means the device is not connected: `FS relay run` is not running, or the computer is asleep or offline.

## 8. Errors and what to tell the user

- **waitlisted (429)** From POST https://api.fsmcp.com/api/enroll: `{"error": "waitlisted", "reason": "active" or "weekly", "retry_after": <unix time>, "position": <n>, "message": "..."}` and a `Retry-After` header in seconds. The CLI prints "The FlowState Relay beta is full right now. You're on the waitlist (number N). ..." (or, for the weekly limit, "... try again after <time>") and "No token or key was saved on this computer." Tell the user: they are number N on the waitlist, the code was not used, and they can run the same enroll command again later; their account page shows their place.
- **device_limit (409)** When getting a code on the account page; the page says "Your account has 1 device, the most it can have." Enroll can also get 403 `device_limit`; the CLI prints `Relay: relay answered 403 (device_limit)`. Tell the user: one device per account; use Replace this device on the account page (it removes the old device and gives a new code). The code was not used.
- **code_limit (429)** When getting a code: 5 codes per account per hour; the page says "You have asked for 5 codes in the last hour." Tell the user to wait, then get a new code.
- **Expired or used code (400)** `invalid_code`: the CLI prints `Relay: relay answered 400 (invalid_code)`. The code was wrong, already used, or older than 15 minutes. Tell the user to get a new code.
- **rate_limited (429)** Too many enroll tries from this address. The CLI prints `Relay: the relay is busy or you tried too often (429); wait a while and try again (rate_limited)`. Tell the user to wait an hour.
- **Already enrolled** The CLI prints `Already enrolled as <handle>.fsmcp.com. To start over: flowstate relay forget`. Don't run forget without asking: it deletes the device token and keys, and the handle stays taken until the user removes the device on the account page.
- **Tunnel: unauthorized** In `FS relay status`: the device was removed or suspended on the account page. Ask the user to check it there.
- **Owner passphrase: NOT set** Apps can't be approved. The user runs `FS remote passphrase`.

## 9. Connect the user's apps

Apps on the same computer use FlowState directly (step 1) and don't need the relay. For cloud apps, phones and other computers, give the user the address `https://<handle>.fsmcp.com/mcp`.

- **claude.ai** Settings, then Connectors, then Add custom connector; paste the address, Connect, then approve on the FlowState page with the owner passphrase.
- **ChatGPT** Settings, then Connectors (developer mode); add the address with OAuth, then approve.
- **Fixed-key apps** Cursor, Claude Code on another computer, and others: the user runs `FS remote add-client --name "<app>"` in their own terminal and keeps the key in an environment variable. You must not see the key.
- **Grok** In Grok, add a custom connector (a remote MCP server) with the address, then approve on the FlowState page.
- **Cut an app off** `FS remote clients`, then `FS remote revoke --client <id>`.

## Help

hello@flowstatemcp.com. Human guide: https://flowstatemcp.com/setup