Credential proxy
The proxy lets an agent call an API with a credential it never sees. The agent writes a reference where the secret goes. The proxy runs on the same machine, fetches the value from your vault, and puts it into the outgoing HTTPS request. The agent's logs, prompts and memory only ever hold the reference.
1. Create the agent's client
Create a client for the agent as in Agent setup, with the scopes it needs. A proxy is one agent: every request through it counts as the client it was enrolled as, against that client's scopes and rate limits, and under its name in the audit log. To keep two agents apart, run one proxy for each, each enrolled as its own client.
2. Install and enroll
Download clavitor-proxy from Downloads and put it in a directory of its own, owned by the user the proxy runs as. Then enroll it:
$ clavitor-proxy init
init reads the client's blob and key from standard input, never from the command line, and shows the vault's hosts, the home vault and its replica, so you can confirm both are yours before anything is saved. It writes clavitor.conf next to the binary, readable only by its owner. The proxy refuses a config file anyone else can read, and there is no setting to move it.
For a scripted enrollment, set CLAVITOR_PROXY_CONFIRM_VAULT to the vault host you expect, or to home,replica when the blob names a replica. init then refuses a blob that names a different vault.
3. Trust the proxy's certificate
The proxy opens the agent's HTTPS connection itself, so the agent has to trust the proxy's own certificate authority. Print it with:
$ clavitor-proxy ca
Add it to the trust store the agent's HTTP client uses. The proxy's connections onward to the API use TLS 1.3. It sends a credential only to a site whose certificate chains to your system's or Mozilla's trusted roots.
4. Start it and point the agent at it
$ clavitor-proxy serve $ export HTTPS_PROXY="http://clavitor:$(cat proxy-auth)@127.0.0.1:1983"
The proxy listens on 127.0.0.1:1983. Every connection must carry the access token from the proxy-auth file next to the binary, and a connection without it is refused, so another user on the same machine can't borrow the proxy. Change the port with CLAVITOR_PROXY_PORT.
The proxy listens only on loopback unless you set CLAVITOR_PROXY_LISTEN to another address and also create an empty file named proxy-allow-private next to the binary, readable only by its owner. The access token travels unencrypted on that port, so do this only on a trusted private network, such as a VPN or Tailscale.
How a credential gets into a request
With a reference. Put clavitor://<entry title>/<field label> in a request header, for example Authorization: Bearer clavitor://OpenAI/key. References are written as for render: the title matches one entry exactly, ignoring case, and a space is written %20. The proxy replaces the reference with the field's value.
By host. With no reference in the request, the proxy looks for the one entry whose web address matches the host the agent is calling, and fills a standard header from that entry's field labels:
| Field label | Header the proxy sets |
|---|---|
key, apikey, api_key, token, secret, bearer, access_token | Authorization: Bearer <value> |
x-api-key, api-key | X-API-Key: <value> |
username and password together | Authorization: Basic … |
Either way, a credential only goes to a host its entry lists among its web addresses: the same host, or its subdomains only where the address says *.. An entry without a web address can't be used through the proxy. When a lookup fails, the request stops with an error. The proxy never sends it on without the credential, and never forwards the reference itself. A request with no reference, to a host no entry matches, passes through unchanged.
Fields protected by Identity Encryption can't be reached through the proxy: only your hardware key opens them.
Cookies an API sets are removed from its responses, so an upstream can't plant cookies in the agent's HTTP client.
Private networks
By default the proxy won't connect to private addresses, loopback, link-local addresses or cloud metadata services, so a manipulated agent can't use it to reach your internal network. If an agent legitimately calls an API on a private network, create the owner-only proxy-allow-private file next to the binary. It is a file, not an environment variable, so it can't be switched on by accident.
Errors
Every failure carries a stable code you can match on in alerts and scripts.
| Code | Meaning |
|---|---|
CV-5032 | No entry has the title in the reference. |
CV-5033 | More than one entry has that title. |
CV-5034 | The entry has no field with that label. |
CV-5035 | The field is protected by Identity Encryption, which the proxy never reads. |
CV-5037 | The host the agent is calling isn't among the entry's web addresses. |
CV-5040 | A header mixes a clavitor:// reference with bytes that aren't valid UTF-8, so the proxy refuses it. |
CV-5051 | More than one entry matches the host. Use a reference instead. |
CV-5052 | The matching entry has no field label from the table above. |
The ranges are CV-5001–5019 for setup, CV-5030–5049 for references, CV-5050–5069 for host matching and CV-5070–5089 for the connection to the API.
What it doesn't protect against
- A compromised machine. The proxy runs beside the agent. Someone with administrator access to that machine can read its memory. The proxy keeps credentials out of the agent, not out of a machine that is no longer yours.
- An API that echoes the credential back. The proxy puts credentials into requests and doesn't filter responses, so an endpoint that returns the key it was sent hands it to the agent.
What it never logs
The proxy logs the host of each connection and, when a request fails, the error code and the request's path. It never logs credential values, query strings, request or response bodies, its config file or its access token.
clavitor-proxy version shows the version and whether it runs in FIPS mode.