Astromesh OS

Minimal, immutable, API-only Linux appliance for running Astromesh AI agents.

Minimal, immutable, API-only Linux distribution (appliance) whose sole purpose is running Astromesh AI agents (astromeshd). Versioned v0.10.1 (semver, like the rest of the ecosystem), mature through Phase 4 + post-4. See the documentation and the design docs in docs/superpowers/specs/.

The roadmap (docs/superpowers/specs/2026-06-05-astromesh-os-decomposition-design.md §4) is implemented through Fase 4 + post-4, all merged to main:

Runtime pinned to astromesh v0.36.0 (runtime.pin) — the Fase 4 OTel/metrics/egress runtime work, the Moonshot/Kimi OpenAI-compat provider with cache-aware pricing, per-role model routing, the core-side OTLP export wiring (ASTROMESH_OTLP_ENABLED), WebSocket streaming of live run events (v0.34.0), type: client tools announced to the model instead of being silently dropped (v0.35.0), the openai_compat client timeout from the agent's model block finally reaching the HTTP client (v0.35.1), and three fixes aimed squarely at the API-managed runtime mode this image uses (v0.36.0): RAG pipelines no longer lost when the runtime boots with no agents on disk, prompt templates scoped per agent so two agents can't overwrite each other's, and usage.by_model — a per-(provider, model, role) breakdown of what a run actually consumed, alongside a usage.model that no longer comes back empty on native providers.

¹ §12.2a sched_ext is implemented (guarded loader + scx_simple, fail-closed, default off) but its acceptance gate is deferred: Debian's trixie 6.12 kernel ships without CONFIG_SCHED_CLASS_EXT (confirmed empirically; backports 7.0 has it). Closeable by moving the kernel baseline — see the schedext design doc §0.1. §12.2b GPU broker is deferred (no GPU in the VMs; ships with sysext-gpu).

Each phase's acceptance gate builds the image and boots it in QEMU to assert the capability. phase0-ci runs on every push to main; the per-phase phase{3,4}-* gates run on their feature branches and via workflow_dispatch.

mkosi and QEMU are Linux-only. On Windows/macOS, build inside a privileged Debian container:

docker run --rm -it --privileged -v "$PWD":/work -w /work debian:trixie bash
# inside the container:
apt-get update && apt-get install -y mkosi qemu-system-x86 git python3 python3-pip
# build the runtime .deb first (see .github/workflows/phase0-ci.yml), then:
PHASE0_MODE=stub mkosi build

CI (GitHub Actions) is the authoritative gate: see .github/workflows/phase0-ci.yml.

For fast iteration without waiting on CI (and without the TCG flakiness of GitHub-hosted runners), reproduce the boot/update gate locally in WSL2 with KVM.

One-time setup (from the Windows host):

wsl --install -d Debian --no-launch
# enable systemd + drvfs metadata, then apply:
wsl -d Debian -u root -- bash -lc "printf '[boot]\nsystemd=true\n\n[automount]\noptions=metadata\n' > /etc/wsl.conf"
wsl --shutdown
# install the same toolset CI uses:
wsl -d Debian -u root -- bash -lc "apt-get update && apt-get install -y mkosi systemd-ukify systemd-boot systemd-boot-efi mtools dosfstools ca-certificates qemu-system-x86 qemu-utils ovmf curl rsync git python3"
# verify KVM is exposed (needs nested virtualization, default on Win11):
wsl -d Debian -u root -- ls -l /dev/kvm

If /dev/kvm is missing, add nestedVirtualization=true under [wsl2] in %UserProfile%\.wslconfig and wsl --shutdown.

The runtime .deb (rarely changes — depends only on runtime.pin). Fetch the latest CI build once into dist/ (run on the Windows side, where gh is authed):

gh run download -n astromesh-deb -D dist

Run the loop (as root in WSL — mkosi needs loop devices). The source of truth stays on D:\; the harness rsyncs into ~/astromesh-build (native ext4) and builds there (drvfs can't host a mkosi rootfs build):

wsl -d Debian -u root -- bash /mnt/d/monaccode/astromesh-os/tests/local/dev-loop.sh update

Targets: build (image only) · boot (single-boot + IMMUTABILITY/health assert) · update (full A/B v1→v2 gate, default) · inspect (UKI roothash vs on-disk verity PARTUUIDs) · clean. CI remains the authoritative gate; the local loop is for fast iteration before push.

runtime.pin pins the exact monaccode/astromesh ref built into the image — prefer a release tag (e.g. ASTROMESH_REF=v0.28.9) over a floating branch tip. CI checks out that ref and builds the node .deb from source, so the image is reproducible from it. Bump deliberately — CI fails if the ref can't be resolved.