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 can run as a small shared internal service: one daemon, one vault, multiple developer machines pointed at it. This page covers when that shape is appropriate, how to configure it, and what’s still missing before it should be treated as production-grade.

​
When hosted mode is appropriate

Approved only when all of these are true:
  • The daemon lives on a trusted private network (VPC, VPN, overlay network, or a dedicated subnet).
  • One shared vault for the team is acceptable. There is no per-user tenant isolation in v1.
  • Operators understand that the network is the primary access-control boundary.
  • The deployment is internal. Not internet-facing.
For single-user laptops, the local default is the right choice. See The local daemon.

​
Configuration

Two environment variables drive hosted deployments. Each is set on a different side.
VariableSet onValuePurpose
AUTHSOME_SERVER_BASE_URLDaemon hostThe canonical external URL the daemon advertises.Browser-facing URLs and OAuth callbacks are built from this.
AUTHSOME_DAEMON_URLClient (CLI, proxy)Full URL of the hosted daemon.Points the CLI at a non-local daemon. Suppresses the auto-start of a local one.
AUTHSOME_HOMEDaemon host (often)Path to the shared ~/.authsome/ directory.Persistent disk. The vault, master key, providers, and audit log all live here.

​
On the daemon host

export AUTHSOME_HOME=/var/lib/authsome
export AUTHSOME_SERVER_BASE_URL=https://authsome.internal.example.com
Include the full scheme and host. Add a non-default port when the scheme doesn’t imply it: 
export AUTHSOME_SERVER_BASE_URL=http://10.10.0.25:7998
Use the same URL that the browser and OAuth providers will see. This is what authsome inserts into OAuth callback URLs and into the dashboard.

​
On client machines

export AUTHSOME_DAEMON_URL=https://authsome.internal.example.com
uvx authsome list
The CLI does not auto-start a local daemon when AUTHSOME_DAEMON_URL points at a non-local host. Client machines do not need AUTHSOME_SERVER_BASE_URL.

​
OAuth callback URL

For PKCE flows in hosted mode, the OAuth callback URL is the daemon-side URL with the /auth/callback/oauth path: 
https://authsome.internal.example.com/auth/callback/oauth
Register that exact URL in every OAuth app you intend to use. Local-mode callback (http://127.0.0.1:7998/auth/callback/oauth) does not apply to hosted deployments.

​
Trust model in hosted mode

Hosted mode widens the trust boundary from “the local machine” to “the private network the daemon sits on”. Two consequences: 1. Filesystem access to the daemon host matters as much as network access. A host that can read both the encrypted SQLite store and master.key can effectively access the vault. Anyone who can SSH onto the daemon host, become the daemon user, and read both files, has the equivalent of full credential access. 2. There is no per-user authentication inside authsome yet. Any client that can reach the daemon URL can call every route. Restrict ingress at the network layer:
  • Place the daemon behind a private IP, VPN, or overlay network.
  • Restrict ingress to known operator and client machines.
  • Terminate TLS at a private reverse proxy if you need a stable HTTPS URL.
The Daemon trust boundary page lists the specific v1 limitations.

​
Operational checklist

Reason
AUTHSOME_HOME is on a persistent diskThe vault and master key must survive daemon restarts.
Snapshots or backups of AUTHSOME_HOME are configuredDisk loss = credential loss. Encrypted records cannot be recovered without master.key.
Backups treat master.key and store.db with the same careTogether they decrypt records. Same security posture as raw credentials.
The daemon is reachable only from approved CIDRs or VPNNetwork is the access-control boundary.
OAuth callback URLs in every provider are updatedLocal-mode callback URLs do not work in hosted mode.
The daemon user has minimal privilegesThe daemon does not need to be root.
Logs are forwarded off-hostAudit events live in audit.log under AUTHSOME_HOME.

​
What’s still missing

Hosted v1 deliberately keeps the trust model simple. Before hosted authsome should be treated as an internet-facing or multi-tenant service, the following must land:
  • Real per-user authentication inside the daemon.
  • Tenant separation between users sharing the same daemon.
  • Persistent browser-session storage (today, sessions are in-memory and lost on restart).
  • A built-in admin secret or bearer token gate.
  • Browser-form session hardening (CSRF, replay protection).
Until those exist, treat hosted authsome as internal infrastructure, not as a SaaS-style identity platform.

​
What’s next

The local daemon

The daemon’s lifecycle and routes.

Daemon trust boundary

What the v1 model protects against, and what it doesn’t.

Environment variables

Every variable authsome reads, writes, or injects.

Daemon issues

Port conflicts, lost sessions, and restart behavior.