Network proxy path

The SDK is great when you control the agent’s code. When you don’t — a third-party tool, a browser-driven agent, an MCP server you didn’t write — the network proxy path is what you want. No code changes; just set one env var.

How it works

1. The agent’s process has HTTPS_PROXY=http://lupid:7070 in its environment.
2. Every outbound HTTPS request issues a CONNECT to Lupid first.
3. Lupid authenticates the agent (JWT + revocation check), mints a leaf cert on the fly from its local CA, presents that cert to the agent’s TLS client.
4. The agent’s TLS client trusts the cert because Lupid’s CA root is mounted into the agent’s trust store.
5. Lupid sees the decrypted bytes, runs the enforcement pipeline (policy + DLP), then forwards the request upstream.

Setup

1. Make sure the agent runs inside the docker network. The HTTPS-CONNECT gateway is bound to the docker network, not the host. If your agent runs as a separate compose service, set:

   services:
     my-agent:
       # ... your agent image ...
       environment:
         HTTPS_PROXY: http://lupid:7070
         HTTP_PROXY:  http://lupid:7070
       networks:
         - lupid_default
       depends_on:
         lupid:
           condition: service_healthy
   
   networks:
     lupid_default:
       external: true
       name: lupid_default

2. Mount the CA root into the agent’s trust store. The gateway generates its CA at startup and stores it in the agentum-certs named volume. Mount it read-only:

   services:
     my-agent:
       volumes:
         - agentum-certs:/etc/ssl/lupid:ro
       environment:
         # tell the agent's TLS lib where to find the CA
         SSL_CERT_FILE:      /etc/ssl/lupid/ca.crt
         REQUESTS_CA_BUNDLE: /etc/ssl/lupid/ca.crt   # Python
         NODE_EXTRA_CA_CERTS: /etc/ssl/lupid/ca.crt  # Node
   volumes:
     agentum-certs:
       external: true
       name: lupid_agentum-certs

3. Identify the agent. Set the JWT the agent presents to Lupid:

   services:
     my-agent:
       environment:
         AGENTUM_SESSION_JWT: "eyJ0eXAi..."  # from `agentum agent register`

   Your agent’s HTTP client needs to put this in an Authorization: Bearer header (or X-Agentum-Session-JWT for raw CONNECT flows). Most LLM SDKs let you set default headers per client.

4. Start the agent. Its outbound calls to OpenAI, Anthropic, etc. now go through Lupid. Watch the /audit page for the events.

Credential injection (the cleanest pattern)

The proxy path supports a placeholder syntax that means the agent never sees the plaintext secret. Store the credential in the vault, then put the marker in your agent’s outbound headers:

Authorization: Bearer agentum://stripe-key

Lupid sees the agentum:// prefix, resolves it to the real Stripe key via the vault, and substitutes before the request leaves. The agent’s process has no plaintext secret to leak.

Verifying it works

From inside the agent’s container:

curl -v https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_KEY"

You should see:

• TLS certificate: subject=CN=api.openai.com, issuer=CN=Lupid Local CA — confirms Lupid intercepted.
• HTTP 200 from the upstream.

And on the dashboard’s /audit page, a tool_call event with outcome=allow (or deny if your policy says so).

Tip

If you see TLS errors in the agent’s logs, the CA root isn’t mounted correctly. Check that cat $SSL_CERT_FILE returns the same content as docker exec lupid-agentum-1 cat /app/certs/ca.crt.

Caveats

• Not every HTTP client respects HTTPS_PROXY. Java needs system properties (-Djavax.net.ssl.trustStore=). Go HTTP clients respect it. Most Python and Node libraries do. Test before you assume.
• WebSockets and HTTP/2 prior knowledge connections aren’t proxied via CONNECT. Lupid speaks CONNECT only.
• Agents outside the docker network can’t reach the gateway by default. Bridge them in, or expose :7070 on the host (not recommended without TLS in front).