Proxy Documentation

TitaniumGuard Proxy is a QUIC relay plus a local desktop agent.

The client exposes loopback HTTP and SOCKS5 proxy ports for operating system or browser proxy settings. It authenticates to the relay with a bearer token over QUIC and trusts the relay certificate configured in its JSON file. The relay applies hostname blacklist policy, checks resolved addresses against safe egress defaults, opens allowed outbound internet TCP connections, and relays responses back to the client.

For a local demo, start bazelisk run //products/proxy/relay:relay first, then bazelisk run //products/proxy/client:client in another terminal under the same user. The relay creates private localhost TLS and bearer-token credentials automatically. Client HTTP and SOCKS5 listeners are loopback-only. Use explicit configuration for a remotely reachable relay.

Relay Image

The relay image is published as:

• ghcr.io/titaniumguardlabs/source/proxy/relay:latest

Run the relay with a single JSON config:

docker run --rm \
  -p 9443:9443/udp \
  -v "$PWD/proxy-relay.json:/etc/titaniumguard/proxy-relay.json:ro" \
  -v "$PWD/proxy-relay.crt:/etc/titaniumguard/proxy-relay.crt:ro" \
  -v "$PWD/proxy-relay.key:/etc/titaniumguard/proxy-relay.key:ro" \
  ghcr.io/titaniumguardlabs/source/proxy/relay:latest \
  --config /etc/titaniumguard/proxy-relay.json

Local Agent

Run the client on desktop machines:

proxy-client --config /etc/titaniumguard/proxy-client.json

Configure HTTP and HTTPS proxy settings to the client http_listen address. Configure SOCKS5 settings to the client socks_listen address.

HTTPS uses normal CONNECT tunneling. The client does not intercept TLS.

Every proxied stream receives a relay-generated UUID v7 interaction ID. HTTP responses include it as x-tg-proxy-id for troubleshooting and correlation.

Relay hostname blacklist matches return HTTP 403 Forbidden responses for HTTP proxy traffic and connection-not-allowed replies for SOCKS5 traffic.

Operations

Relay and client configs can expose loopback health endpoints:

• /live
• /ready
• /metrics

Readiness turns unavailable during shutdown drain. Relay egress denies private and special-use address ranges by default, and client proxy listeners must bind to loopback addresses.