# OxygenFlow

[![OxygenFlow](https://oxygenhub.io/andymccall/oxygenflow/flow/badge.svg)](https://oxygenhub.io/andymccall/oxygenflow/flow)

Hermetic pipelines for Oxygen repositories:

- a typed pipeline in `.flow/pipeline.kdl`

- jobs run in isolation tiers, Firecracker microVMs by default

- the host writes the receipts

- results go to OxygenHub as checks and appear on its Flow tab

The specification is [docs/spec.md](docs/spec.md). What works today is

[docs/m0.md](docs/m0.md).

## A pipeline

```kdl

schema-version 1

sandbox "alpine" {

    runtime "microvm"

    rootfs "cas://blob/…"      // printed by `flow rootfs import`

    memory-limit "256MiB"

    network "isolated"

}

job "build" {

    sandbox "alpine"

    exec "make"

}

job "test" {

    sandbox "alpine"

    depends-on "build"

    exec "sh" "-eu" "test.sh"   // argv, run as written: no shell unless you name one

}

```

Each job boots its own microVM:

- it has no network device

- the rootfs is read-only

- the workspace is the state being built, read-write at `/src`

- the job runs as a user that is not root

This repository's own pipeline is [.flow/pipeline.kdl](.flow/pipeline.kdl).

The stamp at the top of this page is its result on OxygenHub. It shows the

run of the state you are viewing, not whatever the bookmark holds now, and

it names the state and each job's receipt.

## Deploying the runner on Earth

`make deploy-runner` builds `flow` and the static `flow-init`, installs them

under `/home/claude/flow` (keeping the previous files as `.prev`), re-pins

`flow-init` in `flow.toml` and restarts the `flow-runner` service.

## A Windows runner

A Windows machine runs WASM jobs (the other tiers are Linux's). Each

release carries `flow-windows-x86_64.exe` (from the `dist` job):

    flow.exe --home C:\flow runner register https://oxygenhub.io --token flowreg_… --name win-1 --label windows

    flow.exe --home C:\flow runner

The token comes from the hub (Admin › Runners, or `POST /api/v1/user/runner-token`

for a runner of your own repositories). A pipeline sends it work with a

`runtime "wasm"` sandbox and `runs-on "windows"`. To keep it running, a

Task Scheduler task at start-up with that command (restarting on failure)

does; set it to restart on failure, as a runner that leaves for a new build

exits 75 (`flow runner update`, spec §11.5.3). To stop it without losing

its job, `flow.exe --home C:\flow runner drain` (Windows has no SIGTERM;

ending the task kills it). What a Windows runner does not report yet: load

and kernel (oxygenflow#83).

## Commands

    flow check                 # validate .flow/pipeline.kdl, print jobs and the pipeline hash

    flow run [JOB…]            # run the pipeline on this directory, locally, in microVMs

    flow rootfs import T.tgz --sha256 HEX   # make a rootfs image; prints the `rootfs` line to pin

                  [--env NAME=value …]      #   with the image's own environment (a Dockerfile's ENV)

    flow rootfs list

    flow hash FILE             # BLAKE3, for pinning in flow.toml

    flow runner                # claim and run jobs for the hub in flow.toml

    flow runner update --from FILE [--dry-run]   # install a new flow build in place of this one (spec §11.5.3)

    flow runner drain          # the running runner claims nothing more and stops once its jobs are reported

## A Flow home

`$FLOW_HOME` (default `~/.local/share/flow`) holds:

- `flow.toml`

- the pinned Firecracker binary, guest kernel and `flow-init`

- rootfs images under `cas/`

- scratch space

Every pinned file is checked against its BLAKE3 before use.

```toml

[microvm]

firecracker = { path = "bin/firecracker", blake3 = "…" }

kernel = { path = "kernel/vmlinux", blake3 = "…" }

init = { path = "bin/flow-init", blake3 = "…" }

[runner]                     # only for `flow runner`

hub = "https://hub.example:7343"

token = "…"                  # listed in the hub's [flow] runner_tokens

ca = "/path/to/hub-ca.pem"   # when the hub's certificate is self-signed

name = "runner-1"

max_jobs = 3                 # jobs at once (default 1)

memory_mib = 24576           # what they may use together; a lone job may use it all

cpus = 8

```

Setting one up needs Linux x86-64 with KVM and e2fsprogs 1.43 or later:

1. Build `flow` with `cargo build --release -p flow`. Build the guest init

   as a static binary:

   `RUSTFLAGS="-C target-feature=+crt-static" cargo build --release -p flow-init --target x86_64-unknown-linux-gnu`.

2. Download Firecracker v1.17.0 from its GitHub release, and check the

   published SHA-256. Download the guest kernel

   `firecracker-ci/v1.15/x86_64/vmlinux-6.1.155` from Firecracker's CI

   bucket.

3. Run `flow rootfs import alpine-minirootfs-3.24.2-x86_64.tar.gz --sha256 …`.

4. Write `flow.toml`, pinning each file by its `flow hash`.

On OxygenHub, `hub.toml` lists the runner token and the repositories whose

pushes run pipelines:

```toml

[flow]

runner_tokens = ["…"]

repos = ["owner/*"]

```

## Tests

**Changelog:** a commit that changes code adds a line under `## Unreleased` in CHANGELOG.md (Added, Changed, Fixed or Security, with the issue number); versions change only at release. `scripts/changelog-check.sh [PATH...]` checks it for the paths a commit takes (the working copy's changes without any) and runs in the gate; `NO_CHANGELOG=1` for code changes users won't notice.

`cargo test --workspace` runs every test that needs no VM. The microVM

conformance test also runs when `FLOW_TEST_HOME` names a Flow home and

`FLOW_TEST_ROOTFS` is the hash of an Alpine rootfs in it. The test checks

literal argv, network isolation, the read-only rootfs, and that dependents

are skipped after a failure.

## oxygen as a pinned subrepo

`flow` builds against `deps/oxygen`, a subrepo (`oxy submodule`) pinned to an exact state, so builds are reproducible and OxygenFlow can build this repository without network. `make pins` moves it to oxygen's `main` on Earth (push oxygen first); the next commit records the new pin. Format only this workspace, `cargo fmt -p flow -p flow-core -p flow-init`: `--all` also reaches `deps/`. After a fresh clone, `oxy submodule update --init` fetches it.