Daemon issues

Diagnose port 7998 conflicts, lost sessions on restart, and broken daemon discovery.

The authsome daemon binds to 127.0.0.1:7998 by default. Most issues are one of three shapes: port held by another process, daemon unreachable from the CLI, or in-memory state lost across a restart.

Symptom matrix

Symptom	Most likely cause
Address already in use: 127.0.0.1:7998	Another authsome process is running, or something else holds the port.
Could not connect to daemon at http://127.0.0.1:7998	The daemon didn’t start, the port is firewalled, or AUTHSOME_BASE_URL points somewhere wrong.
Browser opens to a blank form	Daemon started but the route is missing; usually a version mismatch between CLI and daemon.
Login was mid-flight, then the terminal disconnected	Daemon restarted; session is gone.
Connection refused from authsome run	The proxy can’t reach the daemon to resolve credentials.
AUTHSOME_BASE_URL is set but unreachable	Hosted daemon URL is wrong, or the host is down.

Port 7998 in use

lsof -i :7998

If the holder is another authsome process, the CLI will reuse it. No fix needed.

If it’s something else, free the port or run a per-user daemon at a different home:

export AUTHSOME_HOME=/path/to/another/home
authsome doctor

A second AUTHSOME_HOME starts a separate daemon on a separate ephemeral port and uses that. The two daemons do not interfere.

Daemon won’t start

Run with verbose logging:

authsome --verbose whoami

Common root causes:

• ~/.authsome/ is on a filesystem that doesn’t support SQLite file locks (rare; some network mounts).
• The current user doesn’t have write permission to AUTHSOME_HOME.
• master.key has the wrong mode and the daemon refuses to start in local_key mode.

authsome doctor reports each of these specifically.

CLI can’t find the daemon

The CLI looks at AUTHSOME_BASE_URL first, then falls back to http://127.0.0.1:7998.

echo $AUTHSOME_BASE_URL

If it’s set to a hosted URL that’s currently unreachable:

unset AUTHSOME_BASE_URL
authsome whoami

The CLI will start a local daemon and verify it’s reachable.

If you do want a hosted daemon and it’s unreachable, the fix is on the daemon host. Check that:

• The daemon process is running there.
• AUTHSOME_BASE_URL on the daemon matches the URL you’re calling.
• Ingress is allowed from your client’s network (private VPC, VPN, or whatever the team uses).

Login was interrupted by a daemon restart

Active auth sessions live in the daemon’s memory. A restart loses them. The provider may or may not have accepted the authorization on its side. Re-run the login:

authsome login <provider> --force

The --force flag overwrites whatever partial state landed in the vault.

If the provider has a partial OAuth grant on file (you authorized but the callback never landed), revoke at the provider and start over:

1. Revoke the OAuth app at the provider’s UI.
2. authsome revoke <provider> locally to clear any partial state.
3. authsome login <provider> to start fresh.

This is rare. Most flows recover automatically by re-running the login.

Daemon health check

The daemon exposes a health endpoint:

curl -s http://127.0.0.1:7998/health

A healthy daemon returns a JSON status with vault and provider-registry readiness. A non-200 response indicates the daemon process is up but a subsystem is unhealthy.

The same information is available through:

authsome doctor --json

which is the right call from monitoring scripts.

Inspect what the daemon is doing

The daemon logs to the same loguru sink the CLI does. With verbose logging on:

LOGURU_LEVEL=DEBUG authsome list
tail -f ~/.authsome/logs/authsome.log

You’ll see every route the CLI calls and every internal step the daemon takes.

Restart cleanly

The daemon is stateless on disk except for what’s already in the vault. To restart it:

# stop any local authsome processes
pkill -f authsome

# next CLI call starts a fresh daemon
authsome whoami

In-flight logins are lost. Stored connections are not.

When to file a bug

If the daemon fails to start after pkill + a fresh authsome whoami, and doctor reports OK, open an issue at github.com/agentrhq/authsome with:

• The output of authsome --verbose doctor.
• The tail of ~/.authsome/logs/authsome.log covering the failed start.
• Your OS and Python version.

What’s next

The local daemon

What the daemon is and which routes it exposes.

Daemon trust boundary

What the loopback-only model protects against.

Diagnose with doctor

The first command to run when something looks wrong.

Environment variables

AUTHSOME_BASE_URL, AUTHSOME_BASE_URL, AUTHSOME_HOME.