Connection troubleshooting.

Where Fleet shows connection state

• Gateways tab / Gateway Detail ▸ Connection — per-gateway health and connection/capability details.
• Gateway Detail — identity, contextual connection controls, and the machine's Needs You item.
• Fleet ▸ Needs You — lists already-observed actionable items, which include classified gateway authentication and configuration failures.
• Fleet ▸ Connection activity — recent connection activity.

Can't connect / gateway unreachable

• Check the endpoint URL — scheme, host, and port, exactly as your gateway operator provided it.
• Check the network path. Your iPhone must reach the gateway over the same network path used when it was set up.
• Local-network permission (iOS): if your gateway is on the local network, iOS asks whether to allow Fleet to find and connect to local-network devices.
• Cleartext http:// on raw IPs: Fleet ships no per-host exceptions for cleartext; iOS App Transport Security rules apply. The preferred fix is a secure (HTTPS) gateway endpoint.
• Check the gateway side: is the gateway process running, is remote access enabled, is a firewall or reverse proxy in front of it?
• Tunnel/VPN differences: confirm the tunnel is up on the iPhone and that the gateway host resolves the same way as during setup.

Authentication failures (per strategy)

• None — nothing to authenticate. If this fails, the gateway is likely misconfigured.
• Session token — token expired or revoked on the gateway: obtain a fresh dashboard-compatible token and update the stored credential.
• Loopback token — the token must be configured for trusted-network access; re-copy it if rotated on the gateway.
• Username + password — password changed on the gateway, or the account is locked: update the pair in the app.
• Bearer token — appears in the strategy vocabulary but is reserved for future gateway support; it is not usable in this beta.

"Capability unavailable" errors are expected behavior

Some features depend on methods exposed by the connected Hermes gateway version. If the gateway does not advertise a method, the feature fails closed with an explicit unavailable/error state — it is never fabricated as working. This is deliberate, not a bug.

Reconnect, replay, and offline expectations

• Mid-conversation disconnects: Fleet reconnects and recovers missed events.
• Temporary disconnects: recently viewed screens stay usable from device-local cached snapshots.
• Cache age/limits: local cached data remains until expired by the app's bounded cache policy or removed by user cache controls.

Reporting a problem safely

• Never include credentials, tokens, private gateway addresses, pairing QR contents, or conversation transcripts in a public issue.
• Bugs → use the GitHub issue tracker.
• Security vulnerabilities → privately per SECURITY.md.

For setup and connection questions, see the FAQ →