run.yaml reference

run.yaml defines runtime placement for a built composition: memory, APID ownership, service isolation, CPU overrides, bridges, relay topology, and the local ground endpoint. space run IMAGE --runtime run.yaml applies it to local execution. Deploy targets are selected separately with space deploy IMAGE --target TARGET.

The same image can run on a developer laptop and on a satellite by switching run.yaml without rebuilding.

Example

schema: space.run
version: "1"
image: _build/spaceos

partitions:
  bus-relay:
    memory: 128
    apids: [0x001, 0x00F]
    send_to: [payload, ground]
  payload:
    memory: 256
    apids: [0x010, 0x01F]
    send_to: [ground]
    services:
      - name: eo-classifier
        isolation: runc
        cpus: [0, 1]
        bridges: [payload-net]
      - name: sdls-downlink
        isolation: hvt

relay:
  from: bus-relay
  to: [payload, ground]

ground:
  port: 8080
  socket: /tmp/spaceos/ground.sock

The relay block names the partition whose frames cross to ground and the destinations they reach. Both relay and ground may be omitted: an absent relay defaults to the first declared partition relaying to the remaining partitions plus ground, and an absent ground block defaults to port 8080 and socket /tmp/spaceos/ground.sock. Declare them explicitly when the topology is part of the mission design.

APIDs are always explicit, because they are part of the partition’s declared authority at the CCSDS edge. Use the mission APID plan when one exists.

Fields

Field	Type	Required	Description
`schema`	string	yes	Must be `space.run`. Unknown fields anywhere in the document are rejected.
`version`	string	yes	Manifest schema version. Currently `"1"`.
`image`	string (path, tag, or OCI ref)	yes	Composition to run. `space run IMAGE --runtime run.yaml` overrides this value with `IMAGE`.
`partitions.<name>.memory`	int (MB)	no (default: `256`)	Memory allocation in MB for this partition.
`partitions.<name>.apids`	`[lo, hi]` pair	no	CCSDS APID range this partition owns on the frame bus. 11-bit values (0x000-0x7FF) per CCSDS 133.0-B-2. APIDs label streams so receivers can sort them; routing authority is `send_to`.
`partitions.<name>.send_to`	list of names	no (default: `[]`)	Directional flow allow-list. Names the partitions or `ground` destinations this partition may originate frames to. Empty means nothing is allowed out.
`partitions.<name>.services[]`	list	no	Per-service runtime placement overrides.
`relay.from`	string (partition name)	no (default: first declared partition)	Primary telemetry source partition. Cannot be `ground`.
`relay.to`	list (partition names and / or `ground`)	no (default: remaining partitions plus `ground`)	Relay destinations. `ground` is reserved and routes frames to the ground-service interface configured in the `ground` block; it cannot be used as a partition name. The relay is bidirectional: telecommands flow back from any destination to `from`.
`relay.limits.rate`	int	no (default: `1000`)	Frames per second admitted per source; `0` means unlimited.
`relay.limits.burst`	int	no (default: `64`)	Frames that may exceed `rate` in a momentary burst before the limit applies.
`relay.limits.queue_depth`	int	no (default: `256`)	Bounded egress queue depth.
`relay.limits.drop_policy`	`block`, `drop-new`, or `drop-oldest`	no (default: `drop-new`)	What the relay does when an egress queue is full.
`relay.security.*`	map	no	SDLS frame-authentication parameters.
`ground.port`	int	no (default: `8080`)	TCP port for the ground-service dashboard exposed by `space run` (local development only). Ignored by `space deploy`, which uses the ground service of the active context.
`ground.socket`	string (path)	no (default: `/tmp/spaceos/ground.sock`)	Unix socket path for the local ground-service interface. Local development only.

Relay security

Each key under relay.security. These are SDLS protocol fields, and the defaults keep frames unauthenticated until a producer starts protecting them, which suits local development and simulation:

Field	Type	Required	Description
`spi`	int	no (default: `1`)	Security parameter index: which key and configuration set the receiver should use to check a frame.
`scid`	int	no (default: `0`)	Spacecraft identifier carried in the transfer frame.
`vcid`	int	no (default: `0`)	Virtual channel identifier: which quality-of-service lane the frame belongs to.
`acs`	string	no (default: `aes-256-cmac`)	Authentication cipher suite used to compute each frame’s authentication tag. Must name a known suite.
`sn_len`	int	no (default: `4`)	Sequence-number length in bytes.
`arsnw`	int	no (default: `128`)	Anti-replay sequence-number window: how far out of order a frame may arrive and still be accepted.
`enforce`	boolean	no (default: `false`)	Reject frames that fail authentication. While `false`, failures are reported but not dropped.

Service runtime entry

Each item under partitions.<name>.services[]:

Field	Type	Required	Description
`name`	string	yes	Must match a service name declared in `build.yaml` for this partition.
`isolation`	`auto`, `runc`, `spt`, `hvt`, `qemu`, `host`, or `firecracker`	no (default: `auto`)	Concrete execution backend for this service. Overrides the build-side default.
`cpus`	list of int	no	CPU cores assigned to this service. Empty inherits the build default.
`bridges`	list of string	no	IP bridges attached to this service. Empty inherits the build default.

Isolation backends

The user-facing categories are containers and unikernels, but manifests use backend names: runc for containers; hvt (KVM) or spt (seccomp, no KVM requirement) for unikernels; qemu for Unikraft on x86_64; firecracker for Linux micro-VMs; host for development fixtures; auto to let the runtime pick. Backend availability depends on the host and connected target profile.

Notes

Partition names must match those declared in build.yaml.
ground is a reserved name in the relay configuration; it cannot be used as a partition name.
Every service may override isolation, CPUs, and bridges by name. Missing values inherit the build-side defaults.
send_to is the directional information-flow policy, keyed by the authenticated service identity rather than by address. Deploy policy can realize a subset of this graph, but it must not widen it.