Troubleshooting

A handful of issues account for >90% of agent installation problems. This page walks each one from symptom to fix.

"I don't see any sessions"

Most common cause. Work the checklist in order; stop at the first failure.

1. Is the agent running?

# macOS
sudo launchctl print system/inc.flowstate.agent.proxy | head -20

# Linux
systemctl status flowstate-agent

# Windows
Get-Service FlowstateAgent | Format-List Status, StartType

Expect Status: Running (or equivalent). If it's not running, the OS supervisor's log will tell you why (typically a missing FLOWSTATE_OTLP_KEY or FLOWSTATE_USER).

2. Does it have an org key and a user email?

# macOS / Linux
sudo cat /etc/flowstate.env

# Windows
Get-ItemProperty -Path "HKLM:\SOFTWARE\Flowstate\Agent" |
  Select-Object FLOWSTATE_OTLP_KEY, FLOWSTATE_USER, FLOWSTATE_CLOUD_PROXY

Both FLOWSTATE_OTLP_KEY and FLOWSTATE_USER must be populated. If the key is missing, doesn't match a real key under Settings → AI → Cloud Proxy, or has been revoked, the agent's log will show repeated 401 unauthorized lines from ai.flowstate.inc. Fix by reconciling the value in-place and reloading:

# macOS
sudo flowstate install --key="<new-key>" --user="<email>"

# Linux
sudo flowstate install --key="<new-key>" --user="<email>"

