Troubleshooting

The shipped Cloud Proxy setup uses an org key plus an MDM proxy payload. Most issues come from one of three places: the org key was not deployed correctly, the device is not using the proxy, or the app has not refreshed its proxy environment yet.

Connection Status Stays Not Configured

No proxy-routed request has reached Flowstate for this organisation.

Check:

1. An active org key exists at Settings -> AI -> Cloud Proxy.
2. The MDM payload has been deployed to at least one device.
3. The MDM secret value contains the full reveal-once org key, not just the displayed prefix.
4. The device has restarted the relevant app or shell session since the payload landed.
5. NO_PROXY does not include the AI provider host you are testing.

Run a manual proxy check from the device:

curl -sS -i \
  --proxy "https://ai.flowstate.inc" \
  --proxy-user "person@example.com:<org-key>" \
  https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  | head -20

Use the user's real work email and the full org key value.

Connection Status Stays Pending

Pending means setup exists but Flowstate has not seen a successful first request yet.

Check:

• The test device can resolve and reach ai.flowstate.inc on port 443.
• The tool honors HTTP_PROXY or HTTPS_PROXY. Some desktop tools and CLIs bypass proxy environment variables.
• The user's email placeholder in the MDM payload is being substituted. A literal placeholder like ${USER_EMAIL} means the MDM did not fill it.
• The org key has not been rotated since the MDM payload was deployed.

If the request succeeds through the proxy but the page still shows Pending, refresh the page after a few minutes. The status card can fall back to a cached snapshot when the live meter is temporarily unavailable.

Proxy Auth Errors

Proxy authentication errors happen before the request is forwarded to the AI provider.

Common causes:

• The proxy password is not the full org key.
• The org key was re-provisioned but the MDM secret still has the old value.
• The Basic Auth username is missing or not an email.
• A shell escaped special characters in the proxy URL incorrectly.

Prefer --proxy-user for manual tests so the shell does not parse the key as part of the URL:

curl -sS -i \
  --proxy "https://ai.flowstate.inc" \
  --proxy-user "$FLOWSTATE_USER_EMAIL:$FLOWSTATE_ORG_KEY" \
  https://example.com \
  | head -20

A Tool Bypasses the Proxy

The Cloud Proxy only meters traffic that actually uses the proxy route.

If one tool is missing from the subject meter while curl works:

• restart the tool;
• check whether the tool has its own proxy setting that overrides environment variables;
• check whether it ignores system proxy settings entirely;
• remove broad NO_PROXY values;
• use the Flowstate Agent for tools that cannot be forced through HTTP_PROXY / HTTPS_PROXY.

TLS or Certificate Errors

The proxy endpoint uses public TLS at ai.flowstate.inc; managed devices should not need a custom Flowstate root certificate for the shipped proxy-metering flow.

If a tool reports a certificate error:

1. Update the tool runtime or base OS CA bundle.
2. Check whether a corporate secure web gateway is intercepting ai.flowstate.inc.
3. Add ai.flowstate.inc to the relevant allow-list or bypass list.

The Cloud Proxy does not require the device to trust a Flowstate-issued root certificate. The Flowstate Agent may require one for full capture modes; follow the agent install guide for that path.

No Detailed AI Sessions Appear

The shipped Cloud Proxy page shows connection status and subject request metering. It does not, by itself, create prompt-level session detail, prompt-quality scores, or content-DLP findings.

For detailed AI governance data:

• install the Flowstate Agent for endpoint capture;
• connect Usage providers for authoritative provider spend;
• use Telemetry vs Enterprise to decide whether prompt bodies are captured by the Agent.

Rotating the Org Key

Click Re-provision (rotate) on the Cloud Proxy page. Copy the new cleartext value into your MDM secret store and force a device sync.

Devices using the old key will fail proxy auth once the old key is revoked. If a subset of devices stops reporting after rotation, check that the MDM secret update reached that cohort.

Getting Help

Open a support ticket with:

• the affected organisation;
• the MDM vendor and payload tab used;
• whether a manual curl --proxy test works;
• the proxy-auth username format, with the org key redacted;
• the current connection status shown in Flowstate.