G
GNOSIS
ASCII prison-cosmos roguelike
Menu
Browse
Home Product Characters Web wiki Bestiary Spell omnibus Technique omnibus Item omnibus Recipe omnibus Leaderboards Steam
Live server
Active characters: 5
Gryphtopher under the Black Bell
Server mode
Access
Log in Register
More
Support Privacy Terms
multiplayer_server_wiki

Gnosis Multiplayer and Server Wiki

This page has been reviewed against the current terminal/server build and the latest portal documentation surfaces. For exact live catalogs and tuning values, use the source-driven...

Updated
2026-04-19T11:06:55+00:00

Gnosis Multiplayer and Server Wiki

Documentation Freshness (2026-04-19)

  • This page has been reviewed against the current terminal/server build and the latest portal documentation surfaces.
  • For exact live catalogs and tuning values, use the source-driven portal compendiums:
    • /bestiary
    • /spell-omnibus
    • /technique-omnibus
    • /item-omnibus
    • /recipe-omnibus
  • In-game references are available through the W wiki menu (including generated spell/component compendiums).
  • World/floor map reference is in-game via P; the website map page is intentionally hidden.
  • Multiplayer host/deployment details live in docs/multiplayer_server_wiki.md and docs/server_portal_setup.md.

Current Build Delta (2026-04-19)

  • Deep floors now have a depth-scaled chance to spawn Lizard Kingdom Gates (FeatureLizardKingdomGate).
  • Using a Lizard Kingdom Gate enters Lizard Kingdom side sites (SiteLizardKingdom) with lizard society-biased populations.
  • Lizard Kingdom floors use dedicated cave themes (Outer Warrens -> Royal Sinkhalls) and integrate with map/examine/senses/clairvoyance text.
  • This update is live in terminal mode and server mode; hosted clients inherit the behavior from the game build.

This page documents the implemented multiplayer host model (gnosisd) and observer turn synchronization.

1. Scope

Primary code:

  • cmd/gnosisd/main.go
  • internal/server/server.go
  • internal/game/turnsync.go
  • docs/server_portal_setup.md

2. Runtime Model

gnosisd hosts the game and starts one game process per player session.

Supported clients:

  • SSH terminal sessions
  • browser terminal sessions (websocket + xterm.js)

The actual game remains the same Go terminal binary; server mode wraps process/session management around it.

3. Network Endpoints

Default listeners:

  • SSH :2222
  • HTTP :8080

Docker compose publishing used by the portal stack:

  • Portal HTTP 127.0.0.1:9004 -> container 8000
  • Browser websocket host 127.0.0.1:9005 -> gnosisd container 8080
  • SSH host 127.0.0.1:2222 -> gnosisd container 2222

Production public host:

  • https://gnosis.cordine.site
  • browser websocket should resolve to wss://gnosis.cordine.site/ws
  • portal production env starts from webapp/.env.production.example

Main HTTP routes:

  • /healthz
  • /api/provision
  • /api/ssh-public-key
  • /api/token
  • /ws
  • /play

4. Accounts and Authentication

Server stores account hashes in server data dir.

Auth modes:

  • SSH password auth
  • SSH public-key auth synced from the Laravel portal
  • optional SSH key-identity mode (GNOSIS_SERVER_SSH_KEY_IDENTITY=1) where profile identity is derived from the SSH key instead of the SSH username
  • optional auto-registration from SSH login (can be disabled)
  • HTTP provisioning endpoint for portal registration
  • signed websocket token flow for browser sessions

The portal stores one OpenSSH public key per SSH username and pushes updates to gnosisd through /api/ssh-public-key.

5. Per-User Save Isolation

Each account gets separate campaign persistence roots:

  • data/server/users/<username>/campaign/ (chunked runtime store)
  • .../backups/ (manual backup copies)

Session env wiring injects per-user save paths plus profile/session ids.

In dedicated locked-world mode (GNOSIS_SERVER_WORLD_CONFIG set), sessions are forced onto one configured world id/seed/setup and runtime world creation/selection menus are disabled.

6. Observer Turn Synchronization

Turn sync file path is configured by server and passed to game sessions.

Mechanic:

  • each player writes presence: region/floor/plane/position/vision/turn
  • if two players can mutually observe each other, they become synchronized
  • acting player waits until observed player resolves a turn
  • UI status line/log shows waiting state text

This applies the “observer makes state shared” rule in active sight overlap.

7. Time and Independent Simulation

When players are not mutually observing:

  • each session proceeds independently
  • normal background simulation still runs for loaded worlds

So synchronization is localized to overlapping perception, not global lockstep.

8. Browser Play

Browser path:

  • client obtains signed token
  • websocket connects /ws?token=...
  • PTY bytes are bridged bidirectionally
  • resize control messages update terminal geometry

/play provides a local lightweight xterm bootstrap page.

9. Config and Environment

Key server settings:

  • GNOSIS_SERVER_SSH_ADDR
  • GNOSIS_SERVER_HTTP_ADDR
  • GNOSIS_SERVER_DATA_DIR
  • GNOSIS_SERVER_HOST_KEY
  • GNOSIS_SERVER_REPO_DIR
  • GNOSIS_SERVER_GAME_CMD
  • GNOSIS_SERVER_SSH_KEY_IDENTITY (bind SSH session identity to SSH key fingerprint account)
  • GNOSIS_PROVISION_SECRET
  • GNOSIS_WS_SECRET
  • GNOSIS_SERVER_TURN_SYNC
  • GNOSIS_SERVER_TURN_SYNC_TTL
  • GNOSIS_SERVER_DISABLE_AUTO_USERS
  • GNOSIS_SERVER_ALLOW_INSECURE_DEFAULTS (set 1 only for local throwaway testing; production should keep this unset)
  • GNOSIS_SERVER_WORLD_CONFIG (world JSON used to lock world id/seed/setup for dedicated host mode)

Steam bundle note:

  • steam/build.sh packages gnosisd alongside the client binary.
  • host-server.sh in the bundle launches the dedicated server with save data under XDG data directories.
  • The bundled server uses the packaged gnosis binary automatically as its session game command.

Standalone Docker host note:

  • docker compose -f docker-compose.server.yml up -d --build starts a dedicated gnosisd host from this repo.
  • It publishes 2222 (SSH) and 8080 (HTTP/WebSocket) by default.
  • Root compose enables GNOSIS_SERVER_SSH_KEY_IDENTITY=1 so players are keyed by SSH public key identity.
  • Root compose defaults GNOSIS_SERVER_WORLD_CONFIG=/var/lib/gnosis-server/world-config.json.
  • If world config is missing/invalid, /healthz is not ready and sessions are refused.
  • A template is available at docker/world-config.example.json and copied into data dir as world-config.json.example.

Session/game-side turn sync envs:

  • GNOSIS_TURN_SYNC
  • GNOSIS_TURN_SYNC_TTL_SEC

10. Operational Notes

  • PTY is required for SSH sessions.
  • Host key is auto-generated if missing.
  • Token signing uses HMAC; keep websocket secret private.
  • Provision endpoint should be protected with strong secret and network policy.
  • Public-key updates use the same secret-protected portal-to-server channel as provisioning.

11. Laravel Integration

Portal/auth integration details are in:

That doc covers registration provisioning and browser play wiring.

The portal compose stack is in webapp/docker-compose.yml and expects the shared postgres_db container from /workspace/container-pgsql/ on dev-net.

Related pages: