Skip to main content
Authsome runs on Python 3.13 or newer. It ships as a single PyPI package with no native build step.

​
Pick an install path

Every command in the docs is written as authsome <subcommand> and assumes you ran uv tool install authsome (or pip install authsome). If you skipped install and prefer one-off runs, prefix every command with uvx authsome@latest instead of authsome.

​
Verify the install

authsome whoami
authsome doctor
whoami prints the home directory, registered identity handle, DID, and both the configured encryption mode and effective master-key source. 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 onboard, authsome initializes its home directory at ~/.authsome/, creates a generated identity handle and Ed25519 DID, registers that identity with the daemon, completes claim, and imports API keys from .env files and the process environment: 
~/.authsome/
  client/
    config.json           active identity, proxy mode
    logs/authsome.log
    identities/<handle>.json
    identities/<handle>.key
  server/
    master.key            mode 0600
    authsome.db           identity/principal/vault registries
    kv_store/             encrypted credential blobs
    logs/authsome.log
On a fresh onboard, authsome resolves the master key source in this order:
  1. AUTHSOME_MASTER_KEY from the environment, when set. The value must be a base64-encoded 32-byte key.
  2. An existing OS keyring entry.
  3. An existing ~/.authsome/server/master.key.
  4. A newly created OS keyring entry, when the keyring is available.
  5. A newly created local ~/.authsome/server/master.key as the final fallback.
Override the home location with AUTHSOME_HOME for ephemeral or per-project setups: 
export AUTHSOME_HOME=/var/lib/authsome
authsome onboard
For a remote or self-hosted daemon, pass --base-url once; authsome saves it in client config for later commands: 
authsome onboard --base-url https://authsome.example.com

​
Choose the encryption backend

By default, authsome uses encryption.mode = "auto" and applies the precedence above. To pin the daemon to the local file or OS keychain instead, edit the Authsome config: 
{
  "spec_version": 1,
  "encryption": {
    "mode": "keyring"
  }
}
Re-run authsome doctor to confirm the backend is reachable. The trade-offs are covered in Encryption at rest. Upgrading from releases before 0.4 (the old profile model) requires a fresh authsome onboard and re-login. Credentials under profile:* keys are not migrated automatically. See Changelog.

​
Optional: trust the proxy CA

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 authsome provider 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.