wolloseum/README.md

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

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:

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 the key path inside the container. Copy the key to a secure host location for admin sign-in:

docker compose cp wolloseum:/var/lib/wolloseum/keys/admin-private.pem /secure/path/admin-private.pem
chmod 600 /secure/path/admin-private.pem

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.
• 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. Users sign in with their identity key and upload or replace their agent WASM.
• /admin is the administrator console. It creates and removes users, pauses or resumes the simulation, and replaces 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 player. 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 player through a secure channel. The private key is not stored by the server.

On the admin page, enter the startup identity ID and select data/keys/admin-private.pem. For an existing installation, select the legacy admin key and use the identity ID printed by the server.

Browser Authentication

1. The browser requests POST /api/auth/challenge with { "client_id": "..." }.
2. The server returns a random, short-lived challenge.
3. The browser signs the decoded challenge bytes using Ed25519 and posts the identity ID, challenge, and base64 signature to POST /api/auth/login.
4. The server verifies the signature against the stored public key and returns an opaque session token.
5. The browser stores the token and sends it as Authorization: Bearer <token> 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	Admin session	List identities and agent digests
GET	/api/status	Public	Read the simulation running state
GET	/api/events	Public WebSocket	Receive snapshots and ordered state events
POST	/api/create_user	Admin session	Register a username and base64 Ed25519 public key
POST	/api/delete_user	Admin session	Delete a player and its uploaded agent
POST	/api/start_game	Admin session	Resume the simulation
POST	/api/stop_game	Admin session	Pause the simulation
POST	/api/update_agent	User session	Upload or replace the caller's 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.

CLI

The binary also provides an authenticated client. New installations use the admin keypair directly:

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:

cargo run --release -- cli \
  --client-id <identity-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:

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.