# Wolloseum Wolloseum is a deterministic, procedurally generated game server. Players upload untrusted WASM agents that control spawned agents in a tick-based simulation. Agent code runs in a sandboxed Extism/Wasmtime runtime with fuel and memory limits. Identity is based on Ed25519 keypairs. The server stores public keys; private keys stay with their owners. HTTPS and WSS termination are intended to be provided by a reverse proxy such as nginx or Caddy. The Wolloseum process serves HTTP and does not create TLS certificates. ## Build and Run ```sh cargo build --release cargo run --release -- serve --data-dir data --bind 127.0.0.1:8080 ``` ### Docker Build and start the server with Docker Compose: ```sh docker compose up --build -d docker compose logs -f wolloseum ``` The HTTP service is published on `127.0.0.1:8080`; configure nginx or Caddy to proxy HTTP and WebSocket traffic to that address and terminate TLS. Compose stores the SQLite database and generated administrator keypair in `./data`. The entrypoint sets the data tree's ownership before starting the server as an unprivileged user. Set `WOLLOSEUM_UID` and `WOLLOSEUM_GID` in the environment or a Compose `.env` file to choose the container process identity. Both default to `1000`. The ownership of the host `./data` tree is changed to these IDs at startup. The first startup logs the administrator identity ID and identity bundle path inside the container. Copy the bundle to a secure host location for admin sign-in: ```sh docker compose cp wolloseum:/var/lib/wolloseum/keys/admin-identity.json /secure/path/admin-identity.json chmod 600 /secure/path/admin-identity.json ``` Back up the key and database volume. To stop the server while preserving data, run `docker compose down`. To remove all persistent identity and game data as well, run `docker compose down --volumes`. The server bootstraps an administrator keypair on first start: - `data/keys/admin-private.pem` is the owner-only Ed25519 PKCS#8 private key. - `data/keys/admin-identity.json` is the owner-only bundle used by browser sign-in. - The server prints the corresponding identity ID at startup. - Keep a secure backup of the private key. The server cannot recover it. Existing installations continue to use `data/certificates/admin-client-key.pem` and the old certificate fingerprint as the admin identity ID when those legacy files are present. Existing player identities and uploaded data remain in the SQLite database. HTTPS certificates, if needed, belong to the reverse proxy. Configuration flags and environment variables: | Flag | Environment variable | Default | Purpose | | ------------ | -------------------- | ---------------- | ------------------------------------------- | | `--data-dir` | `WOLLOSEUM_DATA_DIR` | `data` | Keypairs and SQLite database directory | | `--bind` | `WOLLOSEUM_BIND` | `127.0.0.1:8080` | HTTP listener, usually private to the proxy | ## Web Interfaces - `/` is the player console. Every identity, including moderators and administrators, can act as a player and upload or replace its own agent WASM. - `/admin` is the privileged console. Moderators manage player accounts; administrators can also manage roles, simulation settings and world state, and replace the core WASM module. - `/viewer` is a public live event viewer. It connects to `/api/events`, tracks event sequence numbers, and restores state from snapshots after reconnecting. The admin console generates a fresh Ed25519 keypair when creating a user. The server receives only the public key. The browser downloads a JSON identity bundle containing the new identity ID and private key; deliver that bundle to the user through a secure channel. The private key is not stored by the server. Administrators can promote users to moderator or administrator roles. Sign in on either page by selecting the JSON identity bundle. Protect `data/keys/admin-identity.json` like the private key; the older PEM key remains available for CLI compatibility. ## Browser Authentication 1. The browser reads the identity ID and private key from the selected JSON bundle. 2. The browser requests `POST /api/auth/challenge` with `{ "client_id": "..." }`. 3. The server returns a random, short-lived challenge. 4. The browser signs the decoded challenge bytes using Ed25519 and posts the identity ID, challenge, and base64 signature to `POST /api/auth/login`. 5. The server verifies the signature against the stored public key and returns an opaque session token. 6. The browser stores the token and sends it as `Authorization: Bearer ` on protected API requests. Challenges expire after five minutes and are single-use. Session tokens expire seven days after the last authenticated API interaction. Each authenticated request extends the expiry. Only a SHA-256 hash of each token is persisted. Revoking an identity by deleting it also removes its sessions. ## API | Method | Path | Access | Purpose | | ------ | --------------------- | ---------------- | --------------------------------------------------------- | | `POST` | `/api/auth/challenge` | Public | Request an identity challenge | | `POST` | `/api/auth/login` | Public | Verify a signed challenge and issue a token | | `GET` | `/api/me` | Session | Read the signed-in identity and agent status | | `GET` | `/api/users` | Mod or admin | List identities and agent digests | | `GET` | `/api/status` | Public | Read the simulation running state | | `GET` | `/api/settings` | Admin session | Read simulation calendar, activation, and tick interval | | `PUT` | `/api/settings` | Admin session | Update simulation calendar, activation, and tick interval | | `GET` | `/api/state` | Admin session | Download the current state bundle | | `POST` | `/api/state` | Admin session | Validate and restore a state bundle | | `POST` | `/api/reset_world` | Admin session | Regenerate the world while preserving other records | | `GET` | `/api/events` | Public WebSocket | Receive snapshots and ordered state events | | `POST` | `/api/create_user` | Mod or admin | Register a username and base64 Ed25519 public key | | `POST` | `/api/delete_user` | Mod or admin | Delete a player and its uploaded agent | | `POST` | `/api/set_role` | Admin session | Assign player, moderator, or administrator role | | `POST` | `/api/start_game` | Admin session | Resume the simulation | | `POST` | `/api/stop_game` | Admin session | Pause the simulation | | `POST` | `/api/update_agent` | User session | Queue or replace the caller's next agent WASM | | `POST` | `/api/upload_core` | Admin session | Upload or replace the core simulation WASM | Agent and core WASM uploads are limited to 1 MiB and validated in the sandboxed runtime before they are persisted. Existing signed request headers remain accepted for compatibility with older clients. Agent uploads replace that player's queued module; the active module remains in use until the selected update boundary. The admin console configures ticks per day, days per week and month, and whether queued agents activate between ticks, days, weeks, or months. Defaults are 86400 ticks per day, 7 days per week, 30 days per month, activation between ticks, and a 100 ms delay between ticks. The delay can be set from 1 to 60000 milliseconds. State downloads contain the current world, simulation settings, run state, user public identities, active and queued agent modules, and core module. They do not contain private keys or login sessions. Restoring a bundle requires it to retain the active administrator performing the restore. Resetting creates a fresh random world while preserving settings, users, agents, and the active core. ## Rust APIs The `agent-api` crate defines typed observations, actions, and the `Agent` trait. The `core-api` crate defines serialized tick input/output and the `Core` trait. `default-core/` implements `Core`; `example-wasm-agent/` implements `Agent` and adapts it to the Extism ABI. Both API crates are workspace members and can be used as dependencies when authoring new implementations. The server uses the native Rust implementation in `default-core/` until a core is uploaded. An uploaded core replaces it and must export an Extism `tick` function that accepts `CoreTickInput` JSON (`world` and `actions`) and returns `CoreTickOutput` JSON (`world`). Build the default implementation as a WASM core with: ```sh cargo build --manifest-path default-core/Cargo.toml \ --target wasm32-unknown-unknown --release ``` Upload `target/wasm32-unknown-unknown/release/default_core.wasm` from the admin console to run that same implementation through the WASM path. ## CLI The binary also provides an authenticated client. New installations use the admin keypair directly: ```sh cargo run --release -- cli \ --client-key data/keys/admin-private.pem \ create-user alice ``` `create-user` prints the identity ID and private key as JSON. For commands run as a player, use that player's private key and identity ID: ```sh cargo run --release -- cli \ --client-id \ --client-key alice-private.pem \ update-agent example-wasm-agent/target/wasm32-unknown-unknown/release/example_wasm_agent.wasm ``` Legacy installations can pass `--client-cert` and `--client-key` to derive the historical certificate-based admin ID. The CLI exchanges a challenge for a session token before making protected requests. ## Example Agent `example-wasm-agent/` is a standalone crate implementing the Extism plugin ABI used by `src/wasm_agent.rs`. Build it with: ```sh cd example-wasm-agent rustup target add wasm32-unknown-unknown cargo build --release --target wasm32-unknown-unknown ``` The compiled module is at `example-wasm-agent/target/wasm32-unknown-unknown/release/example_wasm_agent.wasm`.