Setup guide · Beta

Set up FlowState Relay

Reach the FlowState on your own computer from claude.ai, ChatGPT and your other AI apps, from anywhere. Your data stays on your computer. You don't need to be a developer, but you will type a few commands.

1. What you need

FlowState Relay connects your AI apps to FlowState on your computer. Here's what that takes.

• A computer that stays onWindows, macOS or Linux. Your AI apps can reach FlowState only while this computer is on, awake and online.
• FlowStateFree and open source, version 2.2.0 or newer (the relay agent is part of it). Step 2 installs or updates it. It needs Python 3.11 or newer and git.
• An accountOn flowstatemcp.com, free during the beta. Step 3.
• A terminalTerminal on macOS or Linux, PowerShell on Windows. You'll paste a few commands into it.

2. Install and start FlowState

FlowState keeps your project memory in one file on your computer. The easy way to install it is to let an AI app that can run commands do it for you.

The easy way: paste this into Claude Code, Cursor, Codex CLI or Grok Build. It asks which apps to connect, shows you what it will change, then installs.

Set up FlowState for me from https://github.com/dialectforge/FlowState by following its AGENTS.md.

By hand: open a terminal and run these lines. On Windows, type python where it says python3. Put the apps you use after --clients (for example claude-desktop,cursor).

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

The first setup line only shows what would change. The second makes the changes, then checks that FlowState answers. Then fully quit and reopen the apps it connected.

Already have FlowState? Update it to get the relay agent. In the FlowState folder, run these lines, with the same apps after --clients as when you installed:

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

Your database is kept. Then fully quit and reopen your apps.

There's nothing to start by hand: the apps on this computer start FlowState when they need it. The relay (step 5) runs its own copy for your other apps.

3. Create your FlowStateMCP account

Go to flowstatemcp.com/signin and continue with Google or GitHub, or get a 6-digit code by email. There are no passwords. The first sign-in creates your account.

• Account pageflowstatemcp.com/account shows how you sign in, your place in the beta, your computer and its connection log.
• Beta10 spots. When they're taken, you join a waitlist, first come, first served.
• PriceFree for 6 months from when you sign up. After that, beta members keep founder pricing at half price: Relay $3 a month, and Hosted $6 a month once it launches. Billing isn't live yet, so nothing is charged and there is no checkout.
• One computerOne device per account: the computer where FlowState runs, one FlowState database for all your agents.

4. Get an enroll code and enroll your computer

An enroll code links your computer to your account, once. It takes three steps.

• Get a codeOn your account page, press Get an enroll code. It looks like ABCD-2345. It works once, expires in 15 minutes, and is shown only once. You can get 5 codes an hour.
• PassphraseThe first command below sets your owner passphrase (once). You type it on FlowState's approval page whenever you connect a new AI app, so only you can let apps in. Use 12 or more characters you don't use anywhere else. Type it only into the terminal, never into a chat.
• EnrollThe second command enrolls your computer. Put your code in place of YOUR-CODE.

Run these in the FlowState folder. On Windows:

.venv\Scripts\python -m flowstate remote passphrase
.venv\Scripts\python -m flowstate relay enroll --code YOUR-CODE

On macOS and Linux:

.venv/bin/python -m flowstate remote passphrase
.venv/bin/python -m flowstate relay enroll --code YOUR-CODE

When it works, it prints Enrolled. Your relay address: https://<handle>.fsmcp.com/mcp. Write the address down: it goes into your AI apps in step 6. It also gets a certificate for your address, made with a key that never leaves your computer.

If the beta is full, it says so with your place in line, and your code isn't used. See Troubleshooting. If it says relay is not a valid choice, your FlowState is older than 2.2.0: update it (step 2).

From here on, flowstate ... is short for the same start as above (.venv\Scripts\python -m flowstate or .venv/bin/python -m flowstate), in the FlowState folder.

5. Keep the relay agent running

Your AI apps can reach FlowState only while the relay agent runs. Start it and leave the window open.

The relay agent doesn't start by itself. After your computer restarts, run flowstate relay run again in the FlowState folder, or set it to start when you sign in (below).

.venv\Scripts\python -m flowstate relay run
.venv/bin/python -m flowstate relay run

The first line is for Windows, the second for macOS and Linux. To check on it, run flowstate relay status in another window: it shows Relay: ON, your address, the certificate's date and Tunnel: connected.

• Pause itflowstate relay disable stops it and keeps your enrollment. flowstate relay enable turns it back on; then start it again.
• SleepWhile the computer sleeps, your apps can't reach FlowState. Set it to stay awake while it's plugged in.

Optional: start it when you sign in, with your computer's own tools. Put your FlowState folder's full path in place of /path/to/FlowState. Then don't also start it by hand: only one copy can run.

• WindowsIn Task Scheduler, create a basic task that starts when you log on and starts a program. The program, its arguments, and where it starts are below (the last line is your FlowState folder). To stop it, delete the task.

C:\path\to\FlowState\.venv\Scripts\python.exe
-m flowstate relay run
C:\path\to\FlowState

• macOSSave the lines after the command as com.flowstatemcp.relay.plist in the LaunchAgents folder of your home folder, then run the command. To stop it, run it with unload in place of load, and delete the file.

