app.yaml reference

app.yaml tells Space CLI how to build one application from source. The build produces an OCI artifact and an artifact manifest. A build.yaml composition can then refer to a named output from that manifest.

Examples

MirageOS

schema: space.app
version: "1"
name: mirage-hello
source: .
kind: mirage

mirage_version: "4.9.0"
ocaml_version: "5.4.1"
opam_repo: https://github.com/ocaml/opam-repository.git
opam_repo_rev: "<full-git-commit>"

targets:
  - platform: hvt
    arch: arm64
  - platform: hvt
    arch: amd64

policy:
  network: replay
  reproducible: true

outputs:
  flight:
    platform: hvt
    path: dist/http-fetch.hvt
    kind: unikernel

Unikraft

schema: space.app
version: "1"
name: unikraft-hello
source: .
kind: unikraft
kraftkit_image: kraftkit.sh/base@sha256:<digest>

targets:
  - platform: qemu
    arch: arm64
  - platform: qemu
    arch: amd64

policy:
  network: replay
  reproducible: true

outputs:
  flight:
    platform: qemu
    path: .unikraft/build/app_qemu
    kind: unikernel

OCI image

schema: space.app
version: "1"
name: cloud-mask
source: .
kind: oci
dockerfile: Dockerfile
context: .

targets:
  - platform: linux
    arch: arm64
  - platform: linux
    arch: amd64

policy:
  network: replay
  reproducible: true

outputs:
  service:
    kind: oci

Common fields

Field	Type	Required	Description
`schema`	string	yes	Must be `space.app`.
`version`	string	yes	Schema version. The current version is `"1"`.
`name`	string	yes	Application name written to the artifact manifest.
`source`	path	yes	Source tree. Relative paths start at the manifest directory.
`kind`	`mirage`, `unikraft`, or `oci`	yes	Build lane used to prepare the source.
`targets[]`	list	yes	Platform and CPU variants to build.
`policy`	map	yes	Network and reproducibility settings for the build.
`cache[]`	list	no	Named, content-addressed inputs available to an offline build.
`outputs`	map	yes	Named outputs published in the artifact manifest.

Target fields

Field	Type	Required	Description
`targets[].platform`	string	yes	Runtime platform, such as `hvt`, `qemu`, or `linux`.
`targets[].arch`	string	yes	CPU architecture, such as `arm64` or `amd64`.
`targets[].options`	map	no	Lane-specific build options for this variant.
`targets[].image`	OCI reference	no	Pinned toolchain or base image for this variant.

Each output name is independent of CPU architecture. Space CLI publishes the variants under one OCI index, so build.yaml refers to app-name#output-name.

MirageOS fields

Field	Type	Required	Description
`mirage_version`	string	yes	MirageOS release used to configure the application.
`ocaml_version`	string	yes	OCaml compiler version.
`opam_repo`	URL	yes	Opam repository used to solve dependencies.
`opam_repo_rev`	Git commit	yes	Full commit that pins the opam repository.

Unikraft fields

Field	Type	Required	Description
`kraftkit_image`	OCI reference with digest	yes	Pinned KraftKit build image.

OCI fields

Field	Type	Required	Description
`dockerfile`	path	yes	Dockerfile relative to the manifest directory.
`context`	path	yes	Complete Docker build context.

Build policy

Value	Prepare phase	Build phase	Use
`allow`	network allowed	network allowed	Resolve and build mutable inputs.
`none`	offline	offline	Build from inputs already present.
`replay`	offline	offline	Rebuild from verified cache inputs.

Set policy.reproducible to true to require an offline build and compare the output of two builds by digest.

Each cache entry has a name, a seed mode, and a digest. Space CLI checks the digest before mounting the cache. The build record lists every cache input and base image used to produce the result.

Output fields

Field	Type	Required	Description
`outputs.<name>.kind`	`unikernel` or `oci`	yes	Type of the published output.
`outputs.<name>.platform`	string	required for unikernels	Runtime platform for the output.
`outputs.<name>.path`	path	required for unikernels	Built file to place in the OCI artifact.

Run the build from the application directory:

space build app.yaml

The build writes the OCI index, software bill of materials, provenance, and artifact manifest under _build/oci/<name>/.