Run agents with the proxy

Use authsome run to inject auth headers into outbound requests without exposing secrets to the child process.

authsome run is the most secure way to run an agent. Authsome starts a local HTTP proxy, points the child process at it through HTTP_PROXY, and injects auth headers into outbound requests. The child process never sees the real credentials.

Prerequisites

Make sure you are logged in to every provider the agent will hit:

authsome login github
authsome login openai
authsome list

For an overview of how the proxy works, see Proxy injection.

Run a command

authsome run -- python my_agent.py

Everything after -- is the command and its arguments. Authsome:

1. Starts a local HTTP proxy on an ephemeral port.
2. Spawns the child with HTTP_PROXY and HTTPS_PROXY pointing at the proxy.
3. Sets placeholder environment variables for SDKs that check at startup (for example, OPENAI_API_KEY=authsome-proxy-managed).
4. Intercepts outbound requests and injects auth headers based on the destination host.
5. Stops the proxy when the child exits.
6. Returns the child’s exit code.

Verify it’s working

Check the environment authsome injects:

authsome run -- env | grep -E 'PROXY|OPENAI|GITHUB'

You should see:

• HTTP_PROXY and HTTPS_PROXY pointing at http://127.0.0.1:<port> (lowercase variants too).
• OPENAI_API_KEY=authsome-proxy-managed (the real key is never in the environment).

Make a real call through the proxy:

authsome run -- curl -s https://api.openai.com/v1/models | head -5

You should get a JSON response from OpenAI rather than an authentication error.

How matching works

Authsome routes requests to providers using each provider’s api_url field.

Request host	Matches	Header injected
api.openai.com	openai provider	Authorization: Bearer sk-...
api.github.com	github provider	Authorization: Bearer ghu_...
example.com	nothing	request passes through unchanged

The first provider whose api_url matches the request host wins. Ambiguous matches (two providers claim the same host) are not injected, the request is forwarded unchanged.

For the regex form ("api_url": "regex:^api[0-9]+\\.github\\.com$"), see Provider registry.

TLS certificate

HTTPS interception requires the mitmproxy CA certificate to be trusted on your machine. Without it, the child sees TLS verification errors on every HTTPS call.

Per-OS install instructions, including the Python-tooling REQUESTS_CA_BUNDLE / SSL_CERT_FILE overrides, are in Proxy networking.

The proxy is HTTP(S)-only and uses each provider’s default connection. Full routing contract and limitations: Proxy injection.

When to choose run over export

Pattern	Use when
authsome run -- ...	The agent calls APIs over HTTP(S), you can install the mitmproxy CA, you want secrets out of the child’s environment.
authsome export <provider> --format env	The tool can’t use an HTTP proxy, TLS interception isn’t possible, or you need credentials in a long-lived shell.

What’s next

Proxy injection

The full routing contract and known limitations.

Proxy networking

Diagnose TLS errors, certificate trust, and pinned-cert SDKs.