Development

Development

Server (Rust)

Requires PostgreSQL and a valid **DATABASE_URL** unless you use the default in server/src/config.rs.

cd server
cargo run

Runs SQL migrations from server/migrations on startup.

---

Frontend (React + Vite)

cd frontend
npm install
npm run dev

Use the Vite dev server for UI work; configure it to talk to your API and WebSocket endpoints (see environment / proxy settings in the frontend as needed).

---

Agent

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

---

HTTP API and WebSockets (overview)

Paths below reflect server/src/main.rs and server/src/api/mod.rs in the repository.

Unauthenticated (or special-case) HTTP

Path	Purpose
GET /healthz	Liveness — always allowed even when ENFORCE_HTTPS=true.
GET /readyz	Readiness (includes database check).
GET /metrics	Prometheus metrics when METRICS_ENABLED=true (default).
POST /api/login	Dashboard login (JSON body).
POST /api/logout	Clear session.
GET /api/auth/status	Session status.
GET /api/auth/config	Whether OIDC is enabled, etc.
GET /api/auth/oidc/login	OIDC redirect.
GET /api/auth/oidc/callback	OIDC callback.
POST /api/agent/enroll	Exchange enrollment code for per-device agent token (rate-limited per IP).
GET /api/integration/agents/live	Optional JSON integration feed when **INTEGRATION_API_TOKEN** is set; requires Authorization: Bearer ….

WebSockets

Path	Purpose
GET /ws/agent	Agent connection. Query params: name, secret (or per-device token semantics — see server auth).
GET /ws/view	Dashboard viewer stream (requires session when auth is enforced).

Authenticated REST (/api/*)

Nested under **/api** with session + CSRF for mutating methods. Major groups:

• Agents & telemetry: /api/agents, /api/agents/:id/info, /windows, /keys, /urls, /activity, /alert-rule-events, /software, /screen, /mjpeg, /logs/…, /analytics/…, etc.
• Rules & policies: /api/alert-rules, /api/agent-groups, /api/app-block-rules, /api/internet-block-rules, /api/scheduled-scripts, …
• URL categorization (admin): /api/settings/url-categorization/…
• Users & audit: /api/users, /api/audit, …
• Settings: /api/settings/… (retention, enrollment tokens, storage, capabilities, …)

For the authoritative route list, open **server/src/api/mod.rs** — it is the single source of truth.

When dashboard authentication is required (users exist and insecure open-dashboard mode is off), **/api/*** except the auth/enrollment paths above and **/ws/view** require a valid session cookie.

---

CSRF for mutating API requests

After login, the server expects a per-session CSRF token on **POST**, **PUT**, **PATCH**, and **DELETE** to protected APIs.

• **POST /api/login** returns { "csrf_token": "..." } in JSON and sets the **session** cookie (HttpOnly).
• Mutations: send header **X-CSRF-Token: <csrf_token>**.

---

Viewer role permissions (agent control)

Over **GET /ws/view**, only **operator** and **admin** users can send agent control commands; **viewer** users receive telemetry only.

---

Background jobs

• Scheduler — Runs scheduled app/internet/script rules in the server’s configured timezone (**SCHEDULER_TIMEZONE**, default UTC). Set to an IANA zone name (e.g. America/New_York).
• Retention — Periodic cleanup driven by **RETENTION_INTERVAL_SECS** and optional per-table retention env vars (see Configuration).
• URL categorization — Optional import/categorization worker (see URL categorization settings).

---

Troubleshooting

Symptom	What to check
HTTP 426 / “HTTPS required”	Set **ENFORCE_HTTPS=false** for direct HTTP, or fix the proxy so it sends **X-Forwarded-Proto: https** (or **wss** for WebSocket upgrades).
Login fails on plain HTTP	**COOKIE_SECURE=true** in .env can break cookie handling if the browser is not using HTTPS to the origin.
Agents fail / 401 on /ws/agent	**AGENT_SECRET** must match **AGENT_PASSWORD** on the agent when using shared secret; otherwise enroll the agent and use the per-device token. URL must include **/ws/agent**.
“UI_PASSWORD not configured” / cannot log in	Set **ADMIN_PASSWORD** (or **UI_PASSWORD**) for first-user bootstrap, or enable the insecure dashboard opt-in (not recommended).
Database errors	**DATABASE_URL**, Postgres running, credentials, firewall.
Traefik 404 / 502	**Host()** router rule matches the browser hostname; backend URL points at the host’s Sentinel HTTP port (often 9000). See Deployment → Traefik + mDNS.
Migration checksum errors	Follow the message emitted by the server (rebuild from the same migration files, fix _sqlx_migrations as documented in server/src/main.rs).

---

License

MIT — see the LICENSE file in the repository.