apus proxy

Validate operator-managed proxy routing, or run the local explicit debug proxy and inspect captured traffic.

apus proxy validate [--json] [--proxy-url <url>] [--proxy-ca-file <path>] [--allowed-url <url>] [--denied-url <url>] [--apns-reachable] [--apns-authority <url>] [--timeout-ms <ms>]
apus proxy start [--host <host>] [--port <port>]
apus proxy run [--host <host>] [--port <port>] -- <cmd...>
apus proxy coverage [--json]
apus proxy sessions [--limit <count>] [--json]
apus proxy query --preset <name> [--session <id>] [--json]
apus proxy blob --id <blobId>
apus proxy purge

validate preflights an operator-managed forward proxy. The rest are debugging tools for transport-level investigation: start a local capturing proxy, run a child command through it, list capture sessions, query traffic patterns, read captured blobs, and purge local capture data.

Validate

Checks the effective operator-managed proxy URL from --proxy-url, config (proxy.proxyUrl), or APUS_PROXY_URL, in that precedence order. Reports a config problem if no proxy is enabled and configured. Pass --proxy-url for a one-off preflight without touching config.

Managed proxy URLs use http:// for a plain forward-proxy listener, or https:// when Apus must open TLS to the proxy endpoint itself before sending proxy requests. Use --proxy-ca-file to trust a private CA for that TLS connection.

By default it runs:

Custom --denied-url targets are fail-closed: both HTTP responses and ambiguous transport failures count as failures unless you can independently verify a deployment-specific denial signal. The built-in loopback canary is the only target where a transport error is treated as proof of blocking.

Add --apns-reachable to also open an APNs HTTP/2 CONNECT tunnel through the proxy and confirm sandbox APNs responds. The check sends an intentionally invalid provider token, so an APNs 403 InvalidProviderToken response counts as a successful reachability signal (not a failure).

Options

Flag Effect
--json print machine-readable JSON
--proxy-url <url> validate this http:///https:// proxy URL instead of config or env
--proxy-ca-file <path> trust this PEM CA file for TLS verification of an HTTPS proxy endpoint
--allowed-url <url> destination expected to succeed through the proxy (repeatable)
--denied-url <url> destination expected to be blocked by the proxy (repeatable)
--apns-reachable also verify sandbox APNs HTTP/2 is reachable through the proxy
--apns-authority <url> APNs authority to check (default https://api.sandbox.push.apple.com; production is https://api.push.apple.com)
--timeout-ms <ms> per-request timeout

Exits with code 1 when proxy config or destination checks fail.

See Network Proxy for deployment guidance and denial semantics.

Debug proxy

start launches a local capturing proxy and prints its URL, CA cert path, and capture DB path. Stop it with Ctrl+C. Defaults to binding 127.0.0.1 unless --host is set.

run starts a local debug proxy, then runs <cmd...> (after --) with the proxy env applied, under its own capture session.

Capture persistence uses asynchronous worker operations. On orderly shutdown, start and run wait for admitted capture writes and session cleanup. Capture failures remain reportable during cleanup even when the original HTTP response was already delivered to its caller.

Integrations using the proxy capture SDK must await capture finalization and release their async store leases. Direct database maintenance close invalidates capture admission and is not a substitute for that cleanup; the synchronous finalizer cannot drain async capture work.

The debug proxy's direct upstream forwarding opens upstream sockets for diagnostics. When Apus managed proxy mode is active, direct forwarding for proxy requests and CONNECT tunnels is disabled by default. Set APUS_DEBUG_PROXY_ALLOW_DIRECT_CONNECT_WITH_MANAGED_PROXY=1 only for approved local diagnostics.

coverage prints a JSON report (summary + per-transport entries) of which transports are captured, proxy-only, or uncovered.

sessions lists recent capture sessions (--limit, default 20).

query --preset <name> runs a built-in query against captured traffic, optionally scoped to --session <id>. Presets:

coverage, sessions, and query already return JSON by default. They also accept --json as an explicit machine-output spelling for consistent scripts. In that mode, coverage keeps its report object, while sessions and query wrap their rows under sessions and rows, respectively.

blob --id <blobId> prints a captured payload blob's raw content.

purge deletes all captured traffic metadata and blobs. Captures are local debugging data. Purge them when you finish.

Related