Skip to content

Home

Jump to bottom
Pummelchen edited this page Sep 18, 2026 · 52 revisions

XAIOS

XAIOS is a freestanding Unix-like operating system for dedicated AI and high-performance server workloads, written in C99. It boots from UEFI on AArch64, x86_64 and RISC-V under QEMU, and on two macOS hypervisors — VMware Fusion and Apple Virtualization.framework — and provides a native kernel/userspace ABI, persistent filesystems, IPv4/IPv6, OpenSSH-compatible SSH/SFTP, local and remote shells, administration controls, and a portable inference-engine foundation.

The target it is built towards is an SSH-administered distributed CPU inference server in which the operating system and the model runtime are one system rather than an application on a distribution: the kernel owns hardware, isolation, persistence, networking and service lifecycle, the engine owns model packages, architecture adapters, backends and sessions, and the two are built and gated together. No transformer executes yet, which is why the evidence boundary below is stated rather than implied.

XAIOS is not Linux or FreeBSD and does not run their binaries. FreeBSD is the primary Unix behavior reference for commands and network interoperability.

New here? Getting Started goes from a clone to a login prompt; Current Limitations says what is not claimed.

Quick start

Two ways in, and neither needs the other.

From a released build — no compiler. Download the kit for your machine from the releases page — currently build 8 — unzip it, and run the launcher. The choice of architecture is not reversible by downloading another kit, so pick yours first:

unzip xaios_b8-aarch64-qemu.zip
cd xaios_b8-aarch64-qemu
./run.sh                 # Ctrl-A X quits QEMU

A fresh image has no account and no password: the machine asks how to set itself up on first boot.

From source. On a macOS host with Homebrew:

brew install llvm lld qemu mtools python3 meson ninja xorriso
git clone --recurse-submodules https://github.com/Pummelchen/XAIOS.git
cd XAIOS
export PATH="$(brew --prefix llvm)/bin:$PATH"
make image               # -> build/xaios-aarch64.img
make qemu                # boot it, four vCPUs; Ctrl-A X exits

Either way a good boot ends like this:

IPv4: 10.0.2.15
IPv6: fe80::5054:ff:fe12:3457
SSH server: up and running (tcp/22)

xaios login:

The development image's account is admin / xaios — a public credential for isolated networks only. Release images package no password and reject password authentication. Getting Started has the whole path, including the key-based login to use instead.

Common tasks

I want to… Do this You should see
Log in locally type admin, then xaios at the xaios login: prompt the admin@xaios:/$ prompt
Log in over SSH ssh -p 7788 [email protected] from another terminal an admin@xaios prompt
See what the machine is doing xaiosctl status ssh=running, readiness=…, CPU and page counts
Watch it live xtop a refreshing CPU/process dashboard; q quits
Find my way around the filesystem ls -l /, df, du -h /state xaibootFS on /, xaiFS on /models
Copy a file in or out scp -P 7788 file [email protected]:/state/ a silent return; ls /state shows it
Read or edit a file less /etc/xaios-init.conf, nano /state/notes.txt the pager or the editor
Make or open an archive tar -cf /state/etc.tar /etc, unzip -l a.zip the archive, or its listing
Install or update one application xapt update, xapt list, xapt install APP a signed catalog refresh, no reboot
Update the whole OS xapt os-upgrade a streamed image into the inactive A/B slot
Set the clock date, ntp sync, date -s EPOCH the active source, or the corrected time
Check resource pressure limits normal/warning/critical plus the counts behind it
Collect a report for a bug support a redacted bundle to capture on the host
Shut down cleanly shutdown lifecycle record written, then poweroff
Recover after an unclean boot recovery status, then recovery clear the marker and the unclean count

Full syntax is in Commands; every executable, with its options, is in Applications. The worked examples below the reference tables there show what a session actually looks like.

Use XAIOS

  1. Take a released build from the releases page — currently build 8 — or build one from source. A release is one image per architecture; which download to take, and what is in each, is in Getting Started.
  2. Follow Getting Started to build and boot an image.
  3. Read Boot and Console for startup and local login.
  4. Connect through Networking and SSH.
  5. Use the shell surface in Commands and executable programs in Applications.
  6. Manage the system through Administration.
  7. Install signed applications through xapt Package Updates.

Implemented OS surface

  • AArch64, x86_64 and RISC-V UEFI boot under QEMU.
  • Runtime-sized CPU, cpuset, scheduler, NUMA, and process metadata.
  • EL0 processes and threads with capability-checked syscalls.
  • VirtIO block/network/RNG plus focused emulated NVMe and SMMUv3 gates.
  • xaibootFS for bounded writable state and xaiFS for immutable model data.
  • IPv4, IPv6, TCP, UDP, DNS, reassembly, and SACK-aware transport behavior.
  • First-boot setup on a machine that has no account: run from the medium or install onto a disk, then an account name and password, an optional six digit console PIN, the machine's name, and whether the console logs in automatically.
  • Concurrent SSH sessions, SFTP, outbound SSH/SCP, and authenticated local console sessions — from a credential the machine was set up with, or one a development image packaged.
  • FreeBSD-style command behavior, archive exchange, nano, less, and terminal Pong.
  • Typed xaiosctl administration for status, configuration, identity, audit, storage, and model-package lifecycle operations.
  • Signed xapt catalogs, independent application activation and rollback, and streamed A/B OS updates.

Evidence boundary

The ARM, x86_64 and RISC-V QEMU core-OS correctness gates pass. QEMU proves boot, protocol, ABI, and deterministic behavior; it does not prove physical hardware performance, production security, or real-model inference. No real Qwen, Kimi, or DeepSeek checkpoint has passed end-to-end token and logits parity.

See Current Limitations for explicit non-claims and the single Project Tracker for remaining work.

Documentation

Guide

Reference and internals

Where the source lives

A change goes in exactly one of these, and the choice is usually settled by the directory's purpose rather than by the file's subject.

Directory Why it exists
boot/ The UEFI loader: firmware entry, kernel validation, boot handoff.
kernel/ The kernel. Shared code, with arch/aarch64/, arch/x86_64/ and arch/riscv64/ for what cannot be shared.
userspace/ init, the shell, /bin applications, the hosted C99 library, sshd.
engine/ The portable inference engine: model packages, adapters, backends, sessions.
platform/ One directory per hypervisor, holding its assets and launchers and nothing else.
tests/ Gates that boot XAIOS, checks about the repository itself, fixtures, network harnesses.
contracts/ Versioned machine-readable contracts: what a gate is allowed to call passing.
docs/ Versioned specifications and formats.
scripts/ / tools/ If the build calls it, it is a script; if you call it, it is a tool.
release/ One note per numbered build: what it was booted on, and what was not tested.

Naming a hypervisor is platform/ and tests/ work. Kernel, boot and userspace code may not do it at all — see Platform neutrality and CONTRIBUTING.

Repository reference documents

The Wiki is the human-readable entry point. Detailed versioned specifications and API contracts remain in the source repository:

Source repository | API reference | License

XAIOS is a freestanding Unix-like operating system. QEMU and VMware results are correctness evidence, not physical performance or production certification.

Source | Documentation | Project Tracker | License

XAIOS

Use

Where it runs

QEMU is the default and is covered in Getting Started.

Reference

Project

Clone this wiki locally