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 runs on Python 3.13 or newer. It ships as a single PyPI package with no native build step.

​
Pick an install path

​
Verify the install

uvx authsome whoami
uvx authsome doctor
whoami prints the home directory, registered identity handle, DID, and active encryption mode. doctor walks the home directory, verifies encryption is available, and parses every bundled provider definition. A healthy install reports OK for each check and exits with code 0. If doctor reports failures, see Diagnose with doctor.

​
First-run initialization

On authsome init, authsome initializes its home directory at ~/.authsome/, creates a generated identity handle and Ed25519 DID, and registers that identity with the local daemon: 
~/.authsome/
  config.json
  audit.log
  identities/<generated-handle>.json
  identities/<generated-handle>.key
  server/
    master.key            mode 0600
    kv_store/
    identity_registry.json
    daemon/
The daemon-owned master key is generated locally with 256 bits of entropy. Override the home location with AUTHSOME_HOME for ephemeral or per-project setups: 
export AUTHSOME_HOME=/var/lib/authsome
uvx authsome init
See Filesystem layout for the full directory model.

​
Choose the encryption backend

By default, the master key sits in ~/.authsome/server/master.key with mode 0600. To use the OS keychain instead (macOS Keychain, GNOME Keyring, Windows Credential Manager), edit the Authsome config: 
{
  "spec_version": 1,
  "encryption": {
    "mode": "keyring"
  }
}
Re-run uvx authsome doctor to confirm the backend is reachable. The trade-offs are covered in Encryption at rest. Older installs that used the implicit default profile must run authsome init again. This release does not migrate credentials under old profile:default:* keys.

​
Optional: trust the proxy CA

uvx authsome run injects auth headers through a local mitmproxy. HTTPS interception requires the mitmproxy CA to be trusted on the machine. You can defer this until you actually use run. When you’re ready, the per-OS install steps are in Proxy networking.

​
Uninstall

Remove the package: 
uv tool uninstall authsome     # if installed via `uv tool install`
pip uninstall authsome         # if installed via pip
# uvx leaves nothing to uninstall; clear the cache with `uv cache clean` if desired
Remove stored credentials and configuration: 
rm -rf ~/.authsome
This destroys every stored connection and the master key. If you’re on keyring encryption mode, also delete the authsome entry from your OS keychain. To revoke remote sessions for any provider before uninstalling, run uvx authsome revoke <provider> for each one first.

​
Next steps

Quickstart

Log in to GitHub and OpenAI, then run an agent in under five minutes.

CLI reference

Every command, every flag, every exit code.