Astromesh OS

v0.4.0   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 June 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) — 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 commit (currently v0.28.7), so a given image is reproducible from one exact ref. The core image lands at ~285 MB, well under its 500 MB build ceiling.

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

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.