Platform architecture

This page describes the local build and boot path that the space and space-ground tools implement.

Data flow

The build and run path has four stages:

Stage	Input	Output
Build	A local build configuration or OCI index	An initramfs and GPT disk image
Run	An image and a runtime topology file	QEMU partitions backed by SpaceOS storage
Ground	Frames from the virtual machine monitor	A local web dashboard
Observe	Build data and partition logs	Text, JSON logs, or an SBOM file

The CLI reference lists the commands and their options.

Build the software

space build reads build.yml or build.yaml when you name no source. The build creates a cpio initramfs with /init, /dev, /proc, and /sys. It also writes a GPT disk image with an initialized SpaceOS superblock.

The kernel and init program can be local files or OCI references. --kernel overrides the kernel from the build configuration. --output selects the artifact directory.

Boot the partitions

space run IMAGE boots IMAGE and starts the partitions declared in the --runtime topology file. It builds missing artifacts before booting QEMU.

The default topology has two partitions. P0 is the flight simulator and P1 is SpaceOS. P0 sends frames to P1 through virtio-serial IPC. The virtual machine monitor forwards frames to the ground socket.

space build build.yml
space run _build/spaceos --runtime run.yaml --timeout 30

--timeout stops the run after a fixed number of seconds. --headless removes the interactive display and writes logs to files.

Keep applications separate from SpaceOS

The released default topology places the flight simulator and SpaceOS in separate QEMU partitions. The frame path between them uses virtio-serial IPC.

The SpaceOS disk is attached through virtio-blk. This keeps its storage image separate from the host filesystem used to start the virtual machines.

Connect the ground dashboard

space-ground connects to the virtual machine monitor’s ground socket. It serves a web dashboard on port 8080 by default and reads /tmp/spaceos/ground.sock unless --socket is set.

The dashboard process runs separately from space run. Headless runs do not start it.

Distribute build data

The build writes each partition’s init artifact into the local SpaceOS OCI store. A push sends that composition to a registry, and the registry holds it as an OCI index. The build’s own image reference is also the push destination, so any host that can reach the registry pulls the same bytes.

A push distributes artifacts and nothing else. It boots no partition, and it performs no per-board assembly or activation. The CLI reference names the command and its options.

Observe a run

space logs reads partition log files written by space run. It can select a partition or follow new entries. --json emits one JSON object per line.

space sbom reads the build configuration and OCI cache. It emits text by default and supports spdx-json. The SBOM command does not build or boot the system.

Library operating systems

A library operating system links an application with the operating-system libraries it needs. The released CLI does not build those application images. Its build command creates the SpaceOS VM artifacts described above.