Proxies.ai

How It Works

Request flow through Hyperproxy from client to upstream.

This page walks through exactly what happens when a request passes through Hyperproxy — from your client to the upstream API and back.

Auto-Auth Mode Flow

Scroll horizontally to read the diagram.

Show diagram source
sequenceDiagram
    participant Client
    participant Proxy as Hyperproxy
    participant Upstream as Upstream API
    Client->>Proxy: CONNECT api.openai.com
    Note over Client,Proxy: Proxy authentication user:pass
    Note over Proxy: Authenticate using auth DB
    Client->>Proxy: GET /v1/models with Authorization Bearer {$OPENAI_API_KEY}
    Note over Proxy: Resolve {$OPENAI_API_KEY} from encrypted SQLite
    Proxy->>Upstream: GET /v1/models with injected Authorization Bearer sk-proj-real-key
    Upstream-->>Proxy: 200 OK
    Proxy-->>Client: 200 OK

The real key never touches your client. The client only ever sees its proxy credential (username + password) and the response from the upstream.

When a credential vault with a service binding exists for the request host, ICAP resolves the vault-scoped secret and injects it into the configured header automatically. If no binding matches, no credential is injected.

Firewall Mode Flow

Firewall mode adds TLS interception and CEL rule evaluation:

Scroll horizontally to read the diagram.

Show diagram source
sequenceDiagram
    participant Client
    participant Proxy as Hyperproxy
    participant Upstream as Upstream API
    Client->>Proxy: CONNECT api.stripe.com
    Note over Proxy: Issue certificate for api.stripe.com signed by Hyperproxy mitmproxy CA
    Proxy-->>Client: TLS handshake using Hyperproxy CA certificate
    Client->>Proxy: POST /v1/charges, plain HTTP inside TLS
    Note over Proxy: CEL request.host=="api.stripe.com" && request.method=="POST", action ALLOW
    Note over Proxy: Inject credentials into Authorization Bearer sk_live_real_key
    Proxy->>Upstream: POST /v1/charges with injected Authorization header
    Upstream-->>Proxy: 200 OK
    Proxy-->>Client: 200 OK

Proxy Authentication

Hyperproxy's authentication layer validates the proxy Proxy-Authorization header against the credential store on each connection. Each credential is:

  • Unique to a proxy (username encodes the proxy ID)
  • Independently revocable without affecting other credentials
  • Optionally scoped to specific proxy ports
  • Optionally expiring

Secret Resolution

Hyperproxy's credential injection layer intercepts every outgoing request header before forwarding. It scans header values for ${VAR_NAME} patterns, looks up the decrypted value from the encrypted store, and rewrites the header in-flight.

Secrets are stored encrypted with AES-256-GCM using a per-proxy key provisioned at creation time. The key never touches disk and never appears in logs.

CEL Rule Evaluation (Firewall Mode)

CEL rules are evaluated in priority order (lower number = higher priority). The first matching rule's action is applied:

  • allow — request proceeds normally
  • deny — Hyperproxy returns 403 immediately; request is logged
  • hitl — request is held; a notification appears in the dashboard; the operator approves or denies within the timeout window

If no rule matches, the request is allowed by default. Add a catch-all deny rule at low priority (e.g. priority 9999) to flip this to deny-by-default.