launchctl load ~/Library/LaunchAgents/com.flowstatemcp.relay.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>Label</key><string>com.flowstatemcp.relay</string>
<key>ProgramArguments</key><array>
<string>/path/to/FlowState/.venv/bin/python</string>
<string>-m</string><string>flowstate</string><string>relay</string><string>run</string>
</array>
<key>WorkingDirectory</key><string>/path/to/FlowState</string>
<key>RunAtLoad</key><true/>
</dict></plist>

• LinuxSave these lines as ~/.config/systemd/user/flowstate-relay.service, then run systemctl --user enable --now flowstate-relay. To stop it, run systemctl --user disable --now flowstate-relay and delete the file.

[Unit]
Description=FlowState Relay

[Service]
WorkingDirectory=/path/to/FlowState
ExecStart=/path/to/FlowState/.venv/bin/python -m flowstate relay run

[Install]
WantedBy=default.target

6. Connect your AI apps

Apps on this computer already use FlowState directly since step 2; they don't need the relay. The relay is for apps in the cloud, on your phone, or on another computer. They all use your address: https://<handle>.fsmcp.com/mcp.

Connecting an app opens a FlowState page: choose Read only or Read and write, type your owner passphrase, and approve. Some apps take a fixed key instead: make one with flowstate remote add-client --name "App name" on your computer. It's shown once. Keep it in your app's settings or an environment variable, never in a chat.

• ClaudeOn claude.ai (also used by Claude Desktop and the Claude phone apps): Settings, then Connectors, then Add custom connector. Paste your address, press Connect, and approve on the FlowState page.
• Claude CodeOn another computer: make a key named "Claude Code", put it in an environment variable called FLOWSTATE_TOKEN, then run claude mcp add --transport http flowstate https://<handle>.fsmcp.com/mcp --header "Authorization: Bearer $FLOWSTATE_TOKEN".
• ChatGPTSettings, then Connectors (developer mode). Add your address with OAuth sign-in, then approve.
• CursorMake a key named "Cursor" and put it in an environment variable called FLOWSTATE_CURSOR_TOKEN. In Cursor's MCP settings, add your address as the url with "headers": {"Authorization": "Bearer ${env:FLOWSTATE_CURSOR_TOKEN}"}.
• GrokIn Grok, add a custom connector (a remote MCP server) and paste your address. Then approve on the FlowState page.
• Any MCP appLook for "add a remote MCP server" or "custom connector" and give it your address. Apps that sign in with OAuth open the FlowState approval page; apps that take a header use a key as above.

To cut an app off later: flowstate remote clients lists them, and flowstate remote revoke --client ID stops one at once.

7. Replacing a computer, and your data

Your FlowState data lives in one file on your computer. The relay never stores it and can't read it.

• What the relay seesWhen each connection was made, to which device, from which address, and how much data passed: your connection log on the account page, kept 30 days. Never what it contained.
• Why it can't read itThe key for your address is made on your computer and never leaves it. Your computer gets its own certificate and ends every encrypted connection itself; the relay only passes the encrypted bytes through (TLS passthrough).
• New computerOn your account page, press Replace this device and confirm. The old device is removed and you get a new code. Enroll the new computer with it (step 4). It gets a new address: put it in your AI apps in place of the old one.
• Moving your dataThe relay doesn't move your data. To bring it along, close your AI apps and the relay, then copy the FlowState database file to the same place on the new computer. Windows: %LOCALAPPDATA%\flowstate\flowstate.db. macOS: ~/Library/Application Support/flowstate/flowstate.db. Linux: ~/.local/share/flowstate/flowstate.db.
• Old computerStop the relay there and run flowstate relay forget. That deletes its device token and keys.
• Deleting your accountRemoves your relay device, its address, your connection log and your sign-in. FlowState on your computer is not touched.

More on what the relay and this site can and can't see: how FlowState is secured.

8. Troubleshooting

What you might see, and what to do.

• Device offlineThe account page says "not connected yet" or shows an old "last seen". On your computer: is flowstate relay run still open? Run flowstate relay status. Relay: OFF means run flowstate relay enable, then start it again. Tunnel: unauthorized means the device was removed or suspended on your account page. Certificate: none yet means run flowstate relay renew. Also check that the computer is awake and online.
• Code expiredEnroll says relay answered 400 (invalid_code). Codes work once and expire after 15 minutes. Get a new one on your account page. After 5 codes in an hour, wait a while.
• Beta fullEnroll says "The FlowState Relay beta is full right now. You're on the waitlist (number N)." Your code wasn't used and nothing was saved. When a spot opens, it's held for the first person in line for 48 hours, and your account page shows your place. Run the same enroll command again later.
• Device limitOne device per account. To move to a new computer, use Replace this device on your account page. If enroll says relay answered 403 (device_limit), your account already has its device; your code wasn't used.
• Already enrolledEnroll says "Already enrolled as ...": this computer already has a device. flowstate relay forget starts over; remove the old device on your account page too.
• Can't approve an appflowstate relay status says Owner passphrase: NOT set: run flowstate remote passphrase. Five wrong passphrases within 15 minutes lock approvals for up to 15 minutes.

9. Help

Email hello@flowstatemcp.com. Tell us what you ran and what it printed, but never send your passphrase, a key or a token.

FlowState itself is open source: github.com/dialectforge/FlowState. Setting it up with an AI agent? Point it at the guide for AI agents.

Found a security problem? Email support@flowstatemcp.com. See how FlowState is secured.