Troubleshooting

sudoterm status shows daemon unreachable

Check the unit is actually running:

sudoterm status
sudo systemctl status sudoterm
sudoterm logs --lines 200 --no-follow

If the port isn't 7681 (default), check ~/.sudoterm/config.json. If the service won't start, look for EADDRINUSE in the logs — something else has your port.

The URL works but I see a Cloudflare error

cloudflared isn't running, or hasn't connected. Check the daemon logs for Registered tunnel connection — that's the success marker. If you see exit errors, run:

sudoterm doctor

The doctor checks the cloudflared binary, the tunnel.json file, and the daemon's health endpoint. If the binary is missing:

curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared
sudoterm restart

Block output isn't being detected

The default prompt regex covers bash/zsh/starship. If you have a custom PS1, blocks may not register. Until the settings UI lands (Phase 2), you can verify by typing a quick command at a stock prompt — if blocks appear there, it's a regex mismatch.

AI sidebar says "no key"

You haven't added an API key for the selected provider. Click ⚙ in the sidebar, paste a key, save. The key never leaves your daemon — it goes straight to the provider's API.

I forgot my password

Phase 1 reset is destructive (we keep data.db simple):

sudoterm stop
mv ~/.sudoterm/data.db ~/.sudoterm/data.db.bak
sudoterm start
# Visit the URL — you're back at the setup wizard

Phase 2 will add a graceful reset via UDS.

A tab freezes / WS won't reconnect

Reload the browser tab. The tmux session is still alive on the server — you'll reattach to the same scrollback.

Where do I file bugs?

GitHub Issues: https://github.com/sudoterm/sudoterm/issues