Skip to installation
FlowRail

Your first session

Start building with FlowRail

Connect your account, install in your project, and check that the hook is working. Then open Claude Code from the same terminal.

Before you start

You need Claude Code, Node.js 20 or newer (with npm), Git, a project with a package.json, and a FlowRail account with access. The terminal commands below are for Bash or Zsh on macOS or Linux. The released packages are init 0.0.18, hook 0.0.25 and skills 0.0.8.

Before you start
node --version
npm --version
git --version
claude --version

1. Connect your account

Sign in at https://flowrail.ai/settings/keys. Generate a workstation key and copy it. Use a production key with the default production endpoint; a staging key will not work here. Never paste your key into an agent conversation, a Git commit or a command argument.

Open your API keys

If FLOWRAIL_API_KEY is already exported in this shell by you or your secret manager, skip the prompt and go to step 2; do not print its value. Otherwise, run the command below in your terminal, paste the key at the hidden prompt, and press Return. The key is held in this shell's environment rather than written into the command history.

1. Connect your account
printf 'FlowRail API key: '
IFS= read -r -s FLOWRAIL_API_KEY
printf '\n'
export FLOWRAIL_API_KEY

2. Install in your project

Change into the Git project you want to protect, then run the installer. For an existing installation, use the same command to refresh the hook and skills. Keep your shared npm cache.

2. Install in your project
npx --yes @flowrail/init@latest

Wait for the hook self-test, connectivity check and app registration to succeed. The installer also checks existing dependencies. A deferred app registration needs a retry; do not treat a local-only identity as confirmed registration. Generated configuration uses an environment reference for your key.

3. Confirm the connection

3. Confirm the connection
npx --yes -p @flowrail/hook flowrail status --no-probe

Confirm that the key is set, the pre-write and pre-bash hooks are wired, the binary is runnable, and the production server is reachable. A SCOPED warning describes the expected default posture; it does not mean setup failed. This command skips the paid model-latency probe. The installer's local self-test establishes that the hook executable can block a test write; it is not a full security assessment.

4. Open Claude Code

4. Open Claude Code
claude

Start Claude Code from this same terminal so it inherits FLOWRAIL_API_KEY. Restart an already-running Claude session after installation. A new terminal needs the key supplied again, or supplied by your own secret manager. In Claude, approve this project's FlowRail MCP connection if prompted, then run /mcp and confirm the flowrail server is connected before continuing. If it is disconnected, recheck the key and server status, then restart from this terminal.

Ask Claude to use the flowrail-design-review skill on your specification before implementing it. Describe who may access which resources and what should happen when an operation fails. Review the generated requirements, then let Claude work through the registered Write/Edit hooks. Open the corresponding design review in your dashboard to follow the evidence.

Understand the result
  • A denied write has a finding to address. Ask Claude to correct the proposed code and retry.
  • An incomplete design-bound check pauses the write. Wait, then retry the unchanged write to collect its result. A timeout is not itself a vulnerability.
  • A requirement marked not established needs evidence that is missing from this file, such as behavior in another service. It is neither verified satisfaction nor automatically a vulnerability.
  • A passing write is evidence for that check. It does not close every threat or prove the whole app secure.
If something needs attention
  • HTTP 401: copy an active production key from flowrail.ai/settings/keys, set it in the same terminal, and retry. Do not show the key in logs or chat. Check whether FLOWRAIL_MCP_URL points at another environment.
  • Missing hooks or an old package: rerun npx --yes @flowrail/init@latest in this project, then restart Claude Code. Do not delete other hooks or clear a shared cache.
  • Connection or registration failure: check https://flowrail.ai/status, wait and retry the installer. Preserve .flowrail/app.json so a retry keeps the same app identity.
  • Default scope: incomplete design-bound writes pause. Unbound writes can still proceed on operational failures. FlowRail does not intercept every way a file can be changed, and it does not intercept outgoing actions at runtime.
What is installed

FlowRail adds its hook entries to .claude/settings.json, its MCP entry to .mcp.json, five skills under .claude/skills, flowrail.yaml, a .flowrail app identity, and scripts/check-flowrail.mjs. It adds its doctor to predev/prebuild scripts and adds its local state to .gitignore. Inspect the resulting diff in an existing project.

Uninstall from a project

Remove only the FlowRail hook commands from .claude/settings.json and the flowrail entry from .mcp.json; preserve other hooks and MCP servers. Remove the five flowrail-* skill directories installed by FlowRail, its doctor script and only its doctor clauses in package.json. Remove FlowRail's local configuration/state if you no longer need it, uninstall @flowrail/hook (and @flowrail/init if you installed it locally), then restart Claude Code. Revoke the workstation key in Settings if it is no longer used by another project.

Data and scope

Specification and candidate code are sent to FlowRail's backend and its configured model provider for analysis. Read https://flowrail.ai/privacy before supplying sensitive code. Claude Code is the supported hook integration; an agent can read these instructions to help with setup without implying a native OpenClaw, Codex or Cursor integration.

Need a hand? hello@flowrail.ai · Service status