The Experimental ISO build GitHub Actions workflow supports:
- Manual run: build the selected ref and require live KVM boot and passwordless install smoke tests.
Scanned boot evidence is retained for 14 days. ISO upload defaults off;
select
retain_isoexplicitly to expose the ISO/checksum/build metadata to repository readers. It does not create a release on a branch. - Version tag: a tag such as
v0.1.0-alpha.1builds an ISO and creates a draft prerelease after a successful build. A maintainer must review and publish it. Existing releases/assets are not overwritten automatically.
The privileged build runs inside a disposable Arch container on a hosted Linux runner, never on the Windows development host or an unattended personal runner. It reclaims unused Android/.NET/Haskell SDK directories only after verifying the hosted-runner environment and exact target paths, then requires 20 GB free. No provider credentials or VM disks are passed to it. Build has read-only repo permissions; only the separate draft-publication job can write release assets.
The helper uses the repository's Arch snapshot and checks the ArchISO version.
It runs full source preflight, builds the release-compressed ISO, validates its
boot-chain structure, and records the source SHA, package list, container digest
and SHA256 checksums. The bootstrap container tag is resolved at build time and
its reviewed manifest digest is pinned in both workflows and the contributor
container helper. BUILD-CONTAINER.txt records the pin and observed repository
digest, and the build fails when they differ. The build container runs
privileged for ArchISO and KVM tests; pinning its bytes does not reduce that
authority or claim bit-for-bit reproducibility.
Roll the container digest only as a reviewed build-input change: resolve the
new Docker Hub archlinux:base-devel manifest, update the dated pin together in
ci.yml, release.yml and tools/dev/preflight-in-container.sh, then review
ARCH_SNAPSHOT and ARCHISO_VERSION in image/config/versions.env. Run the
source gates and an exact-source release build before accepting the new input.
Each build inventories the actual installed OpenClaw npm tree. The image and
installed target retain manifest.json, collected license texts, the npm
CycloneDX SBOM and the audit snapshot under
/usr/share/licenses/openclaw-npm/. Release artifacts also expose
OPENCLAW-LICENSES.json, SBOM.cdx.json, AUDIT.json and its status; all are
covered by SHA256SUMS. Audit findings are non-blocking evidence, not a claim
that the dependency tree is vulnerability-free or locked.
The release build attests the ISO, SHA256SUMS and SBOM.cdx.json through
GitHub's artifact-attestation service and retains the generated bundle as
ATTESTATION.json. After downloading a release bundle, verify locally:
sha256sum -c SHA256SUMS
gh attestation verify clawos-*.iso --repo Solvely-Colin/ClawOSUse a current GitHub CLI compatible with the current Sigstore trust root. During
the 2026-09-15 proof, the host's old gh 2.55.0 verifier rejected the newer
ED25519 trust-root key type; a checksum-verified portable gh 2.100.0 verified
the same downloaded subject successfully. That client error did not indicate a
missing or invalid repository attestation.
Before building, the hosted runner must expose readable/writable /dev/kvm
and successfully create a KVM VM. Missing acceleration fails the workflow;
there is no silent skip. This follows GitHub's
hosted KVM setup,
with a live probe because runner capabilities can change.
The same Arch container then boots the exact newly built ISO using
image/tests/boot-smoke-qemu. Executed serial markers check ClawOS identity,
systemd health, DHCP, overlay root and effective SSH policy. The host then
requests acknowledged ACPI powerdown; the guest must shut down and QEMU must
exit successfully. Cleanup also requests ACPI, never QEMU
termination. If a failed guest refuses shutdown, the gate stays failed; the
disposable container/runner may subsequently be reclaimed by CI infrastructure.
BUILD-METADATA.txt records Live boot smoke: RUN (KVM, run <id>) only after
success; failed or unexecuted smoke never gets that claim. Serial, transcript
and QEMU logs are scanned before publication, including failure evidence. The
separate clawos-boot-evidence-* artifact contains no ISO, writable firmware
variables or sockets. Evidence containing secret-shaped text is not uploaded.
Next, image/tests/install-smoke-qemu ISO creates a new 32 GiB QCOW2 and
installs using --vm-test --passwordless. It checks the dedicated virtio disk
serial, obtains the installer's disk ID and supplies the exact erase confirmation.
Existing runtime directories or disks are never reused. This test needs KVM,
8 GiB guest memory and matching OVMF code/variable templates; the workflow gives
it a separate 60-minute limit. Both guest shutdowns use acknowledged ACPI.
After installation it boots the same disk and firmware variables with the ISO
detached, checks Btrfs root, zero failed units, desktop/broker/SSH/network
services, effective SSH policy, the pinned OpenClaw version, executable updater
and installed/enabled delivery units, and captures
one fresh-guest screendump. The evidence artifact's install/ directory retains
only explicitly listed, scanned logs and the screendump, never the disk or NVRAM.
Text-pattern scanning of image bytes is not OCR or a general screenshot secret
detector; this isolated guest receives no credentials or enrollment data.
--vm-test changes the installed console by enabling serial root autologin,
restricted by the installer to KVM, Q35 and /dev/vda. It proves the passwordless
install/boot chain, not the shipped serial-console posture. Successful execution
alone changes Passwordless install smoke: NOT RUN to RUN (KVM, run <id>);
failure records FAILED. Encrypted install and full onboarding remain separate.
Before the install smoke, image/tests/install-refusal-smoke-qemu ISO boots
that same ISO with three new disposable QCOW2 disks: a blank control, a disk
with GPT plus an ext4 partition, and a whole-disk ext4 filesystem mounted in
the live guest. The live ISO itself is the fourth unsafe target. The eligible
target list must contain only the blank control. For every unsafe target the
harness derives the current kernel-backed disk identity, runs a dry-run
refusal and then a real refusal, and requires both to stop before package
preparation or the disk-write marker. Exact sfdisk -d and descendant blkid
snapshots must remain byte-identical after each attempt. The scanned evidence
retains the serial proof and snapshots, but never QCOW2 disks, writable
firmware, or sockets. QEMU cleanup is acknowledged ACPI only.
The ISO build packs OpenClaw with lifecycle scripts disabled, verifies the
top-level tarball against OPENCLAW_INTEGRITY and its embedded build commit
against OPENCLAW_COMMIT, then installs from that verified local archive.
Image validation checks the shipped build metadata too. The pin was verified
against the published package bytes, not merely copied from registry metadata.
This is not a publisher signature or a locked transitive dependency tree.
Runtime openclaw.update now checkpoints first, packs the exact promoted
version without lifecycle scripts, verifies that archive against the root-owned
SHA-512 and embedded-build-commit pins, installs only the verified local file,
and checks installed metadata before Gateway migration. A bad-pin rejection and
same-version reinstallation passed through the real D-Bus broker on 2026-09-12;
that is not cross-version migration, a transitive lock or a publisher signature.
The 2026-09-10 public launch is source-only. Its four historical ISO artifacts were removed after private backup verification; CodeQL SARIF artifacts are not ISOs. New manual or tag builds can expose binaries to repository readers, so review artifact distribution before dispatching them. The public entry point is building locally, not downloading an old CI run.
The live boot gate and separate passwordless install gate do not run a model request, test physical hardware, or prove full-system rollback. They must not be described as a verified stable release. See hardware restrictions and the public-release checklist.
Before publishing a draft, independently run the disposable QEMU boot/install gates from image/README.md and attach redacted evidence at the same source SHA. Every ISO proof, automated or manual, gets a row in EVIDENCE.md. The experimental installer accepts eligible blank x86_64 UEFI disks, but source validation is not physical-hardware proof. Do not describe it as universal Arch hardware support; record the exact machine and disk types actually tested.
Builds can fail if the pinned archive/tool versions are unavailable, hosted-runner
disk space is insufficient, or ArchISO needs kernel capabilities the hosted
container does not expose. Diagnose those failures rather than skipping gates.
The first green run on main was 34270708295 on 2026-09-08 (source commit
00f81c5, ISO SHA-256 beginning 9442e105); a branch run had succeeded earlier
that day. At that time the workflow validated but did not boot; that artifact was booted
live by hand (EVIDENCE.md). Later run 34432248984 at de19c1b completed a
manual encrypted GTK install and default onboarding under WHPX on 2026-09-10;
provider inference and full update/recovery were not part of that proof. A
private f2da7a6 candidate later passed GTK passwordless installation and a
separate encrypted CLI installation under WHPX/e1000e, including disk-only boot,
unlock and native provider-wizard launch; it was not tagged or published. See
the evidence ledger for its virtio-net failure and exact limitations.
Do not create a release tag just to make the
workflow look complete.
Fill this from the candidate's evidence, never from an older green run:
ClawOS VERSION — experimental, VM-tested only
Source commit: FULL_SHA
ISO: FILENAME
SHA-256: FULL_HASH
Build/install evidence: RUN_URL and EVIDENCE.md row
Verified install modes and environment: EXACT_MODES / HOST / DISK
Agent inference, live update, delivery and rollback: PASS/FAIL/NOT RUN, evidence
Known failures: candidate-specific failures and links; list manual repairs
Not verified: encrypted/GTK/policy/hardware paths or other omitted acceptance
Recovery: Ctrl+Alt+F3 opens the independent local recovery console.
Log in using this installation's account policy. For a known runtime job,
inspect `sudo /usr/lib/clawos/clawos-deploy status JOB_ID` before acting.
Only an explicitly chosen job with a completed backup may be rolled back with
`sudo /usr/lib/clawos/clawos-deploy rollback JOB_ID`.
This restores managed runtime files, not packages, boot files, credentials or
user data. For boot failure or recovery-required, inspect the retained recovery
checkpoint and instructions; do not replay apply or claim full-system rollback.
Distribution: maintainer-reviewed draft; no supported-hardware or stability claim.