# Windows (elevated PowerShell)
& "C:\Program Files\Flowstate\flowstate.exe" install `
    --key="<new-key>" --user="<email>"

flowstate install is idempotent — re-running it reconciles the existing install without an uninstall first.

3. Can the agent reach the cloud proxy?

curl -sI https://ai.flowstate.inc/healthz

Should return HTTP/2 200. If it doesn't, your egress proxy is blocking it. See corporate proxies — ai.flowstate.inc needs to be allow-listed, and SWGs that buffer streaming responses or break WebSocket upgrades need it on their inspection-bypass list.

4. Is AI traffic going through the agent?

The agent inspects what it can see. If a tool routes around the system proxy (a personal Cursor install pointing at a personal upstream, a CLI hardcoded to bypass system proxy), the agent never sees the traffic.

PAC mode catches everything that honours the system proxy. Once Network-Extension mode lands on macOS (see What you get on macOS), it'll catch the rest as well.

5. Has the agent flushed yet?

Sessions buffer briefly before flushing. If you just sent a prompt, wait a minute, then:

# macOS
sudo tail -f /var/log/flowstate.proxy.log | grep "session forwarded"

# Linux
journalctl -u flowstate-agent -f | grep "session forwarded"

# Windows
Get-Content "C:\ProgramData\Flowstate\logs\agent.log" -Wait |
  Select-String "session forwarded"

TLS errors — "certificate not trusted"

flowstate install installs the per-machine root CA in the system trust store. If you see TLS errors from your AI tools, the CA install failed or the tool is reading from a private trust store.

macOS — verify and re-install

# Verify trust
sudo security find-certificate -c "Flowstate Agent CA" /Library/Keychains/System.keychain

# Re-install — `flowstate install` is idempotent and reconciles the CA.
sudo flowstate install --key="<key>" --user="<email>"

Windows — verify and re-install

# Verify trust
Get-ChildItem -Path Cert:\LocalMachine\Root | Where Subject -Match "Flowstate"

# Re-install
& "C:\Program Files\Flowstate\flowstate.exe" install --key="<key>" --user="<email>"

Linux — verify and re-install

# Debian / Ubuntu
ls /usr/local/share/ca-certificates/flowstate-agent.crt
sudo update-ca-certificates

# Fedora / RHEL / Amazon Linux
ls /etc/pki/ca-trust/source/anchors/flowstate-agent.crt
sudo update-ca-trust

# Or, the cleanest path: let the installer reconcile.
sudo flowstate install --key="<key>" --user="<email>"

CLI tools with their own bundle. Python's requests uses certifi unless you tell it otherwise; Node's https defaults to its bundled CA list; Go's crypto/tls reads the system trust store on Linux but not on every platform. If only one tool sees the cert error, point it at the system store:

• Python: export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
• Node: export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

Streaming responses cut off mid-stream

The v1.12.1 release (2026-05-15) fixed a server-side bug in the agent's WebSocket forwarding through PAC mode — Claude Desktop streaming now works end-to-end via ALPN pinning. If you're still seeing mid-stream cut-offs:

1. Confirm the agent version.

flowstate --version
# Expect: v1.12.1 or newer.

If you're on an older line, re-run sudo flowstate install against the current binary — it picks up the new version's behaviour automatically.

2. Confirm your SWG isn't buffering streaming responses.

Many SWGs buffer SSE / WebSocket responses to inspect them in full before forwarding. Add the provider hostnames to your SWG's inspection-bypass list. See corporate proxies for the full list — short answer: api.anthropic.com, claude.ai, chatgpt.com, api.openai.com, copilot-proxy.githubusercontent.com.

macOS-specific: Network Extension mode (v2, ~weeks away)

The v2 capture path on macOS uses FlowstateAgent.app + a NETransparentProxyProvider system extension. Today, the .app is shipped unsigned in CI builds and is gated on Apple notarisation before we promote the v2 path for customers. Until notarisation lands, every macOS install runs in PAC mode (v1) — which covers every browser, CLI, and Electron client we know about.

If you see these symptoms on a Mac with FlowstateAgent.app present:

• macOS shows "System Extension Blocked" on first launch of the .app. → Approve once via System Settings → Privacy & Security → Allow, or push an MDM SystemExtensions allowlist payload to pre-approve our Team ID. The Kandji recipe at flowstate-agent/docs/mdm/kandji.md walks the MDM payload step by step.
• systemextensionsctl list shows the extension as waiting for user and never advances. → Same fix as above — the user (or an MDM payload) has to approve.
• systemextensionsctl list shows absent after flowstate install. → The .app is not on disk, or it isn't notarised in this build. Pass --no-app to flowstate install to force PAC mode, which works today.

When v2 is generally available, every existing install auto-promotes on the next flowstate install run — there is no separate migration.

flowstate install fails with "unknown flag --transport"

The --transport flag was removed in v1.12. The installer auto-selects the right capture path per platform:

• macOS: NE mode if FlowstateAgent.app is present, PAC mode otherwise.
• Linux: PAC mode always.
• Windows: WinDivert mode always.

If you were passing --transport=pac to force PAC mode on macOS, replace it with --no-app. The installer's error message says the same thing.

"flowstate proxy install" returns an error

The proxy install and proxy uninstall subcommands are gone. Use the top-level commands:

sudo flowstate install --key="<key>" --user="<email>"
sudo flowstate uninstall

There is no migration step — the top-level commands accept the same args and reconcile any in-place install written by the legacy subcommands.

Log locations

Platform	Path	How to tail
macOS	/var/log/flowstate.proxy.log	sudo tail -f /var/log/flowstate.proxy.log
Linux	journald (systemd unit flowstate-agent)	journalctl -u flowstate-agent -f
Windows	C:\ProgramData\Flowstate\logs\agent.log	Get-Content -Wait -Path 'C:\ProgramData\Flowstate\logs\agent.log'

Change the log path with FLOWSTATE_LOG_PATH. Raise verbosity with FLOWSTATE_LOG_LEVEL=debug for one-off debugging.

Getting help

Before opening a support ticket, please run:

flowstate support-bundle

This produces a redacted bundle containing:

• The last 500 lines of the agent log.
• The effective configuration (env vars + per-platform managed config).
• Connectivity test results for ai.flowstate.inc and the GitHub Releases CDN .
• The agent's version, OS, and architecture.

It does not include any captured AI traffic, prompts, responses, org keys, or cookies. Attach the bundle to your support ticket — it's enough for us to triage most issues without further round-trips.