# 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).