Start building with FlowRail

Before you start

• Use a Bash or Zsh terminal on macOS or Linux.
• Have Node.js 20 or newer (with npm), Git, and a Git project containing package.json.
• Have a FlowRail account with access and a supported coding agent installed. The released installer configures Claude Code today; Codex support is being tested, with more agents planned.

node --version
npm --version
git --version

Each command should print a version number. Node must be v20 or newer; npm and Git just need to be installed. If a command is not found, install that tool before continuing.

1. Connect your account

Sign in at https://flowrail.ai/settings/keys. Generate a workstation key and save it in your password manager; it is shown only once. 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.

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, copy and run the command below in your terminal. Then copy your saved key from your password manager, paste it at the hidden prompt, and press Return. Nothing appears while you paste; this is expected. Copying the command replaces anything already on your clipboard. The key is held in this shell's environment rather than written into the command history.

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.

FLOWRAIL_MCP_URL='https://api.flowrail.ai' 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

FLOWRAIL_MCP_URL='https://api.flowrail.ai' npx --yes -p @flowrail/hook flowrail status --no-probe

Look for these success lines in the output. Other status details may appear between them:

• [ok] API key set (FLOWRAIL_API_KEY)
• [ok] Hook wired into .claude/settings.json (pre-write + pre-bash)
• [ok] Hook binary runnable (npx -p @flowrail/hook flowrail-hook)
• [ok] Server reachable

If a line says [FAIL], fix that item before continuing. 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. Start your coding agent

For the currently released integration, check that the agent CLI is installed, then start it from the terminal holding FLOWRAIL_API_KEY:

claude --version
claude

Starting a new agent session from this terminal passes it the key. Restart a session that was already running when you installed FlowRail. A new terminal needs the key supplied again, or supplied by your own secret manager. In Claude Code, approve this project's FlowRail MCP connection if prompted; run /mcp and confirm the flowrail server is connected. If it is disconnected, recheck the key and server status, then restart from this terminal.

5. Review your first design

Replace the bracketed description, then paste this whole prompt into your coding agent. You can start with an idea; you do not need an existing specification.

I would like to build [describe your app or feature].

Help me brainstorm the design. Ask me questions if anything is unclear or ambiguous, including who can access which data and what should happen when an operation fails.

Once we agree on the design, save the specification as a Markdown file in this project. Use the flowrail-design-review skill on that specification before implementing it.

Wait for the review to finish, then explain the security requirements and anything that needs clarification. Let me review the results before you start building.

When the review completes, read the requirements before building. Open the corresponding design review in your dashboard to follow the evidence.