# Jetstream

*Design and architecture decision, 2026-10-11 (oxygenflow#38). Builds on
spec §11, runner capabilities and placement (#36). Crate and CLI: `jet`.*

**Flow** says what to run: a pipeline of hermetic jobs, each in a sandbox,
with its outputs, reports and signed receipt. **Jet** carries each job to
where it should run: a fleet of runners on your own machines, on
Kubernetes or in the cloud, that measure themselves, explain every choice
they make, and fetch what they need on their own.

## 1. The decision

**Context.** Today OxygenHub holds the job queue and talks to runners
directly (`/api/v1/flow/claim`, logs, outputs, finish). Runners are
configured by hand: images are copied onto each machine, labels steer
jobs, and a job that cannot run anywhere simply waits. Every
self-hosted CI system has the same shape and the same problems (§2), and
none of it is specific to Oxygen.

**Decision.** The fleet becomes a service of its own, **Jetstream**:

- Jetstream owns the queue, the runners and their measured facts,
  placement and its explanations, pools (hosts, Kubernetes, cloud
  providers) and images. It knows nothing about repositories.
- The **forge** owns pipelines, runs, checks, receipts, artifacts,
  reports and the UI. It hands Jetstream jobs and receives their events.
- **OxygenHub embeds Jetstream** in its own process by default, so nothing
  changes for anyone who never configures it, and can instead point at a
  standalone `jet server` shared by several forges.
- **Sources are pluggable**: an Oxygen repository is mounted lazily
  through flow-casfs; a Git repository is checked out.
- **`flow run`** runs a pipeline on your own machine through an
  in-process Jetstream with one local runner: the same code path as CI.

**Consequences.**

- Jetstream can be reused by others, and could later run jobs for forges
  that are not OxygenHub (§12) without a rewrite.
- One more boundary to keep stable: the forge contract (§4) is versioned.
- Oxygen's advantage becomes visible: the same fleet runs both kinds of
  source, and an Oxygen job starts without a checkout (§5).

```mermaid
flowchart LR
    subgraph Forges
        OH["OxygenHub<br/>pipelines · runs · checks<br/>receipts · reports"]
        OTHER["another forge<br/>(an adapter, later)"]
    end
    subgraph JS["Jetstream (jet)"]
        Q["queue"]
        P["placement<br/>+ why"]
        F["runner facts"]
        I["images"]
        D["demand"]
    end
    subgraph Pools
        H["hosts<br/>earth-1 · plex-1 · narvi-1"]
        K["Kubernetes<br/>controller, pod per job"]
        C["cloud<br/>GCP · AWS · Azure"]
    end
    OH -- "jobs" --> Q
    OTHER -. "jobs" .-> Q
    Q -- "events: logs, outputs,<br/>finish, receipt" --> OH
    Q --> P
    F --> P
    H -- "claim + facts" --> P
    K -- "claim + facts" --> P
    C -- "claim + facts" --> P
    I -- "by hash" --> H
    I -- "by hash" --> K
    I -- "by hash" --> C
    D -- "how many, of what" --> K
    D -- "how many, of what" --> C
```

## 2. What it fixes

Research into self-hosted runners (GitHub Actions, GitLab, Buildkite,
Jenkins, Forgejo; 2023–2026) found the same complaints everywhere. Most of
them are fleet problems, not pipeline problems.

| What goes wrong elsewhere | Jetstream |
|---|---|
| Persistent runners leak state; fork PRs and compromised actions reach other jobs' secrets | A fresh microVM per job (or the syscall tier); nothing survives a job |
| A job waits for hours, then fails, with no reason given | Every waiting job says why, in terms of facts (§7) |
| Disk fills mid-job; an OOM kill shows up as a "lost runner" | Disk and memory checked on every claim against what the job needed last time; OOM reported as OOM |
| Images copied to each machine by hand; slow pulls | Images served by hash, fetched by the runner on demand, chunked so a rebuild moves only what changed (§8) |
| Exact-match labels that sprawl | Facts measured by the runner; labels only steer (§7) |
| Lost runners and spot reclaims leave jobs hanging | Requeue on a lost runner or a reclaim notice (§11) |
| Forced runner upgrades with a cut-off date | Runners update themselves between jobs; the contract is versioned |
| Ephemeral runners start cold, 30–60 s and no caches | Firecracker boots in about a second; images and caches stay warm by hash |
| Multi-arch builds through QEMU, 5–30× slower; no RISC-V runner at all | Native runners per architecture, RISC-V included (narvi) |
| No queue, utilisation or cost figures | Queue time, utilisation and cost by job, pool and region, built in (§11) |

## 3. Responsibilities

| | Jetstream | The forge (OxygenHub) |
|---|---|---|
| Pipeline from the repository | | ✔ |
| Runs, jobs, `needs`, the run page | | ✔ |
| Queue, placement, why a job waits | ✔ | shows it |
| Runners, their facts and tokens | ✔ | shows them |
| Pools: hosts, Kubernetes, cloud | ✔ | |
| Images | ✔ (by hash) | |
| Secrets and variables | carries them to the job | ✔ (stores them) |
| Job identity (OIDC) | carries the token | ✔ (issues it) |
| Logs | streams them | ✔ (keeps them) |
| Outputs, reports, receipts | carries them | ✔ (keeps, checks, shows) |
| Checks on a change | | ✔ |

## 4. The contracts

Two contracts, both HTTPS and JSON, versioned from the start.

**Forge ↔ Jetstream.** The forge submits a job and follows it.

- `submit`: the job's spec (sandbox, image hash per architecture, exec,
  outputs, time limit), its **source** (§5), its secrets and OIDC token,
  the forge's run and job ids, and optional steering (`runs-on`,
  `prefer`).
