Astromesh OS

v0.10.1   Phase 4 · post-4  

Debian trixie

Source: github.com/monaccode/astromesh-os — a separate repository from the core runtime.

Note

Astromesh OS is built capability-by-capability through a phased roadmap, and a hard rule holds throughout: you do not advance to phase N+1 until phase N boots and passes its checks. As of July 2026 the project is implemented through Phase 4 + post-4 — immutability and A/B updates with automatic rollback (Phase 2), TPM-sealed secrets, AppArmor, tool sandbox, egress governance and Secure Boot (Phase 3), and agent-native fleet join with mesh mTLS, OpenTelemetry export and eBPF causal egress (Phase 4), plus post-4 work on cgroup memory governance, CRIU checkpoint/restore and sched_ext — all merged to main. See the roadmap for the state of each phase.

Astromesh OS (astromesh-os) is a minimal, immutable, API-only Linux appliance — a purpose-built distribution whose sole job is running Astromesh AI agents (astromeshd). It is not a general-purpose operating system, and it is not something you install on top of an existing OS. It ships as a self-contained disk image: an appliance you boot, not a package you manage.

It is built with mkosi on Debian trixie (kernel 6.12+ LTS). The Astromesh agent runtime (astromesh) is baked directly into the image at a pinned ref (currently v0.37.0, declared in runtime.pin), so a given image is reproducible from one exact tag. The core image lands at ~378 MB of real blocks, well under its 500 MB build ceiling — the published .raw looks larger because it is sparse, carrying an empty second A/B slot.

Like every other product in the ecosystem, Astromesh OS is versioned with semver (v0.10.1); the roadmap phase is surfaced alongside it as a maturity signal.

The runtime pin

runtime.pin is the single line that decides which core release the image carries, and it is bumped deliberately — never on a schedule. Two constraints make it a real gate rather than a formality, and neither is caught by the core’s own CI:

• build-deb.sh uses pip, which ignores [tool.uv.sources]. A core release that resolves a sibling repo through a uv path source cannot be built here at all. Releases v0.31.0 and v0.32.0 are deliberately skipped for exactly this reason.
• astromesh.api.main must import with no extras installed. The image venv has no numpy, faiss or aiosqlite. Every release from v0.30.0 through v0.33.0 was unbootable because a module-level import pulled one of them in; this repository’s boot gate is what caught it.

So each bump records, in the pin file itself, what was verified before it: that the diff adds no new import on the boot-sensitive paths, that the slim-install test passes, and — for the riskier bumps — that a real .deb boots in a container and serves an agent.

The pin currently sits at v0.37.0 (declarative integrations framework). The spec.chain work landed in core v0.38.1 and has not been pinned yet.

Astromesh OS vs Astromesh Node

It is critical not to confuse Astromesh OS with Astromesh Node. They solve different problems.

	Astromesh OS	Astromesh Node
What it is	A self-contained, immutable Linux appliance image (a distribution)	A cross-platform installer + daemon that runs on an OS you already have
Delivery	A bootable disk image, distributed as an OCI artifact (oras pull)	.deb / .rpm / macOS / Windows installer artifacts
Where it runs	Bare metal or a cloud VM, as the operating system	On top of Linux, macOS, or Windows
OS lifecycle	You boot a verified, read-only image; updates are A/B image swaps	You self-manage the host OS, drift, and updates
Interactive shell / SSH	None by default (no shell, no package manager at runtime)	Full host shell — it is just a service on your OS
Service	Boots straight to astromeshd	Registers astromeshd with systemd / launchd / Windows Service Manager

In short: Astromesh Node adapts to your machine; Astromesh OS is the machine.

Why an appliance?

Running the agent runtime as a dedicated appliance — rather than as a service inside a general-purpose VM you maintain yourself — buys properties a hand-managed host cannot easily guarantee.

Property	Appliance (Astromesh OS)	Self-managed general-purpose VM
Trust	Verified, read-only root via dm-verity — the running root is cryptographically the image you shipped	Mutable root; you trust that nobody (and nothing) changed it
Attribution & density	Purpose-built for agents; nothing competes for the box	Agents share the host with whatever else you installed
Reproducibility	The whole image is reproducible from one pinned runtime ref	OS state drifts as you patch, install, and tweak over time
Attack surface	Tiny — no interactive shell, no package manager at runtime	Full general-purpose OS, with all the surface that implies

What is in the image

The image is deliberately small (the core image must stay ≤ 500 MB — the build fails if it exceeds the ceiling). It contains only what is needed to boot and serve agents:

• systemd + systemd-boot with a UKI (Unified Kernel Image) for boot.
• A Debian trixie userland, aggressively trimmed (locale, man pages, and docs removed).
• Python 3 plus the Astromesh runtime, baked in at the commit pinned in runtime.pin.
• The astromeshd daemon, started as the system’s default target — the OS boots straight to the agent API.

Because the image is API-only, there is no login prompt to use it. You reach it over its HTTP API (/v1/...), the same surface the rest of the Astromesh ecosystem speaks.

Boot to agent

The system’s default target is the agent. On boot, systemd-boot selects the UKI, the kernel comes up with output forwarded to the serial console, networking is brought up via DHCP, and astromeshd starts and begins answering on its API. There is no interactive step — a healthy boot ends with /v1/health returning 200 and the agent ready to take queries.

What’s next

• Architecture — immutability, A/B updates, the shared /var, OCI distribution, the security and fleet layers, and the 500 MB ceiling.
• Operations & Commands — pulling and booting the image, health checks, A/B updates with rollback, and astromeshctl.
• Building — building the image on a Linux toolchain (Docker or WSL2 + KVM), and bumping the pinned runtime.
• Roadmap — the phased plan and the gate that guards each phase.
• Ecosystem overview — where Astromesh OS fits among the other Astromesh products.