Sysadmin Chronicles

A native Linux game where you work as a junior sysadmin at Axiom Works, handling real tickets inside real Linux virtual machines managed by QEMU/KVM.

Status: Node.js server + Svelte HUD implemented. Server, frontend, and all services are built. Pending: Phase 7 workstation VM verification + Phase 10 full playtest.

---

Architecture Summary

The game runs as a Node.js server on the host, serving a Svelte web HUD into the workstation VM's browser. The player works inside a real XFCE desktop.

Host machine
├── Node.js game server (port 3000) — quest logic, validation, VM control
└── Svelte HUD — tickets, mail, Sage, docs (served by game server)

Workstation VM (sc-workstation / ares) — Debian 12 XFCE desktop
├── Chromium → http://192.168.100.1:3000  (HUD, auto-opens on login)
└── Tilix → SSH to hermes/vulcan          (real terminal, real SSH)

Target VMs (headless)
├── sc-web-server (hermes)   — Q002–Q005, Q007
└── sc-build-machine (vulcan) — Q006, Q008

Quest completion is validated by the server SSHing into the target VM and evaluating real system state — not by tracking commands typed.

---

Quick Start (Development)

Prerequisites

# Install host dependencies
sudo apt install qemu-system-x86_64 libvirt-daemon-system virsh qemu-img \
                 nodejs npm virt-viewer

# Add yourself to the libvirt group
sudo usermod -aG libvirt $USER && newgrp libvirt

First-Time Setup

# Check host capabilities
bash tools/setup/check-host.sh

# Create libvirt networks, storage pool, and SSH keys
bash tools/setup/first-run-setup.sh

# Build VM images and provision quest baselines
bash tools/setup/seed-vms.sh

Build the Frontend

cd frontend && npm install && npm run build && cd ..

Run the Game

# Start game server + open workstation VM via SPICE
bash scripts/start-game.sh

# Or run server only (for development/testing)
cd server && npm install && node src/index.js

Validate Content

node tools/content/validate-content.js --verbose

Run Server Tests

cd server && npm test

---

Project Structure

sysadmin-chronicles/
│
├── server/                     Node.js game server
│   └── src/
│       ├── index.js            Entry point — Express + WebSocket
│       ├── routes/             REST API routes
│       └── services/           ContentLoader, QuestEngine, ValidationEngine, etc.
│
├── frontend/                   Svelte web HUD
│   ├── src/                    Components, api.js
│   └── dist/                   Built output (served by game server)
│
├── scripts/
│   └── start-game.sh           Start server + open SPICE viewer
│
├── content/                    All game content (JSON — unchanged)
│   ├── quests/                 Q001–Q008
│   ├── tickets/                T001–T008
│   ├── incidents/              I001–I003
│   ├── dialogue/               All NPC dialogue files
│   ├── vm_profiles/            workstation, web_server, build_machine
│   └── progression/            trust_unlocks.json
│
├── tools/
│   ├── setup/                  check-host.sh, first-run-setup.sh, seed-vms.sh
│   ├── vm/                     build scripts, quest-prep/, suppress-maintenance-noise.sh
│   └── content/                validate-content.js, verify-clue-fingerprints.js
│
├── docs/
│   ├── ARCHITECTURE.md         System design
│   ├── ROADMAP.md              Phase tracking
│   └── QUEST_AUTHORING.md      Content authoring guide

---

Key Design Rules

• Game server is the single source of truth — frontend only displays results
• Validation is server-side only — SSH into VMs, evaluate real system state
• Quest completion is state-based only — never command-sequence tracking
• Only operate on sc- prefixed libvirt domains
• Content JSON is read-only at runtime — ContentLoader reads once at startup
• Save file is at ~/.local/share/sysadmin-chronicles/save.json

---

Current Build State

Done

• Node.js game server with all services (ContentLoader, QuestEngine, TicketService, ValidationEngine, VMManager, TrustSystem, ProgressionSystem, EmailService, SageService, ShiftTimer, IncidentScheduler, ShiftReviewService, CertificationService)
• All REST routes (tickets, mail, docs, sage, state, vms, session)
• Svelte frontend with all panels (Tickets, Mail, Docs, Sage, VMs, Header)
• Built frontend (frontend/dist/) served by game server
• Content: Q001–Q008, T001–T008, I001–I003, all dialogue, world_flags, trust_unlocks
• Content validator: validate-content.js exits zero

Pending

• Phase 7: verify XFCE workstation VM (SPICE display, Chromium autostart, Tilix default)
• Phase 10: full end-to-end playtest (Q001→Q002 with real VMs)