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 interacts with environment variables in three roles: inputs that change CLI behavior, outputs produced by export, and injected variables set inside processes spawned by run.

​
Inputs authsome reads

VariablePurpose
AUTHSOME_DAEMON_URLClient-side daemon URL used by the CLI and proxy helpers. Set this on machines that should talk to a hosted authsome daemon instead of auto-starting a local one. Defaults to http://127.0.0.1:7998.
AUTHSOME_HOMEOverride the default ~/.authsome directory. Useful for tests, ephemeral environments, and per-project profiles.
AUTHSOME_SERVER_BASE_URLCanonical external base URL for hosted daemon deployments. Authsome uses it to build browser-facing URLs and OAuth callback URLs such as /auth/callback/oauth. Set this when the daemon is reached through a private VM, reverse proxy, or internal DNS name instead of localhost.
HTTP_PROXY / HTTPS_PROXYHonored by authsome’s own outbound HTTP requests (token endpoints, device flow polling). The proxy started by uvx authsome run is set as these variables in the child process; it does not chain through them.

​
AUTHSOME_DAEMON_URL expectations

For hosted clients:
  • set AUTHSOME_DAEMON_URL to the full hosted daemon URL
  • do not set AUTHSOME_SERVER_BASE_URL on the client just to use a hosted daemon
  • when AUTHSOME_DAEMON_URL points at a non-local host, the CLI does not auto-start a local daemon
Example: 
export AUTHSOME_DAEMON_URL=https://authsome.internal.example.com
uv run authsome list

​
AUTHSOME_SERVER_BASE_URL expectations

For hosted servers:
  • include the full scheme and host, such as https://authsome.internal.example.com
  • include a port when it is not the default for the scheme, such as http://10.10.0.25:7998
  • use the same public or private URL that the browser and OAuth provider will see
Example: 
export AUTHSOME_HOME=/var/lib/authsome
export AUTHSOME_SERVER_BASE_URL=https://authsome.internal.example.com
In a local-only setup, you typically do not need to set either AUTHSOME_DAEMON_URL or AUTHSOME_SERVER_BASE_URL.

​
Provider-specific input variables

Some bundled provider definitions declare api_key.env_var so the API-key flow can pick up an existing key without prompting:
ProviderVariable checked
openaiOPENAI_API_KEY
anthropicANTHROPIC_API_KEY
…See each provider’s api_key.env_var field via uvx authsome inspect <provider>.
If the variable is set and non-empty, uvx authsome login <provider> uses its value with no prompt. If unset, the secure browser bridge takes over. The OAuth2 client config block can declare client.client_id_env and client.client_secret_env for similar automated collection. Bundled providers do not currently declare these, they rely on the browser bridge, but custom provider definitions can.

​
Outputs from uvx authsome export

uvx authsome export <provider> --format env prints KEY=value lines on stdout. The KEY names come from the provider’s export.env map. 
$ uvx authsome export github --format env
GITHUB_ACCESS_TOKEN=ghu_...
Source the output to load the variables into your shell: 
eval "$(uvx authsome export github --format env)"
Only access_token (OAuth2) and api_key (API-key) are exported. Refresh tokens are never exposed. For JSON output: 
uvx authsome export github --format json

{
  "access_token": "ghu_..."
}

​
Variables injected by uvx authsome run

When you use uvx authsome run -- <cmd>, authsome sets several variables inside the child process.

​
Always set

VariableValuePurpose
HTTP_PROXYhttp://127.0.0.1:<port>Routes HTTP traffic through the local proxy.
HTTPS_PROXYhttp://127.0.0.1:<port>Same, for HTTPS.
http_proxy / https_proxySame as aboveLowercase variants for tools that prefer them.
NO_PROXY / no_proxy(preserved if set, otherwise unset)Hosts to exclude from the proxy.

​
Per-provider placeholders

For every provider with a connected default connection, authsome sets a placeholder under the provider’s export.env key so SDKs initialize successfully without seeing the real secret:
ProviderVariablePlaceholder value
openaiOPENAI_API_KEYauthsome-proxy-managed
githubGITHUB_ACCESS_TOKENauthsome-proxy-managed
…Per provider definitionauthsome-proxy-managed
The real secret is added to outbound requests at the proxy layer, never in the environment.

​
Logging variables

VariablePurpose
LOGURU_LEVELOverride the loguru log level used by authsome’s library code. The CLI also honors --verbose (DEBUG) and --quiet.

​
Worked example

A typical agent run that pulls credentials from authsome: 
# One-time setup
uvx authsome login github
uvx authsome login openai

# Run the agent through the proxy, secrets stay in the vault
uvx authsome run -- python my_agent.py
The agent reads OPENAI_API_KEY and GITHUB_ACCESS_TOKEN as it normally would. They are placeholders. The proxy injects the real values into outbound requests to api.openai.com and api.github.com. If the agent needs to run a tool that doesn’t honor HTTP_PROXY, fall back to export: 
eval "$(uvx authsome export github --format env)"
my-cli-tool

​
What’s next

CLI reference

Every command and flag.

Proxy injection

The full proxy routing contract.