space#

SpaceOS CLI: build and boot SpaceOS VMs.

Top-level CLI and library for SpaceOS. Builds initramfs (cpio) and disk images (GPT via uniboot), launches multi-partition QEMU sessions with virtio-blk storage, IPC relay over virtio-serial, and a ground station socket. Generates Software Bill of Materials (SBOMs) in SPDX 2.3 format, with OCI attestation extraction when available. Components (kernels, init binaries) can be local files or OCI image references.

The default topology runs two partitions: P0 (flight simulator) sends telemetry frames to P1 (SpaceOS) via virtio-serial IPC, with the VMM relaying frames to a ground station socket.

Installation#

opam install space

Usage#

CLI#

# Build initramfs and disk image
space build

# Boot the default two-partition topology
space run

# Boot with auto-shutdown after 60 seconds (for CI)
space run --headless --timeout 60

# Print the software bill of materials
space sbom
space sbom --format spdx-json -o sbom.json

# Show partition logs
space logs
space logs p0 --tail 20
space logs --follow

# Push init binaries to an OCI registry
space push --registry ghcr.io/my-org/demo

Library#

Eio_main.run @@ fun env ->
Eio.Switch.run @@ fun sw ->
let proc_mgr = Eio.Stdenv.process_mgr env in
let fs = Eio.Stdenv.fs env in
let net = Eio.Stdenv.net env in
let clock = Eio.Stdenv.clock env in

(* Load config from YAML *)
let build_config = match Space.Config.load_build "build.yml" with
  | Ok c -> c | Error e -> failwith e
in
let run_config = match Space.Config.load_run "run.yml" with
  | Ok c -> c | Error e -> failwith e
in

(* Build artifacts *)
let artifacts = Space.Build.all ~sw ~fs ~env ~proc_mgr build_config in

(* Boot and wait for exit *)
let exit_code =
  Space.Run.start ~sw ~proc_mgr ~net ~clock ~fs artifacts run_config
in
exit exit_code

API#

• Space.Config -- Build and run configuration types, YAML decoders, service merge and topological sort, and artifact resolution. Build config describes what goes into the image (kernel, partitions, storage). Run config describes how to run it (memory, APIDs, IPC relay, ground station).
• Space.Build -- Build initramfs (cpio with /init, /dev, /proc, /sys) and disk images for all partitions. Skips up-to-date artifacts.
• Space.Run -- Boot QEMU partitions, set up IPC relay, ground station socket, and per-partition log capture. Supports headless mode and timeout-based auto-shutdown.
• Space.Kernel -- Kernel image resolution: local file paths or OCI references.
• Space.Cross -- Init binary resolution: local files, OCI references, or Docker cross-compilation.
• Space.Sbom -- SBOM generation in SPDX 2.3 format. Extracts attestations from OCI images when available, falls back to build config metadata.
• Space.Log_store -- Per-partition log storage with bounded in-memory ring buffer and file persistence. Supports tail, since-timestamp queries, and JSON serialization.
• Space.Dtn_bridge -- DTN bridge routing uplink frames through the CCSDS Space Packet / BPv7 bundle stack.