Installation

Install authsome with uv, pip, or run it one-off with uvx. No build step, no system dependencies beyond Python 3.13.

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

Pick an install path

uv (recommended)

Project-scoped install with uv. The rest of the docs assume this path.

uv tool install authsome
authsome --version

Upgrade:

uv tool upgrade authsome

pip

Global or virtualenv install.

pip install authsome
authsome --version

Upgrade:

pip install --upgrade authsome

uvx (one-off, no install)

Run authsome once without installing. uvx fetches and caches the package on first use.

uvx authsome@latest --version

Pin a version:

uvx authsome@0.2.4 --version

Use uvx when you don’t want a persistent install (sandboxed environments, one-off scripts). Every command shown in the rest of the docs as authsome <subcommand> works as uvx authsome@latest <subcommand> here.

From source

Clone the repo and install in editable mode. Use this when you are contributing or running an unreleased branch.

git clone https://github.com/agentrhq/authsome.git
cd authsome
uv pip install -e ".[dev]"
uv run authsome --version

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 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/

On a fresh init, 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 init

For ephemeral agents or fresh CI runners, you can also supply the acting identity from the environment instead of relying on local identity files:

export AUTHSOME_IDENTITY=steady-wisely-boldly-0042
export AUTHSOME_IDENTITY_PRIVATE_KEY=<32-byte-ed25519-private-key-as-hex>

When AUTHSOME_IDENTITY_PRIVATE_KEY is set, authsome derives the did:key from that private key and uses the environment-backed identity before falling back to ~/.authsome/client/identities/.

See Filesystem layout for the full directory model.

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.

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

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