Development

Development

Server (Rust)

Requires PostgreSQL and DATABASE_URL if not using defaults.

cd server
cargo run

Runs migrations from server/migrations on startup.

Frontend (React + Vite)

cd frontend
npm install
npm run dev

Use the Vite dev server for UI work; point it at your API/WebSocket URLs as needed.

Agent

On Windows: cargo build / cargo run from agent/. From Linux, use cargo xwin for Windows release builds.

HTTP API and WebSockets (overview)

Path	Purpose
GET /healthz	Health; exempt from HTTPS enforcement when ENFORCE_HTTPS=true.
POST /api/login	Dashboard login.
POST /api/logout	Clear session.
GET /api/auth/config	Tells the SPA whether OIDC is enabled.
GET /api/auth/status	Session status.
GET /api/auth/oidc/login	Redirect to the configured OIDC provider.
GET /api/auth/oidc/callback	OIDC callback handler; validates tokens and creates a dashboard session.
GET /ws/agent	Agent WebSocket (name, secret query params).
GET /ws/view	Viewer WebSocket (needs session when dashboard authentication is required).
GET /api/...	REST API — see server/src/api.rs in the repo for the full list.

When dashboard authentication is required (dashboard users exist and insecure opt-in is not enabled), /api/* (except auth endpoints) and /ws/view require a valid session cookie.

CSRF for mutating API requests

After login, the server requires a per-session CSRF token on mutating requests (POST/PUT/PATCH/DELETE).

• Login: POST /api/login expects JSON {"username":"...","password":"..."}; it sets the session cookie (HttpOnly) and returns { "csrf_token": "..." } in the JSON response.
• Mutations: send header X-CSRF-Token: <csrf_token> to protected mutating endpoints.

Viewer role permissions (agent control)

Over GET /ws/view, only operator/admin users can send agent control commands; viewers with the viewer role only receive telemetry.

Troubleshooting

Symptom	What to check
HTTP 426 / “HTTPS required”	ENFORCE_HTTPS=false for direct HTTP, or fix the proxy so it sends X-Forwarded-Proto: https.
Login fails on plain HTTP	COOKIE_SECURE=true in .env can break HTTP-only access.
Agents fail / 401 on /ws/agent	Set AGENT_SECRET on the server; AGENT_PASSWORD on the agent must match. URL must include /ws/agent.
“UI_PASSWORD not configured”	Set ADMIN_PASSWORD (or UI_PASSWORD) to bootstrap the first dashboard user, or enable the insecure opt-in (not recommended).
Database errors	DATABASE_URL, Postgres running, firewall, credentials.
Traefik issues	Network, TRAEFIK_HOST, entrypoints, cert resolver names match Traefik config.

License

MIT — see the LICENSE file in the repository.