Install on macOS

The Flowstate Agent on macOS is a single CLI (/usr/local/bin/flowstate) plus a launchd daemon (inc.flowstate.agent.proxy) that captures AI traffic and forwards it to the Flowstate cloud proxy at ai.flowstate.inc. The same flowstate install command handles the CLI, the certificate authority, the daemon, and the per-tool configuration in one shot — there is nothing else to wire up.

What you get

• v1 — PAC mode (today). Capture covers every browser, every CLI tool, and every Electron app that respects the system proxy: Claude Desktop, ChatGPT desktop, Cursor, Windsurf, Claude Code, GitHub Copilot Chat, Gemini CLI, Codex CLI, Aider, Qwen Code, OpenCode — plus anything else reaching out to a known AI hostname over HTTPS.
• v2 — Network Extension mode (weeks away, auto-upgrade). Kernel-level capture via a macOS Network Extension. Adds coverage for VPN-routed traffic and any client that hard-codes its egress IP (rare today, but a growing pattern in newer AI agents). The same flowstate install command auto-promotes to NE mode once FlowstateAgent.app is present on disk — no separate flag, no separate workflow.

The v2 promotion is gated on Apple notarisation of FlowstateAgent.app. PAC mode covers the customer-facing AI tools the moment v1 lands; NE mode is the extra-belt-and-braces layer for the long tail.

Prerequisites

• macOS 13 Ventura or newer (Apple Silicon or Intel).
• Admin access on the target Mac (sudo for the install).
• An organisation key, provisioned at https://app.flowstate.inc/settings/ai/cloud-proxy. The key is a composite of your tenant slug and an API token — base64(tenantSlug:apiKey) — and routes your traffic to the right tenant on the cloud proxy. Issue it once at the org level; the same key goes on every device in the fleet.

Quick install — single machine

sudo flowstate install \
  --key="<your-org-key>" \
  --user="<user-email>"

That single command:

1. Generates a per-machine root certificate authority and installs it as a trusted root in the system keychain.
2. Configures macOS PAC (system proxy auto-config) to route AI provider hosts through the local daemon on 127.0.0.1:47813.
3. Drops a launchd plist at /Library/LaunchDaemons/inc.flowstate.agent.proxy.plist with FLOWSTATE_OTLP_KEY, FLOWSTATE_USER, FLOWSTATE_MODE=cloud-proxy, and FLOWSTATE_CLOUD_PROXY=https://ai.flowstate.inc populated.
4. Detects installed AI tools (Claude Code, Cursor, Codex CLI, Aider, …) and writes their per-tool OTLP exporter config so they emit native OpenTelemetry directly to the daemon — no PAC round-trip needed for those.
5. Starts the daemon and verifies it is listening.

The command is idempotent: re-run it after rotating the org key or changing the user email and it reconciles in place — no uninstall first.

Optional flags

Flag	When to use it
--host=<url>	Point at a non-default cloud proxy (regional EU endpoint, staging, on-prem mirror). Default: https://ai.flowstate.inc.
--no-app	Force HTTP/PAC mode and skip the FlowstateAgent.app + system extension install. Use on CI runners, headless macOS rigs, or any machine where you don't want a menubar app.
--with-pac	Register PAC even when the agent is running in Network Extension mode. NE captures everything PAC would, so PAC is off by default once NE is active; this flag forces both on.

The previous --transport flag has been removed. Pass --no-app instead if you want to opt out of the Network Extension path. Passing --transport returns an error that points at --no-app.

What this does to the machine

Path	Owner	Notes
/usr/local/bin/flowstate	root:wheel	The CLI.
/Library/LaunchDaemons/inc.flowstate.agent.proxy.plist	root:wheel	launchd unit. Started on first install, runs on every boot.
/etc/flowstate.env	root, 0600	Reads FLOWSTATE_OTLP_KEY, FLOWSTATE_USER, FLOWSTATE_CLOUD_PROXY. The plist's EnvironmentVariables block points at this file.
/Library/Flowstate/ca/	root:wheel	Per-machine root CA + leaf-cache.
/var/log/flowstate.proxy.log	root:wheel	Daemon log.
System keychain	—	Flowstate Agent CA added as a trusted root.
/Applications/FlowstateAgent.app	root:wheel	Present once NE mode lands and the bundle has been distributed (via .pkg or MDM). The CLI alone does not install the .app.

Verify the install

# 1. Daemon is loaded
sudo launchctl print system/inc.flowstate.agent.proxy | head -20

# 2. Recent activity in the daemon log
tail /var/log/flowstate.proxy.log

# 3. The system proxy resolves correctly
curl -v -x http://127.0.0.1:47813 https://claude.ai/ 2>&1 | head -10

Then open Claude Desktop or claude.ai in Chrome and use them as you normally would. Sessions appear under Settings → AI → Cloud Proxy and in the admin sessions view within a few minutes.

Deploy via Kandji (or other MDM)

For a managed fleet, deploy FlowstateAgent.pkg via your MDM's standard Custom App workflow. The .pkg lands the CLI binary + the launchd plist; a pre-install script seeds /etc/flowstate.env from MDM-supplied secrets so each device starts the daemon with the right key + user on first boot.

The full Kandji recipe — Custom App upload, the pre-install script that materialises /etc/flowstate.env from a Kandji Secret + the per-device $USER_EMAIL variable, audit script, and removal script — lives in the flowstate-agent repository at docs/mdm/kandji.md.

The same recipe applies to Jamf Pro, Mosyle, Intune for Mac, Workspace ONE, and JumpCloud with cosmetic differences (Custom App or Custom Profile, the per-tenant secret variable, the per-device email variable). The two things to wire up are always the same:

1. The .pkg payload (binary + launchd plist + CA install hook).
2. The pre-install script that writes /etc/flowstate.env with FLOWSTATE_OTLP_KEY, FLOWSTATE_USER, and (optionally) FLOWSTATE_CLOUD_PROXY for non-default endpoints.

The same .pkg works for both PAC mode (today) and NE mode (once notarisation lands) — Kandji does not need a separate recipe per mode.

Uninstall

sudo flowstate uninstall

One command, full reversal:

1. launchctl bootout the daemon and remove the plist.
2. Remove /etc/flowstate.env.
3. Remove the Flowstate Agent CA from the system keychain.
4. Revert the system PAC setting.
5. Roll back every per-tool config the installer wrote.

If the optional FlowstateAgent.app is on disk, uninstall leaves it in place by default (re-enabling is then a single flowstate install). Pass --purge-app to remove the bundle as well; macOS still requires the user to click "Uninstall extension" in the menubar to fully deactivate the Network Extension (an OS guardrail we cannot bypass).

The previous flowstate proxy install / flowstate proxy uninstall subcommands are gone; the new top-level install / uninstall are the only supported entry points.

Troubleshooting

See troubleshooting for the full triage flow. Quickest checks if sessions aren't appearing in Flowstate:

• Is the daemon running? sudo launchctl print system/inc.flowstate.agent.proxy | head
• Is the org key in /etc/flowstate.env the one you provisioned?
• Does the daemon log show 401 responses from the cloud proxy? Wrong key, or the key has been revoked in Settings → AI → Cloud Proxy.