Install flowifai

One signed installer puts the operator CLI, local broker, and stdio wrapper under ~/.flowifai/bin:

curl -fsSL https://flowif.ai/install.sh | sh

Linux and macOS on amd64 or arm64 are supported.

Inspect first

Use the inspect-first path when you want to review the script before running it:

curl -fsSLO https://flowif.ai/install.sh
less install.sh
sh install.sh

The installer reads signed stable.json release metadata, verifies the manifest signature and SHA values, verifies each downloaded asset’s SHA-256 checksum, and only then puts binaries in place — with an atomic version swap and --version post-checks. The release-key fingerprint is carried in the signed metadata rather than copied into this page.

What gets installed

Binary	Role
`flowifai`	Operator CLI for connect, status, doctor, update, policy, and approvals.
`flowifai-broker`	Trusted local process on the tools host. It owns the enrollment credential and launches the real MCP server.
`flowifai-wrapper`	Untrusted stdio MCP shim used by Claude or another MCP client. It holds no flowifai credential.

How it fits together

The full first-run flow is in the quickstart. For existing Claude Code or Cursor MCP configuration, start with:

flowifai setup --dry-run
flowifai setup

The wizard creates one private profile and loopback broker process for each distinct selected MCP launch. The older flowifai connect flow remains available for manual and unsupported-client setup.

Profile brokers bind an ephemeral 127.0.0.1 port and publish it to their matching wrappers through private runtime state.
The legacy singleton broker binds to 127.0.0.1:8090 by default.
The wrapper-facing broker endpoints are not authenticated. Do not expose them directly to a LAN, VPN, or raw firewall allow-list.
For split-host setups, use an SSH tunnel or equivalent authenticated encrypted loopback tunnel, then point FLOWIFAI_BROKER_URL at the local tunnel endpoint.
Prefer the app-generated flowifai connect --pairing-token-stdin -- ... command over legacy FLOWIFAI_WRAPPED_CMD; the connect path stores the wrapped command as structured argv.

Wrapper path for GUI clients

GUI-launched MCP clients may not inherit your shell PATH. Print the exact Claude JSON or the expanded wrapper path:

flowifai client-config claude --print

flowifai wrapper-path

Broker service

Keep the broker running after the terminal closes with the per-user service helpers:

flowifai broker install-service
flowifai broker start
flowifai broker logs

On Linux this writes a systemd user unit. On macOS this writes a LaunchAgent. The service runs flowifai-broker from the installed tools directory, reads the private local config created by flowifai connect, and snapshots the current shell environment into a private service env file, excluding flowifai runtime overrides. If your MCP server needs new API keys or PATH entries later, rerun flowifai broker install-service before restarting the broker. If flowifai backend, credential, broker address, server name, or wrapped command settings change, rerun the app-generated flowifai connect command.

Setup-managed services use a profile ID:

flowifai broker status --profile PROFILE_ID
flowifai broker logs --profile PROFILE_ID
flowifai broker reload --profile PROFILE_ID

Use --all instead of --profile to operate all protected profiles. Each profile has separate private config, credentials, runtime identity, and process state.

Update and verify

flowifai version
flowifai update --check
flowifai update

flowifai doctor --strict
flowifai doctor --json --check-update

Use flowifai doctor --strict for install, backend, and broker diagnostics that fail decisively. Use --check-update only when you want to diagnose the signed release channel. The updater verifies the same signed manifest and per-asset checksums as the installer before replacing binaries.

flowifai status is an operator diagnostic. Registered-server data uses the local config or FLOWIFAI_S2S_SECRET; approval data can require FLOWIFAI_USER_TOKEN.

Common fixes

Problem	Fix
Command not found	Add `~/.flowifai/bin` to `PATH` or use the absolute binary path.
Missing S2S secret	Run the app-generated `flowifai connect --pairing-token-stdin` command. If pairing is disabled or the credential is lost, rotate/mint a replacement credential in agent details and use the credential-stdin fallback. Credentials are shown once.
Wrapper cannot reach broker	Same host: run `flowifai broker start` and use `FLOWIFAI_BROKER_URL=http://localhost:8090`. Split host: start the loopback tunnel first and point the wrapper at that local endpoint.
Schema drift	Run the app-generated `flowifai connect` command again, then `flowifai broker stop && flowifai broker start` so startup drift checks re-run.
Stale install lock	Remove `$FLOWIFAI_HOME/.install.lock` only after confirming no install or update is running.
Unsupported platform	Linux and macOS on amd64 or arm64 are supported.

More failure modes — including pairing-token expiry — are in troubleshooting.

Security note

The broker is the trust anchor; the wrapper holds no flowifai credential. Credentials configured in your local MCP server stay local, but tool names, descriptions, input schemas, call arguments, approval events, audit metadata, lifecycle events, and execution results may be sent to and stored by the backend. Values embedded in arguments or results, including accidental secrets, may therefore be stored. Read the security model.

View this page as markdown · All docs as one file