Troubleshooting

Begin with make status. Check loopback before TLS or tailnet access:

curl --fail http://localhost:8317/healthz
make logs proxy

Docker or startup fails

Start Docker and verify docker info. Check that loopback port 8317 is free. Confirm 1Password is unlocked, the CLI integration is enabled, and the credential item has the exact expected field names.

If template injection fails, check OP_ACCOUNT, OP_VAULT, and OP_ITEM_NAME. The checked-in template contains unresolved references by design; do not mount it directly instead of using make up.

Localhost works but hara.local fails

Install portless if absent. Check that it runs in LAN mode and the Hara alias exists. make up re-registers the alias, but restarting the shared portless proxy can affect other local apps.

For certificate errors, configure the portless CA as described in Network and TLS. On other devices, also check mDNS support, the host firewall, and Wi-Fi isolation. Use URL=http://localhost:8317 on the host while diagnosing the LAN layer.

Tailscale is not signed in

Open the login link from make status and authorize the device. Verify MagicDNS, HTTPS certificates, and tailnet ACLs. The first start waits for login rather than repeatedly creating new device keys. Use your installation's actual tailnet URL; example addresses are not usable destinations.

API returns 401

API requests need the client key, not the management password or provider key. After rotation, run make ops keys and make up, then restart clients that cached the old value. Keep set -x off while checking auth. Do not print keys to compare them.

For Claude Code, try a normal terminal outside a nested desktop session. The desktop app may otherwise use its own login instead of the proxy token.

Panel works but no model responds

Run make ops accounts and make ops models, using URL=http://localhost:8317 when bypassing portless. Check that a connected account actually supports the requested model and that its token is valid. Container health does not prove upstream account health.

Accounts are rate-limited

Inspect make ops quota and the panel. A provider may have separate five-hour and weekly windows. Persisted cooldowns survive restarts; repeated restarts do not replenish provider usage. Another eligible account or model can serve a failover, otherwise wait for the reset.

Codex answers but the WebSocket check fails

Run make ops ws-smoke URL=http://localhost:8317 first. Reinstall the profile with make codex profile if the checkout moved. Then run make codex smoke and inspect the server logs privately.

Socket turns show GET /v1/responses; HTTP turns show POST /v1/responses. A client warning about falling back to HTTPS means the WebSocket failed. If no account can serve a response.create, the proxy can close the socket without an error frame.

A panel setting disappears after restart

make up regenerates the runtime configuration from config.yaml. Copy the intended setting into that template and replace sensitive values with 1Password references. Quota-driven account priorities can also change hourly.

Documentation changes do not appear

make web dev serves the landing page; its Docs link opens the deployed site. For live Markdown editing, use make web docs and open http://localhost:5174/. Rebuild with make web build before previewing or deploying the combined site.

Reporting a problem

Include the command, upstream image version, OS, and a minimal sanitized error. Remove keys, OAuth callbacks, account emails, tailnet names, local paths, prompt text, and personal client settings. Do not attach rendered config, auth files, Tailscale state, or full logs.