Quickstart

Build one Linux service into a signed SpaceOS image and boot it in a local VM. You need no account and no hardware. The builder VM is a disposable Linux virtual machine the Space CLI starts on your Mac to run builds, so you install no Docker daemon and no toolchain. The first build also starts that VM, and space build --profile-metrics prints where a build's time went on your machine.

Prerequisites

• A Mac with Apple silicon. The local VM boots through Apple's Virtualization framework. The target reference lists the machines you can deploy to.
• The Space CLI, installed as the documentation home shows.

Step 1: Scaffold a project

$ space init hello-world
✓ hello-world created
Next: cd hello-world && space run
$ cd hello-world

space init writes five files into hello-world/:

File	Purpose
hello.sh	The program. It prints hello from SpaceOS and exits.
Dockerfile	Copies hello.sh into an Alpine image as /init.
space.yaml	Declares one partition, payload, running one service, hello, built from the Dockerfile. A partition is a group of services that runs in a machine of its own.
README.md	Describes the project and the next commands.
.gitignore	Keeps the build output out of your first commit.

space.yaml declares no relay, so the default one applies. The relay forwards the partition's frames, fixed 256-byte messages, to a local ground service on port 8080, which stands in for the mission's ground station. Each relayed frame carries a 4-byte sequence number and a 16-byte AES-256-CMAC tag. The receiver recomputes the tag and refuses a frame whose sequence number falls outside its 128-frame anti-replay window.

The relay draws a fresh key for each run, so you never type a key, and there is no unauthenticated setting to choose. The relay authenticates frames and does not encrypt them. Ground relay describes the relay in full.

Step 2: Build

From the new directory, build the image:

space build

space build reads space.yaml and builds the hello service from its Dockerfile inside the builder VM. It combines that service with the SpaceOS runtime image, signs the result, and writes it under _build/spaceos.

The first build on a computer also creates a development signing identity: an Ed25519 key pair and an ML-DSA-65 key pair that sign every build. The build prints its fingerprint: sha256: followed by the SHA-256 of the identity's composite public key, the one DER encoding that carries both public keys and forms the body of its public PEM file. Later builds reuse the identity. The last lines of the output name the image, its digest, and the identity that signed it. Every build, including a failed one, also appends a provenance record to this computer's build record, which space build ls lists. A record gives the tag, the image digest, the source, the completion time, the status, and the signing identity's fingerprint; a failed build records its cause and no digest.

Step 3: Run

Boot the image in the local VM:

$ space run
Only this run can talk to the machine it starts.
Running on this computer.
Booting the image you built.

The first line says that the run drew a fresh key for the relay. Frames to and from the VM are authenticated under a key only this run holds, so another process on your Mac cannot inject frames into it. space run then starts the payload partition. The service's output arrives prefixed with its name, as [hello] hello from SpaceOS. The hello service is declared lifecycle: oneshot, so the run ends when the program exits. Press Ctrl+C to stop a run sooner.

Edit hello.sh and run space run again. It rebuilds the image because a file it was built from changed, then boots the new one.

What to read next

• Port a Linux app replaces the starter service with an image you already have.
• SpaceOS for Docker users explains what the build signs and why the image carries its own kernel.
• Troubleshooting covers the refusals a first build can meet.
• The space.yaml reference lists every field of the project file.