fungOSBuild and inspect fungOS
The public fungOS source builds capability-derived Debian root filesystems for amd64 and arm64. The output is a rootfs tarball, not a bootable disk, SD-card image or installer ISO. Kernel, firmware, disk assembly, enrollment and signed first-party applications remain separate steps.
This guide follows the public fungOS source at the reviewed revision above. First-party code and documentation are MIT OR Apache-2.0; packaged Linux, Debian and optional applications retain their own licenses.
Prerequisites
Use a Debian-compatible build host with mmdebstrap, debian-archive-keyring, tar, sha256sum and shellcheck. Cross-building arm64 additionally needs qemu-user-static and binfmt-support. The build needs root or a working rootless mmdebstrap mode, outbound HTTPS and enough free space for one root filesystem.
Use committed base/config/release.env inputs. Changing the locked snapshot changes the artifact; review that change before calling it a release.
Build runbook
From the repository root:
./base/scripts/check.sh
sudo ./base/scripts/build.sh amd64 base
sudo ./base/scripts/inspect.sh base/out/fungos-base-amd64.tar
- Run the inexpensive declaration and shell checks first.
- Select a supported architecture and profile.
- Build on a suitable Linux host.
- Retain the tarball, manifest, resolved package list and SHA-256 file from
base/out/. - Inspect the artifact before disk assembly or provisioning.
The builder refuses unsupported architectures and unknown or duplicate capabilities. OUT_DIR and WORK_DIR allow independent CI scratch directories. Do not share a work directory between concurrent builds.
Verify reproducibility
Build twice from clean work directories with the same committed inputs, then compare both artifact digests and package lists:
sha256sum out-a/fungos-base-amd64.tar out-b/fungos-base-amd64.tar
diff -u out-a/fungos-base-amd64.packages out-b/fungos-base-amd64.packages
Matching inputs should produce matching digests. A mismatch is evidence to investigate snapshot drift, undeclared inputs or archive normalization. This page documents the verification procedure; it does not claim a new build was performed when the page was generated.
Provisioning interfaces
| Interface | Contract |
|---|---|
/usr/lib/fungos/first-contact.d/ | Exactly one executable adapter; receives the first-contact environment file path |
/etc/fungos/first-contact.env | Provisioner-owned KEY=VALUE records; adapter validates them |
/usr/lib/fungos/update-verifiers.d/ | Exactly one executable verifier; receives artifact, manifest and signature paths |
fungos-verify-update | Exit zero authorizes staging; it does not install the artifact |
The generic image does not embed tokens, endpoints, enrollment certificates or a Mycelium executable. First-contact adapters own transport, retries and durable enrollment state. Update verifiers own trusted keys, signature format, expiry and rollback protection.
An absent or ambiguous adapter fails visibly. Never let filesystem ordering select a security policy.
Recovery
Inspect journalctl -u fungos-first-contact, networkd state, adapter ownership and executable permissions. Remove stale adapters rather than weakening the single-adapter rule. Provision a public-key SSH recovery path; root password login is disabled in the generic image.
See installation for assembling a bootable target and signed updates for activation and recovery. Owner references: base/README.md, base/RUNBOOK.md, base/interfaces.md and base/scripts/.