# Run the Genesis appliance locally

The ISO is a complete, single-application x86-64 Linux appliance. It boots the
same static BlastEm frontend and two original games as the browser demonstration.
Running it in native QEMU does not require WebAssembly, a browser, a cloud
account, or a remote emulator. The VM has 256 MiB guest RAM.

## Download

Direct ISO: https://tinycore-genesis.pages.dev/downloads/image.iso

Complete native kit: https://tinycore-genesis.pages.dev/downloads/genesis-native.tar.xz

Kit checksum: https://tinycore-genesis.pages.dev/downloads/genesis-native.tar.xz.sha256

Source and licenses: https://tinycore-genesis.pages.dev/downloads/genesis-source.zip

Individual artifacts, sizes and SHA-256: https://tinycore-genesis.pages.dev/downloads/artifacts.json

All sixteen checksummed build files are available individually under
https://tinycore-genesis.pages.dev/downloads/native/ . The kit contains them, this guide, and the
complete source ZIP. Mutable VM data disks are not distributed. The static
application ELF is intended for this guest, not as a host desktop executable.

### Linux / macOS

```sh
curl --fail --location --output image.iso 'https://tinycore-genesis.pages.dev/downloads/image.iso'
printf '%s\n' '37ebaba6819089964873a60beb9b04959728c1c7ce073df5490853b6a270f997  image.iso' | shasum -a 256 -c -
```

Linux also supports `sha256sum image.iso`. Compare the result with the exact
hash above. For the full kit, download the .tar.xz and its .sha256 together,
verify with `shasum -a 256 -c genesis-native.tar.xz.sha256`, then extract:

```sh
tar -xf genesis-native.tar.xz
cd genesis-native
```

Verify every native file using `sha256sum -c SHA256SUMS` on Linux or
`shasum -a 256 -c SHA256SUMS` on macOS. No downloads are needed during guest boot.

### Windows PowerShell

```powershell
Invoke-WebRequest 'https://tinycore-genesis.pages.dev/downloads/image.iso' -OutFile image.iso
$expected = '37ebaba6819089964873a60beb9b04959728c1c7ce073df5490853b6a270f997'
if ((Get-FileHash image.iso -Algorithm SHA256).Hash.ToLowerInvariant() -ne $expected) { throw 'ISO checksum mismatch' }
```

Use `tar -xf genesis-native.tar.xz` or an XZ-capable archive tool for the kit.

## Install QEMU

Use the installers/packages linked by https://www.qemu.org/download/ .
On Debian/Ubuntu, `sudo apt-get install qemu-system qemu-system-gui` provides
system emulation and a graphical display. On macOS, `brew install qemu` is
supported by the upstream download instructions. On Windows, install the
64-bit QEMU distribution linked there, then open its installation directory in
a terminal or add its executable directory to your user PATH.

## Boot the ISO

Run from the directory containing image.iso. This command uses software CPU
emulation, no guest network device, standard VGA, and an AC97 device with sound
disabled. The command works without hardware virtualization or a mounted host
folder. QEMU needs an installed graphical display backend.

```sh
qemu-system-x86_64 -machine pc -accel tcg -m 256 -vga std -nic none -boot order=d -cdrom image.iso -audiodev none,id=sound -device AC97,audiodev=sound -monitor none -serial none -no-reboot
```

In Windows PowerShell use `qemu-system-x86_64.exe` (or
`./qemu-system-x86_64.exe` from its installation directory); keep the remaining
arguments unchanged. Select a legacy BIOS VM if using another hypervisor: this
ISO uses ISOLINUX and is not an EFI image. Do not write it over a host disk.

At the BIOS prompt, type `paddle`, `grid`, or `menu` and press Enter. Waiting
three seconds opens the game menu. In that menu, 1 selects Paddle Rally and 2
selects Grid Runner. Esc returns to the menu while playing. Arrows move,
Enter starts/serves, Z/X/C are A/B/C, A/S/D are X/Y/Z, Backspace is Mode,
P pauses, F1 resets, and F12 shuts down the guest. QEMU may capture the pointer;
its default release shortcut is Ctrl+Alt+G.

For sound, run `qemu-system-x86_64 -audiodev help` and select an available host
backend. Replace `none,id=sound` with e.g. `sdl,id=sound` if SDL is listed, or
`coreaudio,id=sound` on a macOS build that lists CoreAudio. The AC97 device
argument stays unchanged. The silent command is the portable baseline.

On an x86-64 Linux host with KVM access, replace `-accel tcg` with `-accel kvm`
for hardware acceleration. TCG also works on ARM hosts such as Apple Silicon,
with lower CPU emulation speed. Other host accelerators depend on your QEMU
build and host configuration; list them with `-accel help`.

## Direct kernel boot and explicit demo selection

The full kit also provides vmlinuz64 and initrd.gz. This bypasses the BIOS menu:

```sh
qemu-system-x86_64 -machine pc -accel tcg -m 256 -vga std -nic none -kernel vmlinuz64 -initrd initrd.gz -append 'loglevel=4 nokaslr video=640x480@60 tcs.genesis=paddle' -audiodev none,id=sound -device AC97,audiodev=sound -monitor none -serial none -no-reboot
```

Change `tcs.genesis=paddle` to `tcs.genesis=grid` or `tcs.genesis=menu`.
In PowerShell, the quoted append string works as written. Do not add a host
directory share, network interface, or writable disk unless your appliance needs it.

## Construct a different appliance

Extract genesis-source.zip. It includes unikernel.py, the guest PID 1, Lean
graph-specialization sources, the Genesis frontend, original demo assembly,
the exact pinned BlastEm source archive, locks, notices and site sources.
Install the repository's build dependencies and the GNU 68000 assembler, then:

```sh
source ci/init-temp.sh
python3 unikernel.py build --example genesis --genesis-boot paddle --out build/genesis
python3 unikernel.py run build/genesis
```

Use `--genesis-boot grid` or `--genesis-boot menu` for the other defaults. A local
raw cartridge can be added with `--genesis-rom cartridges/game.bin
--genesis-boot cartridge`. The generic builder accepts another static application
and an explicit asset set; inspect `python3 unikernel.py build --help`.

## What this demonstrates

The artifact couples one static application with a custom PID 1 and a small
initramfs. The guest exposes framebuffer, keyboard and AC97 functions; the
provided launch commands omit networking, host shares and writable disks. It
has no interactive shell, package manager, SSH daemon or general desktop.
PID 1 starts the application as UID/GID 1000 with no_new_privileges and dropped
capabilities. This reduces installed userspace and reachable interfaces.

The kernel is a stock Tiny Core Linux kernel, not a formally minimized kernel.
The graph-transformation proof does not prove the native compiler, kernel,
emulator, ROM parser, browser or hypervisor secure. The attack-surface argument
assumes the VM/browser sandbox holds; sandbox escapes and implementation bugs
remain outside that claim. The website's Cloudflare services are outside the
appliance and are not required to run it locally.