Proxy Modes

The proxy operates in one of three modes depending on agent requirements.

UDS Mode

For cooperative agents built with Hull0 protocol support.

Agent ──────► Unix Socket ──────► Proxy ──────► Internet
         JSON protocol

Agent connects to /tmp/hull0-proxy.sock and sends JSON requests:

{
  "capability": "openai-chat",
  "method": "POST",
  "url": "https://api.openai.com/v1/chat/completions",
  "headers": {"Content-Type": "application/json"},
  "body": "{...}"
}

Proxy validates against manifest, executes request, returns response.

Advantages:

  • Fine-grained capability matching
  • Secret injection into headers
  • Taint tracking across requests

Use when: Building new agents or modifying existing ones.

Transparent Mode

For unmodified agents. Network traffic is intercepted via iptables.

Agent ──────► veth ──────► iptables DNAT ──────► Proxy ──────► Internet
         TCP/TLS                              TLS SNI

Sandbox has a veth pair. All outbound TCP is redirected to proxy port 9999. Proxy extracts destination from:

  • SO_ORIGINAL_DST socket option (original IP:port)
  • TLS SNI extension (hostname for HTTPS)

Matches against network.outbound rules in manifest.

Advantages:

  • No agent modification required
  • Works with any TCP application

Limitations:

  • Domain-level granularity only
  • No secret injection
  • Limited taint tracking

Use when: Running existing applications without modification.

Vsock Mode

For Firecracker microVM sandboxes.

Agent (guest) ──────► AF_VSOCK ──────► Proxy (host)
                    CID:port

Uses virtio-vsock for guest-to-host communication. Same JSON protocol as UDS mode.

Use when: High-isolation requirements (paid tier).