- `events`: a stream per forge of `placed` (where, and why), `started`,
  `log`, `output` (a file or blob), `finished` (exit code, peak disk and
  memory, duration), `receipt` (signed by the runner), and `waiting`
  (why, when nothing fits).
- `cancel`, and `queue` (what is waiting, for the forge's pages).

**Runner ↔ Jetstream.** What runners already do with the hub today, moved:
`claim` (with its facts, §6), `log`, `output`, `finish`, `decline` (with a
reason). A runner talks only to Jetstream, never to a forge: moving from
embedded to external Jetstream is a URL change for it.

```mermaid
sequenceDiagram
    participant Forge as OxygenHub
    participant Jet as Jetstream
    participant R as earth-1
    Forge->>Jet: submit(job, source, secrets, token)
    Note over Jet: queued: needs x86_64, microvm,<br/>~6 GiB disk (from its last run)
    R->>Jet: claim(facts: idle, 41 GiB free, holds image)
    Jet->>Forge: placed on earth-1 (holds the image, idle, score 100)
    Jet->>R: job
    R->>Jet: log, log, output
    Jet->>Forge: log, log, output
    R->>Jet: finish(exit 0, peak 5.2 GiB disk, 3.1 GiB memory)
    Jet->>Forge: finished + receipt
```

## 5. Sources: mounted, or checked out

A job's source says how a runner gets its files.

- **Oxygen** (`oxy://HUB/OWNER/NAME@STATE`): flow-casfs mounts the state
  read-only and reads objects as the job touches them (spec §5.1). Nothing
  is checked out; a job that reads 50 files of a 100,000-file repository
  fetches 50 files. Jobs whose scope a change does not touch keep their
  previous result (spec §6), and receipts name the exact state.
- **Git** (`git+https://…@COMMIT`): the runner clones or fetches the
  commit into the job's disk before it starts, as every CI system does.

Both run through the same fleet, so the difference is measured, not
claimed: the job page shows how long the source took.

```mermaid
flowchart TB
    subgraph O["Oxygen source"]
        O1["job starts"] --> O2["mount state (ms)"] --> O3["read files as used"]
    end
    subgraph G["Git source"]
        G1["clone / fetch commit"] --> G2["check out every file"] --> G3["job starts"]
    end
```

## 6. Facts: runners know what they are

A runner measures itself, and sends what it measured **with every claim**.
Idle runners claim every few seconds, so Jetstream always holds every idle
runner's facts from moments ago; there is no separate audit channel to go
stale.

| Fact | Measured by | When |
|---|---|---|
| Architecture, CPU model, cores | `uname`, `/proc/cpuinfo` | at start |
| Tiers: microvm (KVM opened, not assumed), syscall (Landlock ABI), wasm | probing | at start, then hourly |
| Memory free, disk free where jobs run | `/proc/meminfo`, `statvfs` | every claim |
| Load, jobs running | `/proc/loadavg`, its own state | every claim |
| Images held | its image store | every claim |
| Speed score | a fixed few-second benchmark (hashing, compression, a small compile), normalised so earth-1 ≈ 100 | at start, then about every 15 minutes while idle |
| Where it runs | the pool: host, cluster and node, or cloud, region, instance type, spot | at start |

The score is checked against reality: Jetstream compares each runner's
claimed speed with how fast its jobs actually ran, and ranks a runner
whose real timings drift (thermal throttling, noisy neighbours) by what
it achieved.

## 7. Placement: requirements, ranking, and why

**A job's requirements are mostly derived**, never typed by the user:

- architecture from its image;
- tier from its sandbox;
- disk and memory **learned from its own past runs** (peak plus
  headroom); a new job goes to the roomiest runner the first time;
- an explicit floor when the pipeline gives one.

**Placement** filters, then ranks:

1. **Filter on hard facts:** architecture, tier, enough free disk and
   memory now, steering that requires a pool or label.
2. **Rank on soft ones:** already holds the image (warm), idle, speed
   score, the shortest estimated finish.
3. **A short hold for the best fit:** when the runner asking is a poor
   fit and a better one claimed seconds ago, the job is held a few seconds
   for it, then goes to whoever is next.
4. **The runner has the last word:** it checks again on accept and
   declines with a reason if its disk filled meanwhile.

**Every decision explains itself**, on the job and through the API:

> ran on **earth-1**: holds the image, idle, score 100, estimated 4 min

> **waiting**: needs ~12 GiB disk (its last run used 10.4); plex-1 has 9;
> earth-1 is busy until about 11:40

**Labels only steer.** `runs-on "plex"` pins, `prefer "fast"` biases. A
user who never writes one never needs to.

## 8. Images

- **Content-addressed.** An image is an ext4 root file system named by
  its BLAKE3 hash (`cas://blob/…`), as today. A sandbox may name one per
  architecture.
- **Served by Jetstream.** A runner that lacks an image fetches it by hash
  and verifies it; nobody copies images between machines. Images are
  chunked, so a rebuilt image moves only its changed chunks.
- **Built by Flow.** An image is a job's output: a project's
  `.flow/image/` becomes a job, its image is kept and served, and the
  sandbox's pin follows it (a proposal: "image changed: af3c… → 91be…").
- **Architecture recorded at build**, so an x86 image never reaches a
  RISC-V runner.

### 8.1 The swarm: runners share images

Runners that are configured for it fetch image chunks from each other as
well as from the hub (oxygenflow #47, oxygenhub #144). Fifty fresh
runners asking for the same 2 GiB image then cost the hub about one copy,
not fifty, and a site behind a thin link pulls each chunk across it once.

- **Trust comes from the hashes.** The manifest comes from the hub, and
  every chunk is checked against its name before it is kept. A peer can
  fail to help; it can never change what a job runs.
- **The hub is the tracker.** A runner reports its swarm address and site
  with every claim. `POST /api/v1/flow/swarm/announce {image, state}`
  (`fetching`, `done` or `stopped`) returns the peers in the same site that
  hold the image or are fetching it, and a **ticket**.
- **Tickets admit peers.** A ticket names the runner, its site and an
  expiry (15 minutes), signed with the hub key that `/.well-known/oxyhub-key`
  publishes. A runner shows its ticket once to each peer
  (`POST /swarm/v1/hello`) and gets a session for the ticket's life; no
  other runner and no account can take chunks from a peer.
- **The peer protocol** is plain HTTP on the runner's swarm address:
  - `POST /swarm/v1/hello` with the ticket: a session token.
  - `GET /swarm/v1/images/{image}/have`: `complete`, or two bit maps over
    the manifest's needed list (`Manifest::needed`), in its order: the
    chunks it has, then the chunks it is fetching now.
  - `GET /swarm/v1/chunks/{chunk}`: the chunk's bytes, from the chunk
    cache or read out of a whole image; `503` when the peer is at its
    connection limit.
- **Rarest first.** The fetcher refreshes every peer's maps twice a
  second and asks each peer, four requests at a time, for the chunk the
  fewest peers hold. The hub is a seed that holds everything: it is asked
  only for chunks no peer has or is fetching, or any chunk once the peers
  have made no progress for two seconds. Runners that start together so
  split the hub's chunks between them rather than each taking them all. When every missing chunk is already asked
  for, idle workers ask a second source for it (the endgame; the hub joins
  it only once the peers stall). A peer that
  fails is dropped and its chunks go back to the pool.
- **Serving while fetching.** A chunk is offered to others as soon as it
  is checked and kept, so runners starting together share the load.
- **Bounded.** A runner serves at most 16 connections and `upload_mib_s`
  (default 50 MiB/s), so serving never starves its own jobs.
- **Configured, never assumed.** Without a `[runner.swarm]` section a
  runner neither listens nor asks peers. Traffic is plain HTTP: chunks are
  public within the fleet and checked by hash, so keep the swarm address
  on a private network.

In flow.toml (or as `[swarm]` in runner.toml, which stands in for the
`[runner]` section):

```toml
[runner.swarm]
listen = "0.0.0.0:7401"        # where peers reach this runner
advertise = "10.0.0.5:7401"    # the address peers are given (default: listen)
site = "home"                  # peers are only ever in the same site
upload_mib_s = 50
```

### 8.2 Runners update themselves

Proposed 2026-10-25 from Andy's experience: keeping a large fleet's
runners up to date by hand is one of the biggest costs of running CI.
Runners fetch new runner builds the way they fetch images, from each other
through the swarm, check them as strictly as a release, and swap
themselves in without losing work, under a policy the organisation sets,
testing on a few runners before the rest.

**A runner build** is a `flow` binary from an OxygenFlow release, one per
target (linux-x86_64, linux-arm64, linux-riscv64; Windows and macOS when
those runners exist), built by Flow from the tagged state with a signed
receipt, as oxy's and OxygenHub's releases are. The hub serves it as a
blob with a chunk manifest, so the swarm (§8.1) carries it unchanged: one
runner of a site fetches each chunk from the hub and the rest from it.

**Off unless chosen, nearest wins.** The policy is set for the site, an
organisation, a test group and a runner; the nearest setting wins:

- `updates`: `off` (the default) or `on`;
- `channel`: `stable`, `canary`, or a pinned version (`0.3.4`);
- `window`: hours in which a runner may update (outside them it waits);
- `dry_run`: fetch and check, say what would happen, do not swap.

A runner's own `flow.toml` has the last word: `[runner.update] allow =
false` refuses every update whatever the hub says, so a site can hold a
machine back while it tests.

**Test groups and waves.** A test group is a named set of runners: chosen
by name, by label or by pool. A rollout is a release and its waves, in
order; each wave is a group and its share of it, **a percentage or chosen
runners**. A percentage is taken by a stable hash of each runner's id, so
"10% of build-farm" is the same machines every rollout, the ones the
organisation watches. A wave starts when the one before has been healthy
for its soak time (say 24 hours) or when an admin promotes it. For
example: canary (two chosen runners), then build-farm at 10%, then
build-farm at 100%, then everyone.

**Healthy** means the updated runners came back on the new version within
ten minutes, claim jobs, and their jobs' infrastructure errors (`lost`,
`error`, declines) over the soak are no worse than the same runners' on
the version before, over enough jobs to tell. A wave that is not healthy
halts the rollout, and its runners roll back. Job failures from the
pipelines themselves do not count.

**On the runner,** in order:

1. The hub's answer to a claim or heartbeat names an update when the
   policy says so: the version, its blob and manifest, its receipt.
2. Fetch the blob through the swarm (hub as seed); every chunk checked
   against the manifest from the hub.
3. Check it as a release: its BLAKE3 matches the release asset the hub
   attests; the receipt is signed by an `owned` build runner (trust
   classes, #79) and names the tagged state; the target is this machine's.
   A peer can only serve bytes; it cannot change what is installed.
4. Stage it (`bin/flow.new`) and run its self-check (`flow.new tiers`,
   `--version`).
5. Drain with notice (`leave_within`, §11.5.2 of the spec): finish what
   fits, hand back the rest with its checkpoints.
6. Swap: `flow` → `flow.prev`, `flow.new` → `flow`, and restart.
7. Prove it: the first claim reports the new version. A runner that will
   not start, or that the hub does not hear from within ten minutes, goes
   back to `flow.prev` (a start counter in the runner's home: three
   failed starts after an update restore the previous build).
8. The runner's page shows its version, channel, group, last update and
   why; the audit log records every update and rollback.

**Phones** take runner updates with the app's releases (Android updates an
app only through its store or an install), so they follow the app.

**Order of work:** (1) the runner side, with a local source (`flow runner
update --from FILE`): check, stage, drain, swap, prove, roll back; (2) the
policy on the hub (opt in and out, channels, windows, dry run) and the
update in the claim answer; (3) test groups, waves and health; (4) the
swarm as transport; (5) Admin › Runners › Updates and `oh runner update`.

## 9. Pools

A **pool** is one place runners come from. All pools report the same
facts and follow the same placement.

```mermaid
flowchart TB
    J["Jetstream"]
    subgraph Hosts["Host pool"]
        E["earth-1<br/>x86_64 · microvm"]
        PL["plex-1<br/>x86_64 · microvm"]
        N["narvi-1<br/>riscv64 · syscall"]
    end
    subgraph K8s["Kubernetes pool"]
        CTL["jet controller"]
        KP1["KVM node pool<br/>Firecracker in pod"]
        KP2["Kata / gVisor<br/>RuntimeClass"]
        KP3["ordinary pods<br/>syscall tier"]
        CTL --> KP1
        CTL --> KP2
        CTL --> KP3
    end
    subgraph Cloud["Cloud pool (europe-west2)"]
        PRV["jet provider"]
        VM1["warm VM, nested KVM<br/>several microVMs"]
        VM2["VM per job<br/>syscall tier"]
        PRV --> VM1
        PRV --> VM2
    end
    J --> Hosts
    J --> CTL
    J --> PRV
```

**Hosts.** Machines you own run `jet runner` (today's `flow runner`).

**Kubernetes.** `jet controller` runs in the cluster, claims for it, and
creates **one pod per job**, the pattern every major CI system uses on
Kubernetes. The tier follows what each node pool offers:

| Node pool offers | Tier |
|---|---|
| `/dev/kvm` through a device plugin (a tainted pool) | microvm: Firecracker inside the pod |
| A Kata or gVisor RuntimeClass (AKS Pod Sandboxing, GKE Sandbox) | syscall, inside the platform's sandbox |
| Nothing special (GKE Autopilot included) | syscall, in an unprivileged pod |

Dedicated KVM hosts beside a cluster stay first class: that is how
microVM CI is run in practice.

**Cloud providers.** `jet provider` creates and removes VMs in a cloud
account, keyless through OIDC (OxygenHub is already an issuer, OxygenHub spec
§13.5):

- **Packing first:** a warm 8–16 vCPU VM with nested KVM runs several
  microVM jobs, saving the 30–60 s boot, the cold disk and per-VM minimum
  charges. Nested KVM: GCP Intel types and N4D, AWS C7i/C8i and newer
  (since 2026), Azure Dsv5.
- **One VM per job** with the syscall tier inside is the fallback where
  nested KVM is not offered.
- **Regions are pinned** per pool and never fall back outside the set:
  for the UK, `europe-west2`, `uksouth`, `eu-west-2`. Every job records
  where it ran.
- **Spot**, with on-demand fallback; a reclaim notice requeues the job.
- **Scale-in** only of idle VMs near the end of their billing increment.
- Build order: GCP, then AWS, then Azure.

The provider interface: `create(n, spec)`, `delete(ids)`, `list()`,
`health(id)`, `capabilities()`, `quota()`.

## 10. Demand and autoscaling

Jetstream answers **demand by pull**, so nothing needs a way into your
network:

- `GET /demand?pool=…` (long-poll): waiting jobs grouped by architecture,
  tier and size, and the age of the oldest. Kubernetes pools scale on it
  through a KEDA scaler; cloud providers through their own loop.
- **One-shot runner tokens** for ephemeral runners and pods: issued for
  one start, never long-lived.

## 11. Reliability and running it

- **Lost runner:** its jobs are requeued after a short grace; a spot
  reclaim notice requeues at once.
- **OOM** is reported as OOM, with the job's peak, and raises its learned
  memory need.
- **Updates:** a runner told of a newer version updates itself between
  jobs. No cut-off date; the contract is versioned and old runners keep
  working until they update.
- **Figures:** queue time (the single most useful CI metric), utilisation
  per runner and pool, and cost per job, pool and region where a provider
  knows its prices.

## 12. Embedded or on its own

```mermaid
flowchart LR
    subgraph A["Embedded (the default)"]
        OH1["OxygenHub process<br/>+ jet inside"]
        R1["runners"] --> OH1
    end
    subgraph B["On its own"]
        OH2["OxygenHub"] --> JS2["jet server"]
        OH3["another OxygenHub"] --> JS2
        R2["runners"] --> JS2
    end
```

- **Embedded:** the same crate in OxygenHub's process, with no
  configuration. This is what OxygenHub does unless told otherwise.
- **On its own:** `[flow] jetstream = "https://jet.example"` in the hub's
  configuration points it at a standalone `jet server`; several hubs may
  share one fleet.
- **Other forges, later:** the forge contract (§4) and Git sources (§5)
  are what an adapter needs, such as one that runs GitLab or GitHub jobs
  on Jetstream runners. That would be a contained piece of work, not a
  rewrite; it is not planned yet.

## 13. Running a pipeline on your own machine

```sh
flow run                     # every job of .flow/pipeline.kdl, on this directory's files
flow run test                # one job, and what it needs
flow run --var X=1 --secret TOKEN=…   # what the hub would supply
```

`flow run` exists today: it runs the pipeline's jobs in the same sandboxes
CI uses, before anything is pushed. With Jetstream it becomes an
in-process Jetstream with one local runner, the same placement and the
same code path as CI, so passing locally means passing in CI. With images
served by Jetstream (§8), the first local run fetches the pinned image by
hash instead of needing it imported by hand.

## 14. Security

- **Isolation per job:** a microVM where KVM exists, the syscall tier
  (Landlock and seccomp) elsewhere, a platform sandbox where a cluster
  offers one. No job ever shares a Docker daemon or a host socket.
- **Secrets** are mounted as files in the job and masked in logs (spec
  §9), never written to a runner's disk outside the job.
- **Cloud VMs** have no cloud identity of their own, the metadata service
  is blocked from inside job microVMs, and job subnets accept nothing
  inbound.
- **Runner tokens** are per runner, and one-shot for ephemeral ones.

## 15. Order of work

1. **The boundary, inside the hub:** queue, placement and runners behind
   the Jetstream contract in a `jet` crate, embedded; no behaviour change,
   CI proves it.
2. **Images served by Jetstream**, fetched by hash; images built by Flow
   jobs.
3. **Facts on every claim, learned requirements, placement with its
   explanation**, on the job page and the queue.
4. **narvi-1**, the first runner brought up this way (riscv64, syscall).
5. **`jet server`**, OxygenHub pointing at it.
6. **The Kubernetes controller**, with a KEDA scaler on `/demand`.
7. **Cloud providers:** GCP, then AWS, then Azure.

## 16. Open questions

- Whether artifacts and report files travel through Jetstream or go
  straight from the runner to the forge (today: straight to the hub).
- Multi-tenancy in a shared `jet server`: pools per organisation, and
  who may submit to which.
- How long the best-fit hold (§7) should be, and whether it should learn.
- Receipts: the runner signs; whether Jetstream countersigns where it
  placed the job.