Skip to main content

Documentation Index

Fetch the complete documentation index at: https://authsome.agentr.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 at the proxy layer. The child process never sees the real credentials.

​
Prerequisites

Make sure you are logged in to every provider the agent will hit: 
uvx authsome login github
uvx authsome login openai
uvx authsome list
For an overview of how the proxy works, see Proxy injection.

​
Run a command

uvx 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: 
uvx 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: 
uvx 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 host_url field.
Request hostMatchesHeader injected
api.openai.comopenai providerAuthorization: Bearer sk-...
api.github.comgithub providerAuthorization: Bearer ghu_...
example.comnothingrequest passes through unchanged
The first provider whose host_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 ("host_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

PatternUse 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 envThe 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.