Install on Linux

The Flowstate Agent on Linux is a single statically-linked Go binary (/usr/local/bin/flowstate) plus a systemd unit that runs the proxy daemon. On Linux there is no kernel-level capture path — the agent runs in PAC mode only and intercepts AI traffic via a per-machine HTTPS proxy that the system trusts. Browsers, CLIs and Electron apps that honour the standard proxy environment variables (HTTP_PROXY / HTTPS_PROXY / system proxy settings) flow through it cleanly.

Distributions validated end-to-end: Ubuntu 22.04+, Debian 12+, Fedora 39+, Amazon Linux 2023, NixOS 23.11+.

Prerequisites

• Linux x86-64 or arm64.
• Root on the target host (sudo).
• 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.

Quick install — single machine

Download the binary, drop it on $PATH, and run the one-shot installer:

ARCH=$(uname -m); [ "$ARCH" = "x86_64" ] && ARCH=amd64 || ARCH=arm64

# Until the binaries.flowstate.inc CDN is updated to point at the v1.12 line,
# pull from the GitHub Releases page on meetflowstate/flowstate-agent.
# <!-- TODO: switch to https://binaries.flowstate.inc once that site is updated -->
RELEASE_URL="https://github.com/meetflowstate/flowstate-agent/releases/latest/download/flowstate_linux-${ARCH}.tar.gz"

curl -fsSL -o /tmp/flowstate.tar.gz "$RELEASE_URL"
sudo tar -xzf /tmp/flowstate.tar.gz -C /usr/local/bin
sudo chmod +x /usr/local/bin/flowstate

# One-shot install: CA, systemd unit, /etc/flowstate.env, PAC, per-tool config.
sudo /usr/local/bin/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 (/usr/local/share/ca-certificates/ on Debian/Ubuntu, /etc/pki/ca-trust/source/anchors/ on Fedora/RHEL/Amazon Linux) and runs update-ca-certificates / update-ca-trust as appropriate.
2. Writes /etc/flowstate.env with FLOWSTATE_OTLP_KEY, FLOWSTATE_USER, FLOWSTATE_MODE=cloud-proxy, and FLOWSTATE_CLOUD_PROXY=https://ai.flowstate.inc.
3. Drops a systemd unit at /etc/systemd/system/flowstate-agent.service and enables + starts it.
4. Registers a PAC URL on the system proxy settings so browsers and *_PROXY-aware CLIs route AI hostnames through 127.0.0.1:47813.
5. Detects installed AI tools (Claude Code, Cursor, Codex CLI, Aider, …) and writes their per-tool OTLP exporter config.

The command is idempotent: re-run it after rotating the org key, changing the user email, or upgrading the binary, and it reconciles in place.

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	No-op on Linux — there is no host app on Linux. Pass it freely if you share an install script across platforms.

The previous --transport flag is gone. Passing it returns an error that directs you at --no-app (which, on Linux, is the only mode). The flowstate proxy install / flowstate proxy uninstall subcommands have also been removed; use the top-level install / uninstall.

What this does to the machine

Path	Owner	Notes
/usr/local/bin/flowstate	root:root	The CLI + daemon.
/etc/systemd/system/flowstate-agent.service	root:root	systemd unit, EnvironmentFile=/etc/flowstate.env.
/etc/flowstate.env	root, 0600	FLOWSTATE_OTLP_KEY, FLOWSTATE_USER, FLOWSTATE_CLOUD_PROXY.
/var/lib/flowstate/ca/	root:root	Per-machine root CA + leaf-cache.
System trust store	—	Flowstate Agent CA added (via update-ca-certificates or update-ca-trust).

The daemon logs to journald: journalctl -u flowstate-agent -f.

Verify the install

# 1. Daemon is running
systemctl status flowstate-agent

# 2. Recent activity in the journal
journalctl -u flowstate-agent -n 50 --no-pager

# 3. Sessions forwarded to the cloud proxy
journalctl -u flowstate-agent | grep -i "session forwarded"

Then use any AI tool that honours the system proxy (curl with HTTPS_PROXY, a browser, Claude Code on the same host) and watch sessions appear under Settings → AI → Cloud Proxy in Flowstate.

Fleet rollout — Ansible

- name: Install flowstate-agent
  hosts: dev_workstations
  become: yes
  vars:
    flowstate_version: "v1.12.1"        # (v1.12.1, 2026-05-15)
    flowstate_org_key: "{{ vault_flowstate_org_key }}"
  tasks:
    - name: Resolve architecture
      set_fact:
        flowstate_arch: "{{ 'amd64' if ansible_architecture == 'x86_64' else 'arm64' }}"

    - name: Download release tarball
      # <!-- TODO: switch to https://binaries.flowstate.inc once that site is updated -->
      get_url:
        url: "https://github.com/meetflowstate/flowstate-agent/releases/download/{{ flowstate_version }}/flowstate_linux-{{ flowstate_arch }}.tar.gz"
        dest: /tmp/flowstate.tar.gz
        mode: '0644'

    - name: Extract binary
      unarchive:
        src: /tmp/flowstate.tar.gz
        dest: /usr/local/bin
        remote_src: yes
        mode: '0755'

    - name: Run one-shot install
      command: >
        /usr/local/bin/flowstate install
          --key={{ flowstate_org_key }}
          --user={{ ansible_user_id }}@{{ corporate_domain }}
      # `flowstate install` is idempotent — safe to run on every play.

The Ansible play deliberately does not template a systemd unit by hand; flowstate install writes the unit and reconciles it on every run. That keeps the recipe small and the unit owned by a single source of truth.

Fleet rollout — Puppet

class flowstate_agent (
  String $version             = 'v1.12.1',     # (v1.12.1, 2026-05-15)
  Sensitive[String] $org_key  = undef,
  String $user_email          = undef,
) {
  $arch = $facts['architecture'] ? {
    'x86_64' => 'amd64',
    default  => 'arm64',
  }

  # <!-- TODO: switch to https://binaries.flowstate.inc once that site is updated -->
  archive { '/tmp/flowstate.tar.gz':
    ensure       => present,
    source       => "https://github.com/meetflowstate/flowstate-agent/releases/download/${version}/flowstate_linux-${arch}.tar.gz",
    extract      => true,
    extract_path => '/usr/local/bin',
    creates      => '/usr/local/bin/flowstate',
  }

  exec { 'flowstate-install':
    command => "/usr/local/bin/flowstate install --key=${org_key.unwrap} --user=${user_email}",
    unless  => "/usr/local/bin/flowstate verify",
    require => Archive['/tmp/flowstate.tar.gz'],
  }
}

The unless clause uses flowstate verify to make the exec idempotent on re-runs.

Uninstall

sudo flowstate uninstall

Reverses every step the installer performs:

1. systemctl disable --now flowstate-agent and remove the unit file.
2. Remove /etc/flowstate.env.
3. Remove the Flowstate Agent CA from the system trust store and re-run update-ca-certificates / update-ca-trust.
4. Revert the system PAC setting.
5. Roll back every per-tool config the installer wrote.

The Go binary at /usr/local/bin/flowstate is left in place so re-enabling is a single flowstate install. Delete it manually if you're decommissioning the host entirely.

Troubleshooting

See troubleshooting. For Linux specifically:

• Cert errors from a CLI tool: the tool is reading from a private trust store (Python's certifi, Node's bundled CA list, etc.) and not the system trust store. Either point the tool at the system CAs (REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt for Python) or add the Flowstate CA into the tool's own bundle.
• journalctl shows 401 unauthorized: the org key in /etc/flowstate.env doesn't match what's in Settings → AI → Cloud Proxy. Rotate the key in the UI, then re-run flowstate install --key=<new-key> --user=<email> to reconcile.