> ## Documentation Index
> Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="uv (recommended)">
    Project-scoped install with [`uv`](https://docs.astral.sh/uv/). The rest of the docs assume this path.

    ```bash theme={null}
    uv tool install authsome
    authsome --version
    ```

    Upgrade:

    ```bash theme={null}
    uv tool upgrade authsome
    ```
  </Tab>

  <Tab title="pip">
    Global or virtualenv install.

    ```bash theme={null}
    pip install authsome
    authsome --version
    ```

    Upgrade:

    ```bash theme={null}
    pip install --upgrade authsome
    ```
  </Tab>

  <Tab title="uvx (one-off, no install)">
    Run authsome once without installing. `uvx` fetches and caches the package on first use.

    ```bash theme={null}
    uvx authsome@latest --version
    ```

    Pin a version:

    ```bash theme={null}
    uvx authsome@0.7 --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.
  </Tab>

  <Tab title="From source">
    Clone the repo and install in editable mode. Use this when you are contributing or running an unreleased branch.

    ```bash theme={null}
    git clone https://github.com/agentrhq/authsome.git
    cd authsome
    uv pip install -e ".[dev]"
    uv run authsome --version
    ```
  </Tab>
</Tabs>

<Note>
  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`.
</Note>

## Verify the install

```bash theme={null}
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](/troubleshooting/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:

```text theme={null}
~/.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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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](/security/encryption).

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](/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](/troubleshooting/proxy-networking#tls-verification-fails).

## Uninstall

Remove the package:

```bash theme={null}
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:

```bash theme={null}
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

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Log in to GitHub and OpenAI, then run an agent in under five minutes.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    Every command, every flag, every exit code.
  </Card>
</Columns>