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 runs a small HTTP daemon on 127.0.0.1:7998. The daemon coordinates browser-based flows, holds short-lived auth sessions in memory, and serves the dashboard UI. CLI commands talk to the daemon rather than driving flows themselves.

​
Why a daemon

Earlier versions of authsome ran every flow in-process. That made three things awkward:
  • Browser bridges (the local form used to collect API keys and OAuth client secrets) need a single long-running HTTP listener. Spinning one up per CLI invocation produced port conflicts.
  • OAuth callbacks need to land on the same process that started the flow. A short-lived CLI exits before the user can finish authorizing.
  • Multi-step UIs like the dashboard need persistent state across requests, which a one-shot CLI can’t provide.
The daemon owns those concerns. The CLI becomes a thin client.

​
What runs on 7998

Route prefixPurpose
/auth/...Browser bridges for OAuth client credentials and API-key collection. OAuth callback handlers.
/connections/...Read and write connection records through the AuthLayer.
/providers/...List, inspect, register, and remove provider definitions.
/proxy/...Per-request credential resolution for the local HTTP proxy started by authsome run.
/healthLiveness and readiness probes.
/ui/, /ui/connections, /ui/apps/...The interactive dashboard UI.
The daemon binds to 127.0.0.1 only. It is not reachable from other machines on the network.

​
Lifecycle

The CLI starts the daemon on demand. If 127.0.0.1:7998 is already in use by another authsome process, the CLI reuses it. If the port is held by something else, the command fails with a clear error. 
agent / CLI / dashboard
        │
        ▼
  127.0.0.1:7998   ← daemon (FastAPI)
        │
        ├── in-memory: active auth sessions, browser-bridge state
        └── on-disk:   ~/.authsome/  (vault, providers, audit log)
In-memory state is lost on restart. A login that is mid-flight when the daemon restarts must be re-started. uvx authsome run shares the daemon with the rest of the CLI. The local HTTP proxy started by run calls back to the daemon’s /proxy/... routes to resolve fresh credentials on every intercepted request. This keeps decryption logic in one place and avoids handing the proxy direct vault access.

​
Override the daemon URL

Two environment variables control daemon discovery. Both are documented in Environment variables.
VariableSet onPurpose
AUTHSOME_DAEMON_URLClient (CLI, proxy)Point the CLI at a daemon that runs elsewhere. When set to a non-local host, the CLI does not auto-start a local daemon.
AUTHSOME_SERVER_BASE_URLDaemon hostThe canonical external URL the daemon advertises. Browser-facing URLs and OAuth callbacks are built from this.
Local default. Neither variable needs to be set: 
uvx authsome login github
Hosted shared daemon for an internal team. Set both, on the right side: 
# on the server running the daemon:
export AUTHSOME_HOME=/var/lib/authsome
export AUTHSOME_SERVER_BASE_URL=https://authsome.internal.example.com

# on developer machines:
export AUTHSOME_DAEMON_URL=https://authsome.internal.example.com
uvx authsome list
See Hosted deployment model for the trust caveats. Hosted mode is recommended only on a private network.

​
The dashboard

The daemon serves a small interactive dashboard at: 
http://127.0.0.1:7998/ui/
It surfaces:
  • All bundled and custom providers with their connection state.
  • Per-provider detail panes for OAuth and API-key connections.
  • Live connection lifecycle actions (log in, log out, revoke, refresh).
The dashboard is convenience UI on top of the same routes the CLI uses. It is not a separate API.

​
Limitations in v1

Daemon hardening is intentionally minimal in v1. Treat the daemon as trusted infrastructure on the local machine, or a single trusted private network for hosted deployments.
  • The only access control is loopback binding. There is no bearer token between the CLI/proxy and the daemon yet.
  • Browser-rendered forms do not include per-session CSRF tokens yet.
  • Active auth sessions live only in daemon memory. A restart loses any login that is mid-flight.
  • The proxy caches resolved credentials in memory for the lifetime of authsome run.
These are tracked for follow-up releases. See Daemon trust boundary for the full v1 trust model and what it does and does not protect against.

​
What’s next

Daemon trust boundary

What the loopback-only model protects against and what it doesn’t.

Hosted deployment model

Running a shared daemon on a trusted private network.

HTTP daemon API

Every route the daemon exposes.

Daemon issues

Port conflicts, restart loses session, and similar.