run.yaml reference

run.yaml supplies runtime settings to space run. It selects a composition and configures partition memory, service placement, frame routing, and the local ground endpoint.

The schema is strict, and the tables are what it accepts

Every member below is one the space.run decoder takes today, with its real default, and the examples are executed against the binary. An undeclared member is refused by name, so a mistyped field fails the load. A row carrying a WIP badge names a member the decoder accepts and the runtime does not act on yet.

space run --runtime run.yaml boots the image the file names, and space run classifier:test --runtime run.yaml overrides it with the image on the command line. The image field is still required when the command overrides it. --dry-run validates and prints the resolved configuration without starting the workload, which is the session below.

Example

schema: space.run
version: "1"
image: classifier:dev

partitions:
  bus-relay:
    memory: 128
    apids: [0x001, 0x00F]
  payload:
    memory: 256
    apids: [0x010, 0x01F]
    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

$ space run --runtime run.yaml --dry-run
Local target: ...
Boot image: not validated (not in the local store: linuxkit/kernel:6.6.13); build first
image: classifier:dev
partitions:
  bus-relay  128 MB  apids 0x001, 0x00f
  payload   256 MB  apids 0x010, 0x01f
    services:
      eo-classifier    runc  cpus 0, 1
      sdls-downlink    hvt
relay:    bus-relay -> payload, ground  (sdls)
ground:   port 8080  socket /tmp/spaceos/ground.sock

2 partitions, 384 MB total
Dry run complete; no workload started.

Boot image: not validated means the referenced composition is not in the local store. Build or pull it before starting the workload.

Top-level fields

Field	Type	Required	Description
schema	string	yes	Must be space.run.
version	string	yes	Must be "1".
image	string	yes	Local path, tag, or OCI reference. A positional IMAGE argument to space run overrides it.
partitions	map	yes	Runtime settings keyed by the partition names from build.yaml. At least one partition is required.
relay	map	no	Frame route, queue limits, and authentication settings.
ground	map	no	Local ground-service endpoint.
bindings	map	no	WIP What this run supplies for each accelerator the application requires, under bindings.accelerators, keyed by the role the app declared: a content-addressed model or bitstream, and requested_limits. The decoder takes it and checks it against the app’s requirements; realizing the flow through to the device is next-release work.
acquisition	map	no	The imagery this run wants, and when: area as west, south, east and north in degrees, from as an RFC 3339 instant, and hours of window (default 24). A run on the local engine ignores it; a run bought from an operator that owns spacecraft is where it is read. space deploy --area, --from and --hours override it.
output	string	no	Directory the run writes its results into. Naming it empty is refused; omit it instead.

Unknown fields are rejected.

Partition fields

Each key under partitions must match a partition in build.yaml.

Field	Type	Required	Description
partitions.<name>.memory	int	no; default 256	Memory in MB.
partitions.<name>.apids	two-item int list	no; default []	Inclusive CCSDS APID range, from 0x000 to 0x7FF. Example: [0x010, 0x01F].
partitions.<name>.services	list	no; default []	Per-service runtime overrides.

Service fields

Each item under partitions.<name>.services has these fields:

Field	Type	Required	Description
name	string	yes	Service name from the same partition in build.yaml.
isolation	enum	no; default auto	One of auto, runc, spt, hvt, qemu, host, or firecracker.
cpus	list of int	no; default []	CPU IDs. An empty list uses the build default.
bridges	list of string	no; default []	IP bridge names. An empty list uses the build default.

Relay fields

If relay is omitted, from is the first partition and to contains the remaining partitions plus ground.

Field	Type	Required	Description
relay.from	string	no	Source partition. ground is not valid here.
relay.to	list of string	no	Destination partitions and/or ground. A name may appear once. Telecommands use the reverse route.
relay.limits.rate	int	no; default 1000	Frames admitted per second. 0 disables the rate limit.
relay.limits.burst	int	no; default 64	Maximum burst above the configured rate.
relay.limits.queue_depth	int	no; default 256	Frames held in each egress queue.
relay.limits.drop_policy	enum	no; default drop-oldest	One of block, drop-new, or drop-oldest.

Relay security fields

These fields are under relay.security. Key material is provisioned at runtime and is not stored in run.yaml.

Field	Type	Required	Description
spi	int	no; default 1	SDLS Security Parameter Index, from 0 to 65535.
scid	int	no; default 0	Spacecraft ID.
vcid	int	no; default 0	Virtual channel ID.
acs	string	no; default aes-256-cmac	Authentication cipher suite: one of aes-256-cmac, hmac-sha-256, hmac-sha-384 or hmac-sha-512. Any other name is refused.
sn_len	int	no; default 4	Sequence-number length in bytes.
arsnw	int	no; default 128	Anti-replay window size.
authentication	enum	no; default sdls	sdls is the only posture, and the relay authenticates every frame. The plaintext link is gone: it existed to avoid an association key, and that key is now drawn per run and typed by nobody.

Ground fields

The ground block only configures local execution. space deploy uses the ground service from the active context.

Field	Type	Required	Description
ground.port	int	no; default 8080	Local ground-service TCP port.
ground.socket	string	no; default /tmp/spaceos/ground.sock	Local ground-service Unix socket. The path is bound as written, so it must be absolute.

Isolation backends

Value	Use
auto	Select a backend compatible with the service runtime.
runc	Run an OCI container.
spt	Run a Solo5 unikernel with seccomp. KVM is not required.
hvt	Run a Solo5 unikernel with KVM.
qemu	Run a unikernel under the QEMU system emulator. The runner executes qemu-system-x86_64, so an Unikraft package built for that target runs here on any host arch.
firecracker	Run a unikernel in a Firecracker micro-VM.
host	Run a development fixture on the host.

Backend availability depends on the host and target profile. Validation rejects an incompatible service runtime and isolation backend.

Validation rules

• Partition and service names must match build.yaml.
• ground is reserved and cannot be used as a partition name.
• relay is the only place to define the frame route.
• partitions.<name>.send_to is not a valid field.
• Per-service frame permissions are defined by the frame_bus interface in build.yaml.