LithosAnanke/demo

demo/ -- StarshipOS in a browser

A public "Try it" console: each visitor gets a StarshipOS machine of their own, logged in as a Zuse minted for the demo, resumed at its prompt in under a second, gone when they leave. Milestone Public demo terminal (#111-#117).

XWiki "Try it" page (iframe) -> Apache: TLS, websocket -> ttyd -> start-session.sh
                                                                   -> QEMU amd64, resumed from the saved machine
                                                                   <-> console.py <-> the visitor's terminal

The pieces

File	What it does
mint-zuse.sh	Mints a Zuse of the demo's own -- never anyone's real one -- as a stick (#111, ruled 2026-11-06)
build-iso.sh	Packs the amd64 ISO from a kernel build, as make qemu packs it
make-snapshot.sh	Boots the machine once to [zuse@Hera] ok> and saves it (#113)
start-session.sh	One visitor's session: resumes the saved machine, ends it on hang-up, close or time-out (#112)
console.py	Joins the visitor's terminal to the machine only once it runs, discarding keys typed while it loads
qemu-args.sh	The machine, shared by the two above: a resumed machine must match the saved one exactly
starshipos-demo.service	ttyd as a systemd service, on localhost; two guests at once, a busy message for the rest (#114, #116)
DEPLOY.md	Putting it on the server, step by step
apache-demo.conf	Example vhost: TLS, the websocket, framing allowed for the .com only (#115)
xwiki-try-it.xwiki	The "Try it" page, its own page on the .com XWiki (TryIt), in the landing page's style

What a visitor cannot do

Each session is a copy: the firmware variables are copied, the image is read-only, and the Zuse stick's writes are discarded (snapshot=on). The guest has no network device. QEMU runs under its seccomp sandbox (no spawning, no privilege changes), as an unprivileged user, inside a systemd unit that fences memory, CPU and the file system. A session lasts at most DEMO_SESSION_LIMIT seconds (1800).

Setting it up

From a checkout of the most recent green commit -- the latest that passed acceptance, master (or, once it is published, the nightly's StarshipOS.iso):

make ARCH=amd64 init INIT_DOCS=0
demo/mint-zuse.sh   /tmp/demo-zuse                     # once; keep the stick
demo/build-iso.sh   /tmp/StarshipOS.iso
DEMO_PROMPT='[zuse@Hera]' demo/make-snapshot.sh /tmp/StarshipOS.iso /var/lib/starshipos-demo /tmp/demo-zuse/zusestick.img

Then install starshipos-demo.service and apache-demo.conf (their headers say how), and paste xwiki-try-it.xwiki into the page TryIt on the .com XWiki. The {{html}} macro there needs a page author with script rights.

A new image means re-running build-iso.sh and make-snapshot.sh: the saved machine belongs to one image and one QEMU version. Sessions already running keep theirs.

Tested (2026-11-06, Ubuntu 24.04, QEMU 8.2.2, ttyd 1.7.4)

• The Zuse minted: "genesis minted", then "identity confirmed" (logs/20261106-192626, -192739).
• The saved machine: POST 538/538, "identity confirmed", [zuse@Hera] ok> after an 87 s boot.
• A session, in a terminal and through ttyd's websocket: ready 0.2 s after it starts; 3 4 + . answers 7 ok, : SQUARE DUP * ; 7 SQUARE . answers 49 ok; keys typed before "Ready" are discarded, not half-delivered.
• QEMU is gone 0.1 s or less after a hang-up or a closed terminal, and on time at the session limit.
• Not tested here: Apache (none in the test container), several sessions at once (#116).