Quick start

← Back to docs · Architecture · Configuration reference

Requirements

  • Rust 1.88 or later (edition 2024)
  • SQLite (MariaDB and PostgreSQL are supported in the code but not yet verified)
  • A viewer: Aurora Viewer or Firestorm (OpenSim build)

Build

git clone https://github.com/FlintWave/welkin.git
cd welkin
cargo build --workspace --release

This produces two binaries in target/release/:

  • welkin-robust runs the grid services (login, inventory, assets, grid registry)
  • welkin-region runs the region simulator (scene, physics, scripting, viewer connections)

Configure

Welkin uses TOML configuration files. A minimal setup needs two:

robust.toml (grid services):

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

welkin.toml (region simulator):

[Region]
RegionName = "Test Region"
RegionLocX = 1000
RegionLocY = 1000

[Network]
ExternalHostName = "127.0.0.1"
InternalPort = 9000

[DatabaseService]
RegionConnectionString = "sqlite:region.db?mode=rwc"
RobustConnectionString = "sqlite:robust.db?mode=rwc"

[GridService]
GridServerURI = "http://127.0.0.1:8003"

[Scene]
PhysicsEnabled = true
ScriptsEnabled = true

Any setting can be overridden with an environment variable using the pattern OPENSIM__Section__Key=value. For example, OPENSIM__Region__RegionName=MyRegion overrides the region name without editing the file.

If you are migrating from a C# OpenSimulator installation, welkin-migration can import your existing .ini configuration files.

See the configuration reference for all available sections and keys.

Default assets

Welkin does not include the default avatar assets (body parts, clothing, animations and sounds). They are Linden Lab viewer art under CC BY-SA 2.5, which the OpenSimulator source tree labels in bin/data/LICENSE-README-IMPORTANT.txt, and that license does not fit LGPL-3.0-or-later. Copy the bin/assets folder from an OpenSimulator 0.9.3.0 install so that it sits beside welkin-robust, as assets/AssetSets.xml, or set [AssetService] AssetLoaderArgs in robust.toml to the path of your AssetSets.xml. On start, welkin-robust loads the sets into a fresh robust.db (432 assets, 12.6 MB) and skips anything already stored, so restarts are safe. Without the folder it logs a warning and avatars stay untextured. AssetLoaderEnabled = false turns the loader off.

Run

Start the grid services first, then the region simulator:

# Terminal 1: grid services (public port 8002, private port 8003)
./target/release/welkin-robust --config robust.toml

# Terminal 2: region simulator (UDP 9000)
./target/release/welkin-region --config welkin.toml

The web portal and its first-run wizard do not work yet; the portal crate is a scaffold (see Grid Portal). Account creation and region placement through the portal are not available.

Connect a viewer

Point your viewer at the login URI http://127.0.0.1:8002/:

  • Aurora Viewer: launch with --loginuri http://127.0.0.1:8002/
  • Firestorm: open Grid Manager, add a new grid with the login URI above, then select it and log in

Log in with an existing user account on the grid.

Standalone vs external grid

The steps above run a standalone grid: both binaries on one machine with a local database. To connect a region to an existing grid instead, change GridServerURI in welkin.toml to point at that grid's private service endpoint. The region registers itself with the remote ROBUST and appears on the grid map.

For OSGrid, set GridServerURI to OSGrid's grid service URL and follow their registration process. See OSGrid compatibility for details.