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.
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.
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.
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.
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.
A typical agent run that pulls credentials from authsome:
# One-time setupauthsome login githubauthsome login openai# Run the agent through the proxy, secrets stay in the vaultauthsome 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:
