Troubleshooting

Start with status and logs

bin/octi status
bin/octi logs
curl http://127.0.0.1:3005/api/health

Default ports are 3005 for the API and 3007 for the web UI. Check .env and persisted settings if your installation overrides them.

The service does not start

Confirm Node.js is version 24.9 or newer and install both dependency trees:

npm install
cd web && npm install

Run npm run setup if bootstrap configuration or the administrator account has not been created.

Database errors

Embedded mode uses PGlite and needs no Docker service. External mode needs PostgreSQL with pgvector and a reachable connection string. Use the repository migration commands and documentation; do not create or edit migration journal files by hand.

Back up the database before migrations or master-key rotation. Run the documented key-rotation dry run before changing encryption material.

Login problems

Browser login expects cookie sessions and CSRF handling. Desktop and other non-browser clients use the mobile login flow and bearer credentials. If TOTP is enabled, login must complete that challenge; the server does not bypass it for mobile clients.

ASK permissions block unattended work

This is expected. ASK requires an attended client that can return an approval decision. Change a rule to ALLOW only after reviewing the tool, action, and scope you intend to run.

Client cannot connect

Start the backend before bin/octi tui or bin/octi desktop. Confirm that the client points at the correct API port and that a reverse proxy forwards WebSocket upgrades.

For deeper diagnostics, current migration notes, and platform-specific desktop packages, use docs/TROUBLESHOOTING.md and docs/DESKTOP.md from the same repository commit.