Web UI setup

Cogtrix ships with a React-based Web UI that runs alongside the backend. Sessions, messages, tool confirmations, and memory all stream into the browser over a WebSocket.

Start the backend in API mode

export COGTRIX_JWT_SECRET="$(python -c 'import secrets; print(secrets.token_hex(32))')"
uv run python -m src.api --debug --reload

The API listens on localhost:8000. Swagger docs live at /api/v1/docs.

Clone and run the Web UI

git clone https://github.com/NorthlandPositronics/Cogtrix-WebUI.git
cd Cogtrix-WebUI
pnpm install
pnpm dev

Dev server runs on localhost:5173. The Web UI auto-discovers the backend at localhost:8000.

First-time account

The Web UI requires a JWT-authenticated user. Create one via the registration endpoint:

curl -X POST http://localhost:8000/api/v1/auth/register \
     -H 'Content-Type: application/json' \
     -d '{"username":"you","email":"you@example.com","password":"…"}'

The first user registered is automatically granted admin role.

Ports summary

Authentication notes

• Bearer JWT for browsers — obtain via POST /auth/login.
• API keys (cgx_live_…) for SDK and scripting use — manage at /auth/api-keys.
• WebSocket auth uses Sec-WebSocket-Protocol: ["bearer", "<jwt>"] (browser-compatible) or Authorization: Bearer <jwt> header (CLI/SDK).