Usage

Usage

Dashboard

1. Sign in with the bootstrap admin password (ADMIN_PASSWORD or legacy UI_PASSWORD) (the UI calls POST /api/login).
2. Overview lists agents; open one for detail views.
3. Per-agent views can include window focus, keystroke sessions, URLs, activity timelines, screen (MJPEG / still), software inventory, files, scripts (if enabled on the server), and agent settings (e.g. retention).
4. Global settings may cover retention, storage, audit review, and related options.
5. Audit lists operator actions where implemented.

Remote script execution is off unless ALLOW_REMOTE_SCRIPT_EXECUTION=true on the server. Enabling it is effectively arbitrary code execution on monitored machines.

Windows agent

What to configure

• WebSocket URL including path /ws/agent, for example:
  • wss://192.168.1.10:9000/ws/agent
  • wss://monitor.example.com/ws/agent
• The agent refuses ws:// URLs and requires wss:// (TLS).
• Display name (defaults to Windows COMPUTERNAME).
• Shared secret matching server AGENT_SECRET. On the agent this is the agent password / environment variable AGENT_PASSWORD (the client does not use the name AGENT_SECRET).

The agent sends ?name=<name>&secret=<secret> on the WebSocket URL when a secret is set.

Settings window (default)

Configure server URL, name, and secret in the agent settings window. The agent runs without a normal taskbar entry; the window is hidden until you open it with the global hotkey Ctrl+Shift+F12.

Closing the window hides it (it does not terminate the process). Only Exit Agent terminates.

Settings are stored under %LOCALAPPDATA%\sentinel\config.dat (DPAPI-encrypted).

Headless / automation

Non-empty environment variables override saved config:

Variable	Purpose
AGENT_SERVER_URL	Base WebSocket URL including /ws/agent (query string added by the agent).
AGENT_NAME	Agent display name.
AGENT_PASSWORD	Must match server AGENT_SECRET.

Also useful:

• --no-ui or AGENT_NO_UI
• --show-ui or AGENT_SHOW_UI
• AGENT_LOG_FILE
• RUST_LOG

Build

From the agent/ directory:

cd agent
cargo xwin build --release

Output path depends on the target (e.g. target/x86_64-pc-windows-msvc/release/sentinel-agent.exe).

HTTPS, cookies, and reverse proxies

• TLS termination at a proxy: The proxy should send X-Forwarded-Proto: https. Then ENFORCE_HTTPS=true is appropriate, and session cookies can use secure settings when login is seen as HTTPS.
• For WebSocket upgrades, the proxy may set X-Forwarded-Proto: wss (Sentinel treats wss as TLS).
• Plain HTTP only: Set ENFORCE_HTTPS=false. Do not force COOKIE_SECURE=true unless the browser really uses HTTPS to the origin.

For agents, the WebSocket URL must be wss:// (TLS). Even if the dashboard runs on plain HTTP, ensure TLS exists for /ws/agent.