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 keeps all state under a single directory. The default is ~/.authsome/; override it with the AUTHSOME_HOME environment variable.

​
Tree

~/.authsome/
config.json
audit.log
identities/
<handle>.key
<handle>.json
server/
master.key
identity_registry.json
kv_store/

​
File reference

​
config.json

Global settings. JSON, one object. 
{
  "spec_version": 1,
  "encryption": {
    "mode": "local_key"
  }
}
FieldTypeNotes
spec_versionintAlways 1.
encryption.mode"local_key" or "keyring"Where the master key lives. See Encryption at rest.
Identity selection is no longer stored as default_profile. Protected daemon requests are scoped by the registered identity handle in the PoP token, and the daemon validates that handle against server/identity_registry.json.

​
identities/<handle>.key

CLI-owned Ed25519 private key used to sign PoP tokens. Mode 0600. The daemon never reads this file.

​
identities/<handle>.json

CLI-owned cache of the daemon registration response. It is useful for display and signing context, but it is not authoritative for authorization.

​
server/identity_registry.json

Daemon-owned authoritative registry mapping identity handles to DIDs. Protected requests fail if the PoP token sub is unknown or does not map to the token iss.

​
server/master.key

256-bit master key, base64-encoded JSON, mode 0600. Present when encryption.mode = "local_key". Absent when encryption.mode = "keyring" (the key lives in the OS keychain instead).
Lose this file in local_key mode and every encrypted credential in the vault is unrecoverable. Back it up with the same care you’d give the credentials themselves.

​
audit.log

Append-only newline-delimited log of significant actions: login, logout, revoke, export, register, get --show-secret. Each line records timestamp, action, provider, connection (where relevant), and outcome. Read recent entries: 
uvx authsome log
uvx authsome log -n 200
uvx authsome log --json
The schema is intentionally readable. The file is not encrypted; it’s meant to be auditable.

​
logs/authsome.log

Rotating loguru-managed debug log. Written when commands run with --verbose or when LOGURU_LEVEL=DEBUG is set. Inspect: 
tail -f ~/.authsome/logs/authsome.log
The default path is ~/.authsome/logs/authsome.log. Override with --log-file <path>. Pass --log-file "" to disable file logging entirely.

​
providers/<name>.json

User-registered or user-overridden provider definitions. A file at this path with the same name as a bundled provider wins over the bundled one. 
uvx authsome inspect github > ~/.authsome/providers/github.json
# edit fields
uvx authsome list   # github now shows source=custom
See Provider schema for the full schema and Provider registry for resolution rules.

​
server/kv_store/

Daemon-owned encrypted key-value store. Holds:
  • Per-provider metadata (known connections, default connection, last-used connection)
  • Per-provider state (last refresh attempt and error)
  • Per-provider OAuth ProviderClientRecord (client_id, encrypted client_secret)
  • Per-connection ConnectionRecord (encrypted tokens / API key, scopes, expiry, account info)
Key namespace: 
profile:<profile>:<provider>:metadata
profile:<profile>:<provider>:state
profile:<profile>:<provider>:client
profile:<profile>:<provider>:connection:<connection_name>
Sensitive fields are encrypted at rest with AES-256-GCM. See Credential storage and Encryption at rest.

​
server/daemon/

Daemon runtime files managed by the local daemon controller: pid, log, and process metadata.

​
Sizing

Typical home directory after a few logins:
ItemSize
config.json< 1 KB
identities/<handle>.key< 1 KB
identities/<handle>.json< 1 KB
server/master.key< 1 KB
server/identity_registry.json< 1 KB per identity
providers/<name>.json1-3 KB each
server/kv_store/~50 KB per connection
audit.log200-400 B per event, grows linearly
logs/authsome.logRotates; bounded
The vault is not large unless you accumulate hundreds of connections.

​
Permissions

PathDefault modeWhy
~/.authsome/0700Only the user can read or traverse.
~/.authsome/identities/<handle>.key0600CLI signing key. Never read by the daemon.
~/.authsome/server/master.key0600Daemon-owned vault encryption key.
~/.authsome/server/kv_store/0700Daemon-owned encrypted credential store.
~/.authsome/audit.log0600Same justification.
~/.authsome/providers/*.json0644Not sensitive on its own.
uvx authsome doctor verifies the critical paths and their modes.

​
Override the location

export AUTHSOME_HOME=/var/lib/authsome
uvx authsome whoami
Useful for:
  • Ephemeral CI environments where you want a clean state per job.
  • Per-project credential isolation by setting AUTHSOME_HOME in a .envrc.
  • Hosted daemon deployments. See Hosted deployment model.

​
What’s next

Credential storage

The vault key namespace and connection record shape.

Encryption at rest

What’s encrypted, with which algorithm, and where the key lives.

Environment variables

AUTHSOME_HOME and friends.

Diagnose with doctor

Verify the layout is healthy.