ROBUST grid services server

← Back to docs · Operator guide · Integration architecture · Container deployment

ROBUST is the grid services process. It handles login, asset storage, inventory, user accounts, presence, grid registration and every other service that regions and viewers share. The name comes from C# OpenSimulator, where the same process serves the same role. Welkin's welkin-robust binary is a wire-compatible replacement.

What it does

ROBUST listens on two ports. The public port (default 8002) faces viewers and serves XML-RPC login, LLSD login, grid info and map tiles. The private port (default 8003) faces regions and serves all service-to-service traffic: asset fetch/store, inventory queries, grid registration, presence updates, friends, groups, profiles, estates, auth, agent preferences, mute lists, offline IM, map image upload and authorization.

The split keeps inter-service endpoints off the public network. In production, only port 8002 needs to be reachable by viewers. Port 8003 should be restricted to the region hosts.

Services hosted

ServicePortProtocolRole
LoginpublicXML-RPC, LLSDViewer authentication, session creation
Grid infopublicJSON (GET)Grid name, login URI for viewer discovery
Map tilespublicHTTP GETMap tile images for the viewer world map
AssetprivateLLSDStore and retrieve assets (textures, meshes, scripts)
InventoryprivateLLSDFolder tree, item CRUD, library folders
GridprivateLLSDRegion registration, lookup, neighbour queries
PresenceprivateLLSDWho is online and where
GridUserprivateLLSDLast-seen region, home location
AccountsprivateLLSDUser account CRUD, search
AuthprivateLLSDPassword verification, token management
AuthorizationprivateLLSDAccess control checks
AvatarprivateLLSDBaked appearance data
FriendsprivateLLSDFriend list, online notifications
Agent preferencesprivateLLSDPer-user settings
MuteprivateLLSDMute list storage
Offline IMprivateLLSDStore and deliver offline messages
GroupsprivateLLSDGroup membership, notices, roles
EstateprivateLLSDEstate settings, access lists
ProfilesprivateLLSDUser profiles, picks, classifieds

Configuration

ROBUST reads robust.toml by default (override with --config <path>). The minimal configuration sets just the database connection:

[DatabaseService]
ConnectionString = "Server=localhost;Port=3306;Database=opensim;User=opensim;Password=secret"

For SQLite (development only):

[DatabaseService]
ConnectionString = "sqlite:robust.db?mode=rwc"

Environment variables override any TOML setting. The format is OPENSIM__Section__Key=value:

OPENSIM__DatabaseService__ConnectionString="Server=db;Port=3306;Database=opensim;User=opensim;Password=secret"

See the operator guide for the full configuration reference, including database setup for MariaDB, PostgreSQL and SQLite.

Running

Command line

welkin-robust --config robust.toml --public-port 8002 --private-port 8003

All flags have defaults, so a bare welkin-robust works for local development if robust.toml exists in the working directory.

FlagDefaultPurpose
--configrobust.tomlPath to the TOML configuration file
--public-port8002TCP port for login, grid info and map tiles
--private-port8003TCP port for service-to-service traffic

With a region

Start ROBUST first, then the region simulator:

# Terminal 1: grid services
welkin-robust

# Terminal 2: region simulator
welkin-region --config welkin.toml

The region connects to ROBUST's private port to register itself, fetch inventory and assets, and report presence changes. The viewer connects to ROBUST's public port to log in, then to the region's UDP and HTTP ports for in-world traffic.

With Podman Compose

The repository's compose.prod.yaml starts the full stack (database, ROBUST, region). See the container guide for details.

With systemd

The installer creates a welkin-robust.service unit:

sudo systemctl enable --now welkin-robust
journalctl -u welkin-robust -f

Health and monitoring

ROBUST exposes /health (returns ok, HTTP 200) and /metrics (Prometheus text format) on both ports. Use /health for load balancer probes and container orchestration readiness checks.

Key metrics to watch:

  • opensim_caps_requests_total: HTTP request throughput across services
  • Login latency and error rate (from the XML-RPC login handler)
  • Database connection pool usage (from sqlx metrics)

Database

ROBUST uses welkin-data to access 13 typed stores over sqlx. It supports MariaDB 10.5+, PostgreSQL 14+ and SQLite. On first startup the migration runner applies 53 embedded SQL files matching the C# OpenSimulator schema. An existing C# database opens without modification.

Run osim-migrate validate-db before connecting to a database that was created by C# OpenSimulator, to confirm schema compatibility.

Security notes

The private port serves all inter-service endpoints without authentication. These endpoints trust that callers are authorized region processes. In production, restrict port 8003 to region hosts using firewall rules or network segmentation. Do not expose it to the public internet.

The public port serves login (which accepts passwords) and grid info (read-only). Place a reverse proxy with TLS in front of port 8002 for production use. ROBUST itself serves plain HTTP.

See the operator guide for TLS setup, firewall recommendations and rate limiting.

Relationship to C# OpenSimulator

Welkin's ROBUST speaks the same wire protocol as C# OpenSimulator's Robust.exe. A Welkin region can connect to a C# ROBUST, and a C# region can connect to a Welkin ROBUST. This makes incremental migration possible: replace one component at a time while the rest of the grid keeps running.

See the migration guide for the full migration process.