Control endpoints
The control API uses JSON for its structured responses. It runs on the configured control.bind_address and a port two above the proxy listener. A token file, when configured and nonempty, makes every route require X-404-Control-Token. Never bind an unauthenticated control listener to a public interface.
Lifecycle and certificates
| Request | Current response or effect |
|---|---|
GET /status | { "mode": "proxy", "ready": true } when the proxy is ready; mode can also be control. |
POST /stop | { "stopping": true }; requests process shutdown. |
GET /ca/status | Certificate path, existence flag, and public cert_pem (empty if no file yet). |
POST /ca/init | Initializes CA material if needed and returns path, existence, and public PEM. |
The CA private key is not returned from these endpoints. Trust installation belongs to the host or operator. See TLS and certificates.
Profiles and telemetry
| Request | Current response or effect |
|---|---|
GET /profiles/catalog | active_profile and profiles array; entries include key, display name, family, variant, and platform. |
GET /profiles/active | Current active_profile or null. |
POST /profiles/select | Accepts { "profile": "chrome-windows" }; returns the selected active_profile, or 400 if unknown. |
POST /profiles/validate | Accepts { "profile": { … } }; returns { "warnings": [ … ] } for coherence issues. |
GET /telemetry/snapshot | { "events": [ … ] } from the bounded in-process buffer. |
Profile selection affects new Flows and triggers an attempted Linux packet map sync. The validation endpoint returns coherence warnings; it is not a substitute for the browser-policy contract/preflight and does not install the submitted profile. Telemetry snapshots are process-local, not durable. Inspect control.rs for the exact current schema and Profile anatomy for the profile data model.
Authentication and failure behavior
| Condition | Verified core behavior |
|---|---|
| Token path absent, or readable file trims to empty | No token requirement. |
| Configured token file unreadable | Control construction fails at startup. |
| Nonempty configured token; missing or wrong header | 403, with missing control token or invalid control token. |
| Token file edited while process runs | Token was loaded at construction; restart to reload it. |
Unknown profile in /profiles/select | 400; selection is not accepted. |
| CA initialization/read failure | CA routes can return 500. |
All nine routes call the token check. The port uses saturating proxy-port + 2, and the bind address is independently control.bind_address. Configuration defaults are in Configuration and launch.
TOKEN="$(cat /path/to/control-token)"
curl --fail-with-body \
-H "X-404-Control-Token: $TOKEN" \
http://127.0.0.1:4042/statusUse the actual token path/port and avoid posting tokens in support reports. The route contract is defined by the control implementation. API availability is separate from browser routing, certificate trust and page-runtime coverage.
someguy integration
The desktop renders runtime configuration and uses authenticated control requests for readiness, public CA retrieval, telemetry and profile discovery/selection. Managed profile caches verify exact manifest bytes, including inherited primitives, before replacing the runtime cohort. CA trust, system routing, cleanup and signed provisioning remain host responsibilities; core listener readiness does not certify these steps or browser privacy.
Shared state and readiness
app.rs constructs one ProfileStore, then shares it with the request pipeline and this listener. Proxy mode requires an explicit selected profile before startup. The ready flag reflects listener readiness, not proof that browser routing or certificate trust was installed. An active Flow retains the profile data it captured when its request was processed; later selection applies to new Flows. Already initialized browser realms retain their runtime policy until replaced or reloaded. Listener readiness does not certify runtime execution, individual surface coverage or privacy effectiveness. /telemetry/snapshot reads a bounded, in-process event buffer and is not a persistent audit log. See app.rs and telemetry.rs.