Agent policy

Agent policy is the set of runtime knobs that govern every Flowstate Agent in your organisation. Set them once in Settings → AI → Agent Policy; the agents pick them up on their next poll.

The policy covers seven things:

Setting	What it controls
Capture mode	Telemetry (metadata only) vs Enterprise (full prompts + responses).
Update policy	What the in-agent auto-updater is allowed to do.
Update channel	Stable or beta.
Maintenance window	When auto-updates may install.
Pinned version	Hold the fleet on a specific version.
Upstream proxy	If your egress is routed through a corporate proxy.
Enforcement	Observe-only vs block-at-request-time.

Capture mode

The high-level pathway you're on. See Telemetry vs Enterprise for the side-by-side comparison.

Flip it from the toggle on the policy page. The change propagates to the fleet on next poll; engineers don't need to restart anything.

Update policy

Forward-looking

The in-agent auto-updater is a forward-looking surface — see auto-updates for the current transitional state. Today, upgrading is a manual re-run of flowstate install (which is idempotent). The policy modes below describe how the updater will behave once Sparkle ships on macOS and the equivalent scheduled-update path ships on Linux + Windows.

What the in-agent auto-updater is allowed to do, once it ships:

Mode	Behaviour
auto (default)	Install newer versions automatically when the maintenance window is open.
notify-only	Surface "update available" in the agent status; never install. Useful for compliance-driven shops that audit every binary.
manual	Same as notify-only, plus an agent.update.available event is sent so a Flowstate dashboard surfaces it for the admin to action.
disabled	Don't poll. Use only when an alternative update mechanism owns the agent (e.g. Munki, Intune Win32 app push, internal mirror).

Update channel

Two release tracks:

• stable (default) — production releases. Versioned vN.M.K.
• beta — pre-release builds, typically 1–2 weeks ahead of stable. Versioned vN.M.K-beta.X.

The beta channel is opt-in. We recommend pinning a small pilot group of internal machines to beta, and leaving the rest of the fleet on stable.

Maintenance window

When auto-policy installs are allowed to fire. Format: DOW HH:MM-HH:MM (24-hour clock, local time on the machine).

• Sun 02:00-04:00 — Sunday early hours only.
• Any 23:00-02:00 — every day overnight (crosses midnight, both sides valid).
• Empty — any time. Default.

Pinned version

Set to e.g. v1.2.3 to hold the fleet on that exact version regardless of channel. The auto-updater never moves up or down from a pinned value.

Use cases:

• You're running a customer-specific build and need predictability.
• A new release introduced a regression and you want every machine back on the previous version while you investigate.
• You want a slow rollout: pin to N-1 on most of the fleet, leave a smaller group unpinned.

Clear the pin (empty value) to let the channel resume control.

Upstream proxy

If your organisation routes all egress through a corporate proxy (Zscaler, Forcepoint, Palo Alto Prisma Access, Netskope, etc.), set the URL here. The agent will dial through it for both telemetry submission and update downloads.

Format: http://proxy.example.com:8080 (or https://, with optional user:pass@).

The corporate proxies page covers the full integration picture, including which hostnames you may want your proxy to allow-list.

Enforcement

Off (default) — the agent observes traffic and forwards it; the user's request reaches the provider unchanged.

On — the agent applies the active AI policy at request time. Requests that violate a rule (banned model, monthly cap exceeded, missing cost-centre attribution, etc.) are blocked with a structured error the user's tool surfaces in their UI.

Enforcement is the irreversible step you take after you've watched the data flowing in observe-only mode for a few weeks and you trust what you're going to enforce. Once on, the agent becomes part of the request path — uptime matters, latency matters.

Where the policy comes from

The agent reads its effective policy in this precedence order (highest wins):

1. Local env var — FLOWSTATE_LOG_LEVEL=debug set on a single machine for debugging.
2. Per-platform managed config — /etc/flowstate.env (macOS / Linux) or HKLM\SOFTWARE\Flowstate\Agent (Windows), written by flowstate install from the values your MDM passed in.
3. Flowstate-managed policy — what an admin set in the UI at Settings → AI → Agent Policy.
4. Built-in defaults — observe enforcement, cloud-proxy mode, no pinned version.

The Flowstate-managed policy is the source of truth for fleet-wide behaviour; the MDM-pushed values exist so IT teams can override on a per-machine basis (debug box, build farm, dev environment).

What happens when the agent is offline

The agent caches its last-known policy locally. If the daily poll fails (no connectivity, server unreachable), the agent keeps operating with the previous values until the next successful poll. There's no fail-open / fail-closed behaviour to choose: the agent never reaches more permissive defaults on a failure, only the values it last successfully retrieved.

Audit trail

Every change to the policy is recorded with a timestamp, the user who made it, and the diff (before → after). Visit Settings → AI → Agent Policy → History to see the trail.