deploy/cloudflare-iso-builder/README.md

back to source

# numericalos-iso-builder

Cloudflare **Containers (Sandbox SDK) + R2** pipeline that produces NumericalOS
`initramfs` and hybrid ISO artifacts **without WSL** on the agent host.

This is infrastructure for the skill `numericalos-build-iso-cf`. Building an
artifact is **not** a boot verification. Use `numericalos-verify-boot` on a
downloaded ISO or kernel+initrd under local QEMU.

**Recorded once (2026-08-09):** offline-layout initramfs from this builder
reached `numos: boot complete degraded=1` under QEMU 10.2.2 on x86_64. That
does not auto-claim later builds or other arches.

## Prerequisites

- Cloudflare account + `wrangler` login
- **Docker Desktop (or engine) once**, only to publish the container image
- R2 bucket `numericalos-artifacts`

Not required on the machine that *requests* builds: WSL, local `xorriso`, local
Linux.

## Deploy

```sh
cd deploy/cloudflare-iso-builder
npm install
npx wrangler r2 bucket create numericalos-artifacts
npx wrangler secret put BUILD_TOKEN   # generate a long random string
npx wrangler deploy                  # needs Docker running
```

Health check:

```sh
curl -sS https://numericalos-iso-builder.<subdomain>.workers.dev/health
```

## Build

```sh
# From numericalos repo root (after exporting state):
tar -czf /tmp/numericalos-src.tgz \
  boot/bootstrap.sh boot/numinit.sh boot/numctl boot/lib/arch_table.sh \
  dist/numos.state

curl -sS -X POST "https://numericalos-iso-builder.<subdomain>.workers.dev/build" \
  -H "Authorization: Bearer $BUILD_TOKEN" \
  -F "arch=x86_64" \
  -F "want_iso=true" \
  -F "source=@/tmp/numericalos-src.tgz;type=application/gzip"
```

Download:

```sh
npx wrangler r2 object get numericalos-artifacts/builds/<id>/numericalos-x86_64.iso \
  --file ./numericalos-x86_64.iso
```

## Honesty

| Layer | Role |
|---|---|
| Worker | Auth, orchestrate sandbox, put R2 objects |
| Container | Real Linux: busybox fetch, cpio, grub-mkrescue |
| R2 | Artifact store |
| Local QEMU | Only place boot claims may be made |

Workers alone cannot run `mkisofs`. Do not describe this as a pure-edge ISO forge.

## Known limits

- Artifact egress prefers Sandbox `readFileStream` → Worker → R2 (base64 exec
  fallback). Source still arrives as JSON `source_b64`. Local smoke:
  `scripts/cf-build-smoke.ps1` (token from `.build-token` or env).
- `BUILD_TOKEN` is required; `/build` fails closed if the secret is unset.
- One-time `wrangler deploy` needs Docker for the container image registry push.