agentrhq__authsome/docs/site/installation.mdx

---
title: "Installation"
sidebarTitle: "Installation"
description: "Install authsome with uv, pip, or run it one-off with uvx. No build step, no system dependencies beyond Python 3.13."
icon: "download"
keywords: ["authsome install", "uv tool install authsome", "pip install authsome", "uvx authsome", "authsome 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
    uv tool install authsome
    authsome --version
    ```

    Upgrade:

    ```bash
    uv tool upgrade authsome
    ```
  </Tab>
  <Tab title="pip">
    Global or virtualenv install.

    ```bash
    pip install authsome
    authsome --version
    ```

    Upgrade:

    ```bash
    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
    uvx authsome@latest --version
    ```

    Pin a version:

    ```bash
    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.
  </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
    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
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
~/.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 `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
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
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
{
  "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).

Older installs that used the implicit `default` profile must run `authsome onboard` 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](/troubleshooting/proxy-networking#tls-verification-fails).

## Uninstall

Remove the package:

```bash
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
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>