OXYGENHUB
# 731413202557 oxygenflow / README.md
4.3 KiB · Markdown · last changed README: a Windows runner, and flow runner update 11 days ago renderedsource blame history raw
1 
# OxygenFlow
2
3 
Hermetic pipelines for Oxygen repositories:
4
5 
- a typed pipeline in `.flow/pipeline.kdl`
6 
- jobs run in isolation tiers, Firecracker microVMs by default
7 
- the host writes the receipts
8 
- results go to OxygenHub as checks and appear on its Flow tab
9
10 
The specification is [docs/spec.md](docs/spec.md). What works today is
11 
[docs/m0.md](docs/m0.md).
12
13 
## A pipeline
14
15 
```kdl
16 
schema-version 1
17
18 
sandbox "alpine" {
19 
    runtime "microvm"
20 
    rootfs "cas://blob/…"      // printed by `flow rootfs import`
21 
    memory-limit "256MiB"
22 
    network "isolated"
23 
}
24
25 
job "build" {
26 
    sandbox "alpine"
27 
    exec "make"
28 
}
29
30 
job "test" {
31 
    sandbox "alpine"
32 
    depends-on "build"
33 
    exec "sh" "-eu" "test.sh"   // argv, run as written: no shell unless you name one
34 
}
35 
```
36
37 
Each job boots its own microVM:
38
39 
- it has no network device
40 
- the rootfs is read-only
41 
- the workspace is the state being built, read-write at `/src`
42 
- the job runs as a user that is not root
43
44 
This repository's own pipeline is [.flow/pipeline.kdl](.flow/pipeline.kdl).
45
46 
## Deploying the runner on Earth
47
48 
`make deploy-runner` builds `flow` and the static `flow-init`, installs them
49 
under `/home/claude/flow` (keeping the previous files as `.prev`), re-pins
50 
`flow-init` in `flow.toml` and restarts the `flow-runner` service.
51
52 
## A Windows runner
53
54 
A Windows machine runs WASM jobs (the other tiers are Linux's). Each
55 
release carries `flow-windows-x86_64.exe` (from the `dist` job):
56
57 
    flow.exe --home C:\flow runner register https://oxygenhub.io --token flowreg_… --name win-1 --label windows
58 
    flow.exe --home C:\flow runner
59
60 
The token comes from the hub (Admin › Runners, or `POST /api/v1/user/runner-token`
61 
for a runner of your own repositories). A pipeline sends it work with a
62 
`runtime "wasm"` sandbox and `runs-on "windows"`. To keep it running, a
63 
Task Scheduler task at start-up with that command (restarting on failure)
64 
does. What a Windows runner does not do yet: report load and kernel, update
65 
itself, or drain when Windows stops it (oxygenflow#83).
66
67 
## Commands
68
69 
    flow check                 # validate .flow/pipeline.kdl, print jobs and the pipeline hash
70 
    flow run [JOB…]            # run the pipeline on this directory, locally, in microVMs
71 
    flow rootfs import T.tgz --sha256 HEX   # make a rootfs image; prints the `rootfs` line to pin
72 
    flow rootfs list
73 
    flow hash FILE             # BLAKE3, for pinning in flow.toml
74 
    flow runner                # claim and run jobs for the hub in flow.toml
75 
    flow runner update --from FILE [--dry-run]   # install a new flow build in place of this one (spec §11.5.3)
76
77 
## A Flow home
78
79 
`$FLOW_HOME` (default `~/.local/share/flow`) holds:
80
81 
- `flow.toml`
82 
- the pinned Firecracker binary, guest kernel and `flow-init`
83 
- rootfs images under `cas/`
84 
- scratch space
85
86 
Every pinned file is checked against its BLAKE3 before use.
87
88 
```toml
89 
[microvm]
90 
firecracker = { path = "bin/firecracker", blake3 = "…" }
91 
kernel = { path = "kernel/vmlinux", blake3 = "…" }
92 
init = { path = "bin/flow-init", blake3 = "…" }
93
94 
[runner]                     # only for `flow runner`
95 
hub = "https://hub.example:7343"
96 
token = "…"                  # listed in the hub's [flow] runner_tokens
97 
ca = "/path/to/hub-ca.pem"   # when the hub's certificate is self-signed
98 
name = "runner-1"
99 
```
100
101 
Setting one up needs Linux x86-64 with KVM and e2fsprogs 1.43 or later:
102
103 
1. Build `flow` with `cargo build --release -p flow`. Build the guest init
104 
   as a static binary:
105 
   `RUSTFLAGS="-C target-feature=+crt-static" cargo build --release -p flow-init --target x86_64-unknown-linux-gnu`.
106 
2. Download Firecracker v1.17.0 from its GitHub release, and check the
107 
   published SHA-256. Download the guest kernel
108 
   `firecracker-ci/v1.15/x86_64/vmlinux-6.1.155` from Firecracker's CI
109 
   bucket.
110 
3. Run `flow rootfs import alpine-minirootfs-3.24.2-x86_64.tar.gz --sha256 …`.
111 
4. Write `flow.toml`, pinning each file by its `flow hash`.
112
113 
On OxygenHub, `hub.toml` lists the runner token and the repositories whose
114 
pushes run pipelines:
115
116 
```toml
117 
[flow]
118 
runner_tokens = ["…"]
119 
repos = ["owner/*"]
120 
```
121
122 
## Tests
123
124 
`cargo test --workspace` runs every test that needs no VM. The microVM
125 
conformance test also runs when `FLOW_TEST_HOME` names a Flow home and
126 
`FLOW_TEST_ROOTFS` is the hash of an Alpine rootfs in it. The test checks
127 
literal argv, network isolation, the read-only rootfs, and that dependents
128 
are skipped after a failure.