# Install flowifai

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

```sh
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:

```sh
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](/docs/quickstart/). For existing
Claude Code or Cursor MCP configuration, start with:

```sh
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:

```sh
flowifai client-config claude --print
```

```sh
flowifai wrapper-path
```

## Broker service

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

```sh
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:

```sh
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

```sh
flowifai version
flowifai update --check
flowifai update
```

```sh
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](/docs/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](/docs/security-model/).