Environment variables

Variables authsome reads, writes, and injects into subprocesses.

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

Variable	Purpose
AUTHSOME_BASE_URL	The daemon URL. On client machines, set this to point the CLI and proxy at a remote daemon instead of auto-starting one locally. On the daemon host, set this to the public URL when behind a reverse proxy — authsome uses it to build OAuth callback URLs such as /auth/callback/oauth. Defaults to http://127.0.0.1:7998.
AUTHSOME_HOME	Override the default ~/.authsome directory. Useful for tests, ephemeral environments, and per-project vaults.
AUTHSOME_IDENTITY_PRIVATE_KEY	Hex-encoded Ed25519 private key. The agent’s full identity is derived from this single value: the DID is computed locally and the human-readable handle is resolved from the identity server. Sufficient on its own — no authsome onboard or local identity files required.
AUTHSOME_IDENTITY	(Optional, deprecated) Explicit handle override used alongside AUTHSOME_IDENTITY_PRIVATE_KEY. No longer required: the handle is resolved from the identity server. See the migration note below.
HTTP_PROXY / HTTPS_PROXY	Honored by authsome’s own outbound HTTP requests (token endpoints, device flow polling). The proxy started by authsome run is set as these variables in the child process; it does not chain through them.

Agent identity from a single key

For headless, CI, and container deployments, supply only the private key:

export AUTHSOME_IDENTITY_PRIVATE_KEY=<hex-encoded-ed25519-key>
uv run authsome list

On startup the CLI derives the DID from the key and asks the identity server for the handle bound to that DID. If the DID is not yet registered, a handle is generated and registered automatically, then the standard browser claim flow runs.

Migration: the previous setup required both AUTHSOME_IDENTITY (handle) and AUTHSOME_IDENTITY_PRIVATE_KEY. The key alone is now sufficient. AUTHSOME_IDENTITY is still honored as an explicit handle override but is deprecated and no longer required. Resolving the handle requires the daemon to be reachable at CLI startup.

AUTHSOME_BASE_URL for remote daemons

For remote daemon deployments:

• set AUTHSOME_BASE_URL to the full daemon URL on client machines
• set AUTHSOME_BASE_URL to the public-facing URL on the daemon host when behind a reverse proxy
• when AUTHSOME_BASE_URL points at a non-local host, the CLI will not attempt to manage daemon state

Example:

export AUTHSOME_BASE_URL=https://authsome.internal.example.com
uv run authsome list

When running the daemon locally, you typically do not need to set AUTHSOME_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:

Provider	Variable checked
openai	OPENAI_API_KEY
anthropic	ANTHROPIC_API_KEY
…	See each provider’s api_key.env_var field via authsome inspect <provider>.

If the variable is set and non-empty, 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.

Variables injected by authsome run

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

Always set

Variable	Value	Purpose
HTTP_PROXY	http://127.0.0.1:<port>	Routes HTTP traffic through the local proxy.
HTTPS_PROXY	http://127.0.0.1:<port>	Same, for HTTPS.
http_proxy / https_proxy	Same as above	Lowercase 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:

Provider	Variable	Placeholder value
openai	OPENAI_API_KEY	authsome-proxy-managed
github	GITHUB_ACCESS_TOKEN	authsome-proxy-managed
…	Per provider definition	authsome-proxy-managed

The real secret is added to outbound requests at the proxy layer, never in the environment.

Logging variables

Variable	Purpose
LOGURU_LEVEL	Override 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
authsome login github
authsome login openai

# Run the agent through the proxy, secrets stay in the vault
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 "$(authsome export github --format env)"
my-cli-tool

What’s next

CLI reference

Every command and flag.

Proxy injection

The full proxy routing contract.