Research-Stack/4-Infrastructure/infra/embedded_surface/xen_alpine

Xen Alpine rs-surface

This is a minimal Alpine Linux carrier for the existing rs-surface embedded node API. It is meant for small Xen guests where the useful interface is:

• serial console first: console=hvc0
• OpenRC service: rs-surface
• Python stdlib only at runtime
• HTTP receipts: /health, /status, /metrics, /primitives
• binary WebSocket frame lane: /ws

The guest does not need a full Research Stack checkout. The install script copies only server.py, one profile JSON file, and the OpenRC service.

Nanokernel Framing

The minimal path is a two-stage carrier:

Xen/QEMU hardware model
  -> Alpine Linux with VirtIO and serial drivers
  -> rs-surface OpenRC service
  -> bounded GCL/nanokernel primitive surface
  -> future signed layer0 image handoff

In this stage, Alpine is not the trusted architecture. It is the driver shim and rollback carrier. The current rs-surface process exposes the nanokernel-shaped contract: bounded operations, local state budget, serial-first recovery, health receipts, route decisions, snapshots, and explicit refusal of unimplemented recovery transitions.

The profile records a future layer0-gcl-nanokernel handoff, but keeps destructive_handoff_allowed=false and handoff=manual until a signed layer0 image, rollback boot entry, serial health pulse, and QEMU health probe all exist. That makes the nanokernel approach incremental rather than theatrical: first prove the carrier and receipt lane, then replace the Python carrier with the smaller layer0 runtime.

Files

• xen-alpine-rs-surface.cfg: xl domain template.
• install_rs_surface_openrc.sh: installs the interface inside Alpine.
• rs-surface.openrc: OpenRC service file.
• rs_surface_static.c: small static C surface for uClibc/musl/glibc-static.
• rs_surface_nolibc.c: smaller x86_64 Linux syscall-only surface.
• smoke_xen_alpine_surface.py: receipt-producing HTTP smoke check.
• run_qemu_alpine_surface.sh: disposable QEMU boot smoke using Alpine netboot.
• ../profiles/xen-alpine-surface.json: default local/recovery profile.

Alpine Guest Install

From a checked-out repo inside the Alpine guest:

cd "4-Infrastructure/infra/embedded_surface/xen_alpine"
doas ./install_rs_surface_openrc.sh
doas rc-service rs-surface start
python3 ./smoke_xen_alpine_surface.py --output /tmp/rs-surface-smoke.json

For a tiny copied payload, set SOURCE_ROOT to the directory containing server.py and profiles/xen-alpine-surface.json:

doas SOURCE_ROOT=/tmp/rs-surface ./install_rs_surface_openrc.sh

QEMU Smoke

The QEMU harness downloads Alpine latest-stable virt netboot assets, builds a small apkovl overlay containing rs-surface, boots Alpine under QEMU, and polls the forwarded health endpoint.

make -C 4-Infrastructure/infra/embedded_surface/xen_alpine qemu-smoke

For the stripped embedded path, build and boot the syscall-only static surface. This is the preferred reduction target for now because it has no libc, no dynamic linker, no Python runtime, no heap, and only a small Linux syscall surface:

make -C 4-Infrastructure/infra/embedded_surface/xen_alpine qemu-static-smoke

When a uClibc toolchain is available, the C surface can be built with:

make -C 4-Infrastructure/infra/embedded_surface/xen_alpine static \
  CC=x86_64-buildroot-linux-uclibc-gcc

Current local receipt from the no-libc path:

runtime=static-nolibc
surface_version=0.1-nolibc
text+data+bss=1627 bytes
stripped ELF=2.4K

Receipt and serial log are written under:

4-Infrastructure/infra/embedded_surface/xen_alpine/build/qemu-alpine/

Those files are ignored because they include downloaded kernel/initramfs/modloop assets and transient boot logs.

Xen Host Sketch

1. Create a small Alpine guest disk, install linux-lts, openrc, python3, and ca-certificates.
2. Ensure the guest kernel command line includes console=hvc0.
3. Copy the tiny surface payload into the guest.
4. Start the domain with an edited copy of xen-alpine-rs-surface.cfg.
5. Attach serial console with xl console rs-alpine-surface.
6. Verify from inside the guest:

rc-service rs-surface status
wget -qO- http://127.0.0.1:8080/health

Bind Modes

The default profile binds to localhost. For an exposed appliance, prefer a Tailscale address by editing the copied profile:

"api": {
  "plain_health_port": 8080,
  "websocket_port": 8080,
  "bind": "tailscale",
  "tailscale_ip": "100.x.y.z"
}

Public bind is supported by the server, but should be paired with an outer firewall or reverse proxy.