Rust Sentinel

A self-hosted Rust+ companion for live server awareness, smart-device monitoring, and raid planning.

React 19 · TypeScript · Fastify · WebSocket/Protobuf · PWA · Docker

Quick start · Architecture · Server pairing · Validation

Overview

Rust Sentinel connects a persistent backend to the Rust+ companion interface and presents the available server data in a mobile-friendly web app. It combines an interactive map, team and shop information, a smart-device registry, an event timeline, a base-planning workspace, and a resource-aware raid calculator.

The application targets desktop browsers and installation as a PWA, with a Ukrainian interface. Rust refers to the game; the main application is written in TypeScript. The optional Windows pairing helper is written in C#.

Current source snapshot: v0.12.5. Live integrations require a Rust+ enabled server and your own authorized pairing credentials. Without a connection, the interface starts with an empty offline state.

Features

Live map and server awareness

• Rust+ map-image loading and local caching.
• Team positions, team chat, monuments, event markers, map notes, and vending-shop data exposed by Rust+.
• Click-to-inspect map objects, search for shop inventory, and independent map-layer filters.
• Readable map grid with a separate label toggle and wrapping filter controls on narrow screens.
• Quick-start area scoring and terrain-based estimates for likely ore zones.

Ore overlays are estimates from visible terrain, not live resource-node coordinates. Sleeping-bag tracking was removed in an earlier release and is not a current feature.

Smart devices and base monitoring

• Persistent device registry, Smart Switch controls, Smart Alarm events, and Storage Monitor inventory changes.
• Inventory aggregation, configurable resource thresholds, and consumption estimates from monitored observations.
• Manual base layout and sensor-role configuration.
• Raid Intelligence that correlates signals such as alarms, device unavailability, inventory loss, and nearby deaths.
• Confidence, signal expiry, cooldowns, and a local incident timeline.

Raid Intelligence is an inference from available signals, not an authoritative server raid event.

Raid planning

• Multiple targets and quantities, grouped targets with equivalent cost profiles, and mixed attack methods.
• Strategies for resource cost, speed, or a single method.
• Raw-resource totals, intermediate crafting, reserve amounts, stacks, and comparison against available inventory.
• Versioned raid and item data, with fallback behavior for unknown item IDs.

Integration and delivery

• Custom Rust+ WebSocket/Protobuf client with polling, reconnect handling, diagnostics, and synchronization guards.
• Server-Sent Events to stream backend state to the frontend.
• AES-256-GCM storage for pairing credentials when an encryption key is configured.
• Optional Steam/Facepunch pairing flow through a local Windows helper and FCM listener.
• Web Push support requiring VAPID configuration and a suitable HTTPS deployment.
• Docker Compose configuration with a Caddy reverse proxy and persistent volumes.

Architecture

flowchart LR
    A[Rust+ server] <-->|WebSocket and Protobuf| B[Fastify backend]
    B --> C[Domain rules and event pipeline]
    C --> D[Local persistence]
    C --> E[Web Push]
    B -->|Server-Sent Events| F[React PWA]
    F -->|HTTP commands| B
    G[Local C# pairing helper] --> B

Loading

Location	Responsibility
apps/web	React/Vite UI, interactive map, PWA manifest, service worker
apps/api	Fastify endpoints, Rust+ worker, persistence, pairing, notifications
packages/domain	Shared types, detectors, grid geometry, quick-start scoring, raid calculations
catalog	Versioned fallback item catalog
tools/pairing-helper	Optional Windows/.NET pairing integration
docs	Technical notes and release history

Quick start

Requires Node.js 22+ and npm.

git clone https://github.com/L1BBER/rust-sentinel.git
cd rust-sentinel
npm ci
Copy-Item apps/api/.env.example apps/api/.env
npm run build -w @rust-sentinel/domain
npm run dev

The shared domain package must be built before first development startup because its exports point to dist/.

• Frontend: localhost:5173
• API: localhost:8787
• Health endpoint: localhost:8787/api/health

The API development command runs in apps/api, so use apps/api/.env for local npm development. The root .env.example is intended for Docker Compose. Keep all actual environment files out of Git.

For a strictly offline preview, set ITEM_CATALOG_REMOTE_ENABLED=false in apps/api/.env; otherwise the backend may refresh its item catalog from the configured external source.

Connect a Rust server

For the supplied Windows/Docker pairing workflow, install Docker Desktop and use Chrome or Edge for the official login flow:

Copy-Item .env.example .env
# Configure DOMAIN/PUBLIC_APP_URL for your intended local or hosted deployment.
powershell -ExecutionPolicy Bypass -File .\scripts\connect-rust-server.ps1

Review the script before running it: it builds and starts Docker services, generates local setup secrets, builds the pairing helper, and opens the login flow. Follow the in-game Pair with Server step using your own account. See connection details.

The API also supports explicit RUSTPLUS_SERVER, RUSTPLUS_PORT, RUSTPLUS_PLAYER_ID, and RUSTPLUS_PLAYER_TOKEN settings. Do not commit or share their real values.

Build and test

GitHub Actions CI runs the offline tests, lint and production build on pushes and pull requests using Node.js 22. It does not connect to a live game server or perform pairing.

npm test
npm run lint
npm run build

Start the built application:

$env:NODE_ENV = 'production'
npm start

The backend serves the built frontend from apps/web/dist. Set PUBLIC_APP_URL to the actual origin. The optional helper has a separate command, npm run build:pairing, which requires a suitable .NET SDK; the Docker workflow can build it in a container.

See validation results for checks performed on this source snapshot. Offline tests do not establish that Steam pairing, a live Rust+ connection, push delivery, or a VPS deployment has been verified.

Deployment and security boundaries

• Use this as a private companion for your own authorized server pairing.
• The setup-import token protects the setup flow; it is not a complete user-authentication system for the dashboard. Add access control at the reverse proxy or VPN before making the service reachable outside a trusted network.
• Keep .env, pairing files, device data, player identifiers, push subscriptions, and runtime logs private. The source import excludes the supplied configured .env and generated state files.
• Never publish encryption keys alongside encrypted credentials.
• Push delivery depends on platform support, permission, VAPID keys, and a valid HTTPS configuration.
• Rust+ data availability and game balance can change. Treat estimates and bundled catalog values as versioned inputs, not guarantees.

Documentation and notices

• Architecture notes
• Map behavior
• Raid planner
• Terrain estimates
• Change history
• Third-party notices

Some archived release notes describe older versions; this README summarizes the v0.12.5 code. Rust Sentinel is unofficial and is not affiliated with Facepunch Studios or Valve. The supplied third-party notices are preserved; no new project-wide license has been assigned during this import.