MiOS (pronounced MyOS, “My Operating System”) is an Apache-2.0 research project. Its deliverable is a rebuildable Linux operating system blueprint: a Fedora bootc/OCI image, a local agent runtime, and the source and checks needed to regenerate that image. The architectural thesis defines four linked pillars: an immutable image, one local AI front door, a repository that mirrors the target root filesystem, and configuration projected from one source of truth.
This is the system repository. Its usr/, etc/, var/, and other FHS paths describe the filesystem baked into the image. mios-bootstrap owns the interactive installer and operator-editable layer. MiOS-DEV is the build environment; Windows provisioning hands the build to MiOS-DEV.
MiOS is an active proof of concept. WSL2 and development VM runs are the observed environments described by the thesis. Bare-metal, blade fleet, and edge mesh shapes are design targets under development, not claims of a completed deployment.
mios-bootstrap installer + operator selections
-> Total Root Merge with this FHS overlay
-> MiOS-DEV build pipeline
-> bootc/OCI image
-> WSL2, VM, disk, or installer artifact
-> bootc upgrade / rollback on a bootc host
The image includes a desktop, virtualization and GPU support, and a local AI stack. The build uses Containerfile and numbered automation stages. The runtime image owns its static files in /usr; /etc holds host overrides, and /var persists across bootc upgrades. A bootc image is the unit of update and rollback.
The planned MiOS-Metal architecture separates a bare-metal Blade from the MiOS guest. Each Blade owns its boot chain, TPM, NICs, radios, mesh access point, and hardware routing; the MiOS image runs as a NIC-less guest. Fleet roles distinguish services on every Blade, singleton services across Blades, and guest-plane services. See the MiOS-Metal architecture for design details and limits. Whole-device VFIO passthrough is the driver-free host GPU path; mediated GPU sharing requires a host driver and explicit opt-in.
usr/share/mios/mios.toml is the singular vendor SSOT for packages, repositories, images, ports, services, identity, build resources, and the shared theme. Operator choices are made through the local HTML configurator and layered above vendor values. Higher nonempty user values win over host and vendor defaults. Generated files must be projections of the resolved TOML rather than independent settings.
The Windows bootstrap reads [bootstrap.dev_vm.host_reserve] for MiOS-DEV resources. Its current default reserves half of physical RAM for Windows, with an 8 GB minimum reserve; the generated WSL setting is recalculated during bootstrap. Terminal colors, fonts, geometry, and application launch behavior likewise derive from the theme and terminal sections of the same TOML.
The root .mios guide explains workflow dotfolders. They stage sources and generated work; they are not alternate runtime FHS locations.
Every OpenAI-compatible client resolves through MIOS_AI_ENDPOINT, MIOS_AI_MODEL, and MIOS_AI_KEY. The supported public shapes include /v1/chat/completions, /v1/responses, /v1/embeddings, and /v1/models, with function calls and MCP tools. The agent contract and API reference describe the local interface.
mios-llm-lightis the primary local inference and embeddings lane, with model selection inllama-swap.yaml.- Heavy GPU inference lanes are gated by the resolved configuration.
- Agent routing and tool work run through agent-pipe and the local gateway; PostgreSQL with pgvector holds durable agent memory.
- MCP exposes tools, while A2A connects agents. Service ports and enablement come from
mios.toml.
No hosted model account is required for the local runtime. Actual acceleration and enabled services depend on the host hardware and operator selections.
The documented bootstrap entry is:
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/mios-dev/mios-bootstrap/main/Get-MiOS.ps1 | iex"
The installer performs Windows provisioning, fetches the current repositories and full system TOML, and hands the build to MiOS-DEV. It is an interactive system installer that can repartition the selected data disk. Read the bootstrap installation guide for the current phase model, acknowledgement gate, TOML edit and import flow, monitor, and deployment artifacts.
The bootstrap repository's field/ component owns live and USB media staging through MiOS-Field. Its shared staging implementation validates real OCI manifests, blobs, and filesystem layers before marking large media ready. The retired cat/ launcher paths are no longer an installation entry.
From a checkout on a suitable Linux builder:
git clone https://github.com/mios-dev/MiOS.git
cd MiOS
just preflight
just buildJustfile also defines iso, raw, qcow2, vhdx, and wsl2 artifact targets. MiOS-DEV is the canonical environment for build operations in the Windows bootstrap path. just --list shows the local targets; self-build describes their dependencies and outputs.
The package SSOT declares the shared compiler and linker tools in [packages.build-toolchain], the image, repository and verification tools in [packages.self-build], and service dependencies in their runtime groups. requires_sections composes these groups through the existing package resolver; the development image consumes the same dependency closure. Shared agent Python dependencies remain in the requirements file consumed by its isolated environment.
The default [packages.self-build].retain_toolchain = true preserves the tools in the final image. Disabling retention deliberately produces a deployment that needs a separate builder. Package declarations and focused tests establish the requested dependency coverage; a successful full image build and runtime checks are still required to verify a deployed generation.
For an existing bootc-compatible installation, deployment guidance covers image selection, bootc switch, upgrades, and rollback. Do not treat a design target as a verified artifact: check the build log and postchecks for the selected image.
The 16-law registry in mios.toml and its build gates govern contributions. The first six laws define the core image and runtime boundaries:
- Static system configuration belongs under
/usr;/etcis for overrides. - Persistent
/varpaths are declared through tmpfiles, not created during the image build. - Quadlet images are bound into the bootc image and units run without unnecessary privilege.
- The final image must pass
bootc container lint. - AI clients use the one local OpenAI-compatible endpoint.
- Operator-tunable values originate in
mios.toml; generated projections must stay in sync.
This repo owns the system overlay, Containerfile, automation, systemd and Quadlet units. The installer repo owns its interactive entry scripts and user-editable layer. Avoid tracking the same runtime file independently in both repositories.
| Start here | Purpose |
|---|---|
| Thesis | Four pillars and observed versus designed scope |
| Architecture | System layout and component boundaries |
| Installation guide | Day-0 and first-boot overview |
| Engineering guide | Build pipeline conventions |
| Deploy guide | Image lifecycle |
| AI contract | Local agent and endpoint rules |
| Contributing | Source and review conventions |
| Agreements | Project acknowledgement and component attribution |
The version is recorded in VERSION. MiOS and its deployment shapes remain under active development. Component licenses and upstream credits are recorded in the license catalog and credits.
Every MiOS image is the same MiOS. A GitHub Codespace, a local devcontainer, a Claude Code cloud session, the MiOS-DEV podman machine and the bootable OCI image all build from this repository's SSOT. The dev image starts FROM the same podman machine OS mirror, ghcr.io/mios-dev/machine-os.
Open this repository in a Codespace, or reopen it in a devcontainer. The container opens /workspaces, and on first create it clones every MiOS repository listed in mios.toml [workspace].repos beside this one: MiOS, mios-bootstrap, -dev-loop and mios-micro. A local checkout opens the same set through mios.code-workspace; both views are projected from [workspace] by tools/sync-dotfiles.py, and the drift gate fails if either differs.
A Claude Code cloud session runs on a fixed Ubuntu VM. MiOS builds its dev image there with rootful podman from main and installs mios-dev, which enters that image with the session's checkouts mounted at the same paths. It also installs the dev-loop plugin. In the environment's settings (environment menu, Edit), set the network to Full and paste:
Setup script:
#!/bin/bash
curl -fsSL https://raw.githubusercontent.com/mios-dev/MiOS/main/.devcontainer/cloud-shell/claude-code-cloud.sh -o /tmp/mios-claude-code-cloud.sh && bash /tmp/mios-claude-code-cloud.sh
exit 0Environment variables:
CLAUDE_CODE_PLUGIN_DIRS=/opt/dev-loop
The script is .devcontainer/cloud-shell/claude-code-cloud.sh. Every FEDORA_* value has a default there, so set one only to override it. The setup script always exits 0. A cold first build can run past the setup budget: the devcontainer lifecycle is then deferred, mios-dev reports it, and bash /opt/dev-loop-fedora/cloud-fedora-setup.sh --lifecycle applies it. Details: cloud-shell README.
A session's first prompt for live debugging:
/dev-loop:goal Develop MiOS live in this cloud session. Run every gate inside the MiOS dev image (`mios-dev <cmd>`, same $PWD): tests/run-suites.sh lint, python3 tools/ci-suites.py --check, python3 tools/sync-bootstrap.py --check. Take the highest-value open task from the MiOS task list, reproduce its failure, fix it in code, prove it with a positive and a negative control, and push to main. Repeat until the task list's acceptance criteria hold.
The image equivalence work is still in progress. One Containerfile with one stage per profile, plus a gate that proves every image carries the same floor, is tracked as T-1164 and T-1170 to T-1181.