How It Works
ProxAI Gateway is a single self-contained binary that runs as a managed background service on your machine. It does not intercept HTTP traffic, install a proxy, or attach to any agent process — every byte it sends originates from on-disk session files your coding agents already write themselves.
The capture pipeline
Every record moves through the same steps, all of them on your machine:
- Read — the gateway discovers the session files of supported coding agents and reads only the content added since the previous cycle. Per-file progress markers (watermarks) make capture resumable: nothing is read twice, and nothing is skipped after a restart.
- Filter — a per-agent filter keeps only genuine dialogue content and trims oversized or non-dialogue fields.
- Redact — an on-device rule pipeline strips API keys, tokens, and other secrets before anything is stored. See Data & Privacy for the full rule categories.
- Compress and buffer — the redacted records are compressed and written to a local SQLite buffer.
- Upload — the uploader drains the buffer in batches to ProxAI. Failed uploads stay in the buffer and are retried.
The background daemon
The daemon runs three independent loops:
| Loop | Cadence | Job |
|---|---|---|
| Capture | every 2 minutes | Read new agent activity, redact, compress, and buffer it |
| Drain | every 30 seconds | Upload buffered batches to ProxAI and retry earlier failures |
| Heartbeat | hourly | Check for new gateway releases and keep upload progress in sync |
The daemon is registered with your operating system’s service manager during
setup, so it starts automatically when you log in:
| Platform | Service mechanism |
|---|---|
| macOS | launchd launch agent (runs at login) |
| Linux | systemd user service |
| Windows | Task Scheduler task (runs at logon) |
Use start, stop, and restart
to control the daemon manually.
Offline-first by design
The gateway never loses data to a flaky connection. If your machine is offline or ProxAI is unreachable, captured records simply accumulate in the local buffer and upload resumes automatically once connectivity returns. The buffer pauses new capture if it grows past 50 GiB and resumes once it drains below 45 GiB — both thresholds are configurable.
Staying up to date
You can upgrade manually at any time with
proxai-gateway upgrade. The daemon also
checks for new releases on its own: by default it logs a warning once the
binary is 30 days old and upgrades itself automatically at 60 days, so you
keep receiving new agent support and redaction rules without re-installing.
Both thresholds can be tuned or disabled in the
configuration file.