aesthetic.computer / core
Monorepo for Aesthetic.Computer aesthetic.computer
Star
Fork 0
Watch
core reports ac-native-init-analysis.md
26 kB
Markdown
at datewizard-instant-hover-label

AC Native OS — Initialization Analysis #

Internal technical analysis of the full boot path from EFI firmware to running JS piece.

Source files analyzed:

  • fedac/native/initramfs/init (81 lines)
  • fedac/native/src/ac-native.c (~2300+ lines, focus on main() and boot functions)
  • fedac/native/src/audio.c (1497 lines)
  • fedac/native/scripts/build-and-flash.sh (956 lines)
  • fedac/native/ac-os (build orchestrator)
  • fedac/native/Makefile

1. EFI Boot #

The system boots via UEFI from a GPT-partitioned drive with a single EFI System Partition (ESP), FAT32-formatted, labeled AC-NATIVE.

Partition layout (build-and-flash.sh:876-879):

label: gpt
type=C12A7328-F81F-11D2-BA4B-00A0C93EC93B, size=512M

Boot chain: The kernel (vmlinuz) is a standard Linux bzImage with the initramfs CPIO archive (LZ4-compressed) embedded directly via CONFIG_INITRAMFS_SOURCE. This means the kernel and initramfs are a single file.

Two boot layouts are supported:

  1. Direct EFI stub — EFI/BOOT/BOOTX64.EFI is the kernel itself (default for USB flash).
  2. Splash chainloader — If fedac/native/bootloader/splash.efi exists, it is placed at BOOTX64.EFI and the kernel goes to EFI/BOOT/KERNEL.EFI. The splash EFI displays a logo while the kernel loads (build-and-flash.sh:900-908).
  3. systemd-boot layout — Detected during install-to-disk: kernel at EFI/Linux/vmlinuz-ac-native with separate loader configs.

The kernel version defaults to 6.14.2 (build-and-flash.sh:36). It is compiled with Intel WiFi firmware (iwlwifi-*) built in via CONFIG_EXTRA_FIRMWARE, i915 GPU drivers, HDA audio, and all necessary subsystems for the target ThinkPad-class hardware.

2. Init Script (/init — PID 1) #

The init script is a minimal POSIX shell script (#!/bin/sh) that runs as PID 1 inside the initramfs. It never uses systemd, udev, or any service manager.

Filesystem Mounts (lines 4-13) #

Mounts are performed in order with error suppression:

Mount Point Type Notes
/proc proc
/sys sysfs
/dev devtmpfs Kernel-populated device nodes
/dev/pts devpts PTY support (ptmxmode=0666)
/dev/shm tmpfs Shared memory
/tmp tmpfs Temporary storage
/run tmpfs Runtime data
/sys/kernel/tracing tracefs Performance tracing
/sys/kernel/debug debugfs Debug interfaces

Credential Restoration (lines 15-34) #

The build system bakes Claude Code credentials into the initramfs at /claude-creds.json and /claude-state.json. Because /tmp is mounted as tmpfs (hiding the initramfs's own /tmp), the init script copies these from the initramfs root:

  • /claude-creds.json -> /tmp/.claude/.credentials.json
  • /claude-state.json -> /tmp/.claude.json
  • Seeds /tmp/.claude/settings.json with default permissions (all tools allowed, installMethod: "native", auto-updates off)
  • Copies /device-claude.md -> /tmp/ac/CLAUDE.md (working dir for Claude Code sessions)

Logging (line 37) #

An ilog() function writes to /tmp/ac-init.log (tmpfs). This log is later copied to USB by ac-native's try_mount_log() for post-mortem debugging.

zram Swap (line 42) #

Creates 1GB compressed RAM swap via zram:

modprobe zram && echo 1G > /sys/block/zram0/disksize && mkswap /dev/zram0 && swapon /dev/zram0

This effectively doubles usable memory for Firefox/GTK browser sessions.

Networking (line 45) #

Brings up loopback interface (ip link set lo up) for localhost connections (needed for Claude OAuth callback server).

Environment (lines 47-51) #

Sets PATH, SSL_CERT_FILE, CURL_CA_BUNDLE, SSL_CERT_DIR for curl/OpenSSL trust in the initramfs environment.

System Setup (lines 53-59) #

  • Creates minimal /etc/group and /etc/passwd (root only) for seatd compatibility.
  • Sets all CPU cores to performance governor.

Kernel Log Dump (lines 62-77) #

Before launching ac-native, the init script attempts to dump kernel boot logs to USB for debugging:

  • Scans /dev/sda1, /dev/sdb1, /dev/sdc1 for block devices
  • Mounts the first available one at /mnt
  • Reads /dev/kmsg (non-blocking, 1-second read window) and writes to /mnt/dmesg.log
  • Copies /tmp/ac-init.log to /mnt/init.log

Exec (line 80) #

exec /ac-native /piece.mjs

The init script replaces itself with the ac-native binary (PID 1 preserved). The default piece is /piece.mjs (baked into initramfs at build time, defaults to prompt.mjs).

3. ac-native Main Boot Sequence #

The main() function begins at line 1773 of ac-native.c. The binary records a monotonic clock timestamp at entry (boot_start) and reports total boot time at the end.

3.1 PID 1 Detection and Filesystem Setup (lines 1777-1802) #

Two code paths based on PID:

PID 1 (direct DRM boot — no cage):

  • Calls mount_minimal_fs() (line 217) which mounts proc, sysfs, devtmpfs, devpts, shm
  • Creates 1GB zram swap (again — safe if already done by init, skips silently)
  • Brings up loopback
  • Waits up to 1 second for /dev/dri/card0 or /dev/fb0 to appear (line 246, 100 iterations x 10ms)
  • Sets all CPUs to performance governor

Non-PID-1 (under cage compositor):

  • Filesystems already mounted by init/parent
  • Opens cage-child.log on USB or falls back to tmpfs

Both paths set PATH and SSL environment variables.

3.2 Signal Handling (lines 1804-1814) #

  • SIGINT, SIGTERM -> graceful shutdown (running = 0)
  • SIGUSR1 -> DRM master release (for browser handoff)
  • SIGUSR2 -> reboot request
  • SIGSEGV, SIGBUS, SIGABRT, SIGFPE -> crash report to /mnt/crash.json with machine ID and timestamp, then re-raise

3.3 Display Initialization (lines 1834-1880) #

Two display backends, selected at runtime:

Wayland path (when WAYLAND_DISPLAY env var is set — running under cage):

  • Calls wayland_display_init() which connects to the cage compositor
  • Creates a minimal ACDisplay struct with width/height from Wayland surface
  • On failure: exits with code 1 (cage will restart or fall through to DRM)

DRM path (direct framebuffer — default for PID 1 boot):

  • Calls drm_init() which opens /dev/dri/card0, finds a connected CRTC, and sets up double-buffered dumb buffers
  • Fatal if no display found — powers off after 5 seconds if PID 1

Framebuffer creation (line 1869):

  • Software framebuffer at 1/3 display resolution: fb_create(display->width / 3, display->height / 3)
  • Default pixel_scale = 3 (3x nearest-neighbor upscale on present)

3.4 Graphics and Font Init (lines 1883-1888) #

  • graph_init() — software rendering context bound to framebuffer
  • font_init() — loads built-in bitmap font
  • Creates separate cursor overlay framebuffer (prevents KidLisp effects from smearing cursor)

3.5 USB/Disk Mount and Log Setup (line 1894) #

try_mount_log() (defined at line 266):

  1. Waits up to 2 seconds for USB block devices (/dev/sda1, /dev/sdb1) to appear (100 iterations x 20ms)
  2. Two-pass mount strategy:
    • Pass 0: Try removable devices first (USB install source)
    • Pass 1: Fall back to internal ESP (for disk-installed boots)
  3. Scans: sda1, sdb1, sdc1, sdd1, nvme0n1p1, nvme1n1p1
  4. Mounts as VFAT at /mnt
  5. Opens /mnt/ac-native.log in append mode
  6. Dumps init log (/tmp/ac-init.log) and cage stderr to /mnt/init.log
  7. Logs all available block devices with removable status

3.6 Config Loading (line 1897) #

load_boot_visual_config() (defined at line 542):

Reads /mnt/config.json (USB/HD) or falls back to /default-config.json (baked in initramfs).

Extracts:

  • handle — sets AC_HANDLE env var, generates time-of-day greeting as boot title (e.g., "good morning @jeffrey")
  • colors — per-character RGB colors for the boot title text, from the handle-colors API
  • wifi — boolean, defaults to true; when false, sets wifi_disabled = 1
  • claudeCreds — JSON object written to /tmp/.claude/.credentials.json
  • claudeState — JSON object written to /tmp/.claude.json
  • voice — "off" disables keystroke TTS

The config supports an AC_IDENTITY_BLOCK_V1 header line (used by ac-usb flash tool).

3.7 Audio Init (line 1900) #

audio_init() (defined at audio.c:616):

This is the most timing-sensitive subsystem. The function:

  1. Allocates state — ACAudio struct with defaults: BPM 120, sample rate 192kHz (default target), reverb buffers, 10-second sample buffer at 48kHz, TTS ring buffer (5 seconds at output rate).

  2. Seeds default sample — Generates a 550ms synthesized one-shot (240Hz with wobble and exponential decay) so sample-mode is playable before first mic recording (audio.c:587-614).

  3. Waits for sound card — Polls for /dev/snd/pcmC{0,1,2}D0p for up to 8 seconds (400 iterations x 20ms) at audio.c:665-670. This is the critical wait for HDA codec probe completion.

  4. Diagnostics — On timeout, distinguishes between:

    • HDA controller present but codec not probed (/dev/snd/controlC0 exists but no PCM device)
    • No hardware at all Dumps /proc/asound/cards and /dev/snd/ contents to /mnt/ac-audio.log.

  5. ALSA device open — Tries 11 device names with 5 retry attempts (2-second sleep between retries, audio.c:722-743):

    hw:0,0  hw:1,0  hw:0,1  hw:1,1  hw:0,2  hw:0,3  hw:1,2  hw:1,3
plughw:0,0  plughw:1,0  default

    Total worst case: 5 attempts x 2s sleep = 10 additional seconds on top of the 8s card wait.

  6. ALSA configuration (audio.c:755-801):

    • Format: S16_LE interleaved, 2 channels
    • Rate: Requests 192kHz (AUDIO_SAMPLE_RATE), accepts whatever the hardware provides via set_rate_near
    • Period size: AUDIO_PERIOD_SIZE (negotiated)
    • Buffer: 6 periods for underrun tolerance
    • Logs actual vs. requested rate (common mismatch on some codecs)

  7. Mixer setup (audio.c:809-875):

    • Opens ALSA mixer for the detected card
    • Unmutes every playback switch found
    • Sets all playback volumes to maximum
    • Enables all capture switches and sets capture volume to 90% of max
    • Attempts HDA codec verb injection for ALC257 (Speaker node 0x14, HP Out node 0x21)

  8. HDMI audio (audio.c:882-920) — Best-effort secondary output:

    • Tries: hdmi:0,0 through hdmi:1,1, plughw:0,3, plughw:0,7, plughw:0,8, plughw:1,3, plughw:1,7
    • Opens non-blocking, 48kHz, 512-frame period
    • Calculates downsample ratio from primary rate

  9. Audio thread (audio.c:924) — Starts the real-time audio thread at SCHED_FIFO priority 50.

Audio is treated as optional — if no ALSA device is found after all retries, audio->pcm is NULL and the struct is returned with a status message. The rest of the system continues without sound.

3.8 TTS Init and Precache (lines 1901, 1928-1929) #

In DRM boot path only:

  • tts_init(audio) (tts.c:125) — Initializes Flite with two voices:

    • cmu_us_slt (female, primary)
    • cmu_us_kal (male, secondary)
    • Both set to 0.9x duration stretch (slightly faster speech)
    • Starts a background TTS thread

  • tts_precache(tts) (tts.c:204) — Pre-renders all lowercase letters (a-z) and digits (0-9) as cached TTS waveforms. This eliminates latency on keystroke speech during typing.

3.9 Boot Beep (line 1927) #

audio_boot_beep(audio) (audio.c:1407-1413):

  • Two-tone "doo-dah": E5 (660Hz, 120ms) then B5 (990Hz, 150ms) with 80ms gap
  • Stereo-panned slightly left then right

3.10 Boot Animation — Startup Fade (line 1937) #

draw_startup_fade() (defined at line 1288):

300 frames at 60fps = 5-second animation.

  1. Immediate solid frame — White (daytime 7am-6pm LA time) or black (nighttime) to hide kernel console text.
  2. Version check — Compares AC_GIT_HASH-AC_BUILD_TS against /mnt/booted-version. Marks as "FRESH" if different. Appends to /mnt/boot-history.log.
  3. Machine ID — Reads /mnt/.machine-id or generates notepat-XXXXXXXX (random hex from /dev/urandom).
  4. TTS greeting (frame 10) — Speaks time-of-day greeting with handle name and build name: "good morning jeffrey. enjoy Los Angeles! fuzzy-meadow."
  5. Visual elements:
    • Fade from solid color to time-of-day themed background (cream/warm white for day, deep blue/sunset purple for night)
    • Centered title with per-character handle colors (animated pulse)
    • Version panel (top-right): build name, git hash, build timestamp, "FRESH" badge
    • "enjoy Los Angeles!" subtitle (appears after frame 130)
    • Auth badges (bottom-left): pixel-art crab (Claude token present) and octocat (GitHub PAT present)
    • Shrinking time bar at bottom
    • "W: install to disk" hint (only when booting from removable USB)
  6. Input handling — Opens all /dev/input/event* devices non-blocking:
    • First 60 frames (1 second): all key presses are drained/ignored
    • After frame 60: W key triggers install-to-disk flow, any other key skips animation

3.11 Input Init (line 1944) #

input_init() (input.c:315):

  • Scans all /dev/input/event* devices
  • Opens each with O_RDONLY | O_NONBLOCK | O_CLOEXEC
  • Checks event bits: accepts devices with EV_KEY, EV_ABS, EV_REL, or EV_SW
  • Detects tablet mode (EV_SW + SW_TABLET_MODE) with sysfs fallback for ThinkPad ACPI
  • Identifies NuPhy keyboards by vendor ID — marks them for hidraw analog handling instead of evdev
  • Calls hidraw_scan() for analog keyboard support via HID raw protocol

3.12 Install-to-Disk Flow (lines 1967-1981) #

Triggered only when user pressed W during boot animation and confirmed with Y:

auto_install_to_hd() (line 713):

  1. Identifies source (removable USB with kernel at EFI/BOOT/BOOTX64.EFI)
  2. Finds target non-removable block device (NVMe or SATA)
  3. Creates GPT with EFI System Partition via sfdisk
  4. Formats FAT32, copies kernel and config.json
  5. Supports both direct EFI stub and systemd-boot layouts
  6. Displays animated progress during install
  7. On success: prompts reboot (with TTS "rebooting", shutdown sound, 600ms delay)

3.13 WiFi Init (line 1987) #

wifi_init() (wifi.c:653):

  1. Checks for iw binary existence
  2. Logs diagnostic info: network interfaces, firmware files, kernel wireless messages from /dev/kmsg, PCI device enumeration
  3. Waits up to 3 seconds for wireless interface (30 attempts x 100ms)
  4. If found, stores interface name (e.g., wlan0)
  5. wifi_autoconnect() called immediately after — connects to saved/preset network

WiFi is skipped entirely if wifi_disabled is set from config.json.

3.14 Secondary HDMI Display (lines 1997-2000) #

drm_init_secondary() — attempts to find a second connected DRM output for HDMI mirroring/extension.

3.15 JS Runtime Init (line 2004) #

js_init() (js-bindings.c:1637):

  1. Allocates ACRuntime struct with pointers to all subsystems (graph, input, audio, wifi, tts)
  2. Creates WebSocket and UDP client handles
  3. Initializes 3D camera
  4. Creates QuickJS-ng runtime and context
  5. Registers Form and Painting JS classes
  6. Sets up module loader (JS_SetModuleLoaderFunc)
  7. Registers the full native API surface:
    • Graphics chain API: box, line, circle, plot, write, scroll, blur, zoom, contrast, spin, qr, form, ink
    • Top-level graphics: wipe, ink, line, box, circle, qr, plot, write, scroll, blur, zoom, contrast, spin
    • console: log, warn, error
    • performance: now()
  8. Evaluates init JS code (Button, Box classes)
  9. Evaluates browser API stubs for KidLisp compatibility

3.16 Config Application to Runtime (lines 2016-2077) #

After JS init, re-reads /mnt/config.json to populate runtime fields:

  • rt->handle and rt->piece (boot piece override)
  • Voice config ("off" disables keystroke TTS)
  • Claude token -> /claude-token
  • GitHub PAT -> /github-pat
  • Piece aliases: "claude" and "cc" resolve to "terminal" with param "claude"
  • Resolves piece path: /pieces/{name}.mjs

3.17 Piece Load and Boot (lines 2080-2144) #

  1. js_load_piece(rt, piece_path) — Evaluates the .mjs file, extracts boot, paint, act, sim, leave, beat function references
  2. Logs boot time: "Booted in %.1fms" (line 2105)
  3. Logs subsystem status: audio, backlight, input devices, NuPhy analog status, JS function availability
  4. Waits for TTS to finish greeting + 300ms drain + plays ready melody (C5-E5-G5 ascending triad) + 400ms ring-out
  5. audio_prewarm() — plays near-silent 440Hz note (50ms, 0.001 volume) to fill ALSA buffers
  6. Drains queued input events from boot animation
  7. js_call_boot(rt) — Calls the piece's boot() function
  8. perf_init() — Initializes performance logger (30-second CSV chunks to /mnt/perf/)

3.18 DRM-to-Cage Transition (lines 2149-2280) #

After boot completes in DRM mode (compiled with USE_WAYLAND), the system attempts to transition to a Wayland session for browser popup support:

  1. Destroys audio (cage child will re-open ALSA)
  2. Releases DRM master
  3. Forks:
    • Child: Sets env vars (WLR_RENDERER=pixman, WLR_BACKENDS=drm), creates XDG runtime dir, starts seatd -g root, waits up to 3s for /run/seatd.sock, then execlp("cage", "cage", "-s", "--", "/ac-native", "/piece.mjs")
    • Parent: Waits for cage to exit, copies cage stderr to USB log

This means ac-native boots twice: once in DRM for fast startup, then re-execs under cage for full Wayland capabilities.

4. Timing #

Based on log data and code analysis, approximate timing from kernel handoff:

Phase Duration Cumulative Notes
Kernel + initramfs decompress ~1-2s ~1-2s LZ4 decompression, driver probe
Init script (mounts, zram, dmesg dump) ~1-2s ~2-4s dmesg dump takes ~1s (sleep 1)
Display wait 0-1s ~2-5s Up to 1s for /dev/dri/card0
USB mount + log setup 0-2s ~2-7s Up to 2s waiting for USB block devs
Config load <1ms — Simple file read + JSON parse
Audio init 0-18s ~2-25s Highly variable — see Known Issues
TTS init + precache ~0.5-1s — 36 Flite renders (a-z, 0-9)
Boot animation 0-5s — Skippable with any keypress
Input init <100ms — evdev + hidraw scan
WiFi init 0-3s — Interface detection wait
JS init + piece load ~100-200ms — QuickJS context + module eval
Total (typical, audio found quickly) ~9s From kernel to piece running

The ac_log at line 2105 reports "Booted in %.1fms" measuring from main() entry to piece load completion. With well-behaved audio hardware (card appears quickly, first ALSA device opens on attempt 0), total time from kernel to playable piece is approximately 9 seconds.

5. Known Issues #

5.1 ALSA Race Condition (HDA Codec Probe Timing) #

The primary boot-time variability comes from audio initialization.

On fast NVMe boots, the HDA codec may not be fully probed when ac-native first tries to open ALSA. The code handles this with a two-layer retry:

  1. Card wait loop (audio.c:665-670): Polls for /dev/snd/pcmC{0,1,2}D0p for 8 seconds. If timeout occurs and /dev/snd/controlC0 exists, it means the HDA controller initialized but the codec hasn't finished probing — this is logged as "HDA ctrl ok, codec not probed".

  2. ALSA device open retries (audio.c:722-743): Even after a PCM device node appears, snd_pcm_open() can fail if the codec isn't fully ready. The code retries 5 times with 2-second intervals across 11 different device names.

Worst case: 8s card wait + 5 retries x 2s = 18 seconds for audio init alone. On machines where audio hardware is ready quickly, this completes in under 1 second.

The diagnostic output is written to /mnt/ac-audio.log (separate from the main log) with full /proc/asound/cards and /dev/snd/ directory listings.

5.2 Missing Shared Libraries #

The build system uses dynamic linking by default (gcc, not musl-gcc). This means all shared libraries must be correctly bundled into the initramfs. The build script (build-and-flash.sh) handles this with:

  1. Per-binary ldd scanning for direct dependencies
  2. A two-pass transitive dependency resolver (lines 740-769) that scans all ELF files in the initramfs and copies missing .so files

Historical issues:

  • Libraries missed by single-pass ldd (transitive deps of deps)
  • Unversioned .so symlinks needed for dlopen() but not created
  • Mesa GPU stack requiring libexpat, libffi, libxkbcommon that aren't direct deps of ac-native

The build now generates an initramfs manifest (build/initramfs-manifest.txt, copied into the image as /manifest.txt) for build parity verification.

5.3 Firmware Requirements #

Required firmware blobs (bundled in initramfs at /lib/firmware/):

Firmware Purpose
iwlwifi-9260-th-b0-jf-b0-*.ucode Intel WiFi 9260
iwlwifi-cc-a0-*.ucode Intel WiFi AX200
iwlwifi-QuZ-a0-hr-b0-*.ucode Intel WiFi AX201
iwlwifi-QuZ-a0-jf-b0-*.ucode Intel WiFi AX201 (variant)
regulatory.db + .p7s Wireless regulatory database
i915/* Intel GPU display firmware (all generations)
intel/sof/*, intel/sof-ipc4/* Intel SOF audio firmware
intel/sof-tplg/*, intel/sof-ipc4-tplg/* SOF audio topology

The kernel config also embeds a subset of WiFi firmware via CONFIG_EXTRA_FIRMWARE for early availability before the initramfs mounts firmware. The build script decompresses .xz and .zst compressed firmware from the host system.

5.4 Wayland/Cage Transition Complexity #

The DRM-to-cage transition (Section 3.18) is inherently fragile:

  • Audio must be destroyed and re-opened by the cage child
  • DRM master must be released before cage can take it
  • seatd must start successfully within 3 seconds
  • The ac-native binary effectively boots twice (DRM then Wayland)
  • If cage fails, the parent logs the error but the system stays on the DRM frame (no automatic fallback to DRM-only mode with continued operation)

5.5 Clock Accuracy #

Time-of-day greetings and themed backgrounds depend on get_la_hour() which computes LA time. Since the system has no RTC battery on some hardware and NTP hasn't run yet at boot, the kernel time may be epoch (1970). The code accepts this gracefully — it just shows the wrong greeting.

6. Build Pipeline #

Local builds (ac-os build) #

Orchestrated by fedac/native/ac-os:

  1. Binary build (build_binary()):

    • Runs make CC=gcc (or musl-gcc if available with linux/input.h)
    • Passes BUILD_TS env var for timestamp embedding
    • Verifies the binary contains the current git hash via strings check
    • Builds BPF trace tools if Makefile exists

  2. Initramfs build (build_initramfs()):

    • Runs build-and-flash.sh --skip-kernel --skip-binary under sudo
    • KidLisp bundling done as user (npx unavailable under sudo): npx esbuild bundles kidlisp.mjs as IIFE
    • Copies fresh binary into initramfs
    • Claude Code native binary: copies from ~/.local/share/claude/versions/ (latest), bakes OAuth token from ~/.claude/.credentials.json, bakes GitHub PAT from gh auth token
    • Bakes credentials into initramfs root files

  3. Kernel build: Runs build-and-flash.sh for kernel compilation with embedded initramfs

Makefile version stamps (Makefile:10-15) #

GIT_HASH   := $(shell git rev-parse --short HEAD)
BUILD_TS   := $(shell date -u '+%Y-%m-%dT%H:%M')
BUILD_NAME := $(shell scripts/build-name.sh --bump)

These are compiled into the binary via -DAC_GIT_HASH, -DAC_BUILD_TS, -DAC_BUILD_NAME and used for:

  • Boot screen version panel
  • TTS greeting (build name spoken aloud)
  • /mnt/booted-version comparison for "FRESH" detection
  • /mnt/boot-history.log entries

Critical note (Makefile:123 comment): Make's dependency tracking doesn't detect changes to AC_BUILD_NAME or AC_GIT_HASH because they're not source file changes. The Makefile forces a rebuild of the main object file to prevent stale version strings.

Oven builds vs. local builds #

The primary differences:

Aspect Local (ac-os) Oven (CI/Docker)
Compiler gcc (dynamic) or musl-gcc (static) gcc (dynamic)
Claude binary From ~/.local/share/claude/versions/ Downloaded from GCS (claude-code-releases)
Claude credentials From ~/.claude/.credentials.json Baked by ac-usb flash injection
GitHub PAT From gh auth token Baked by flash injection
KidLisp bundle npx esbuild (user space) Not available under sudo
Firmware Host /lib/firmware/ (all generations) Host /lib/firmware/ (Docker image)
i915 blobs All from /lib/firmware/i915/ All from Docker image
SOF audio All from host All from Docker image
Manifest Generated and embedded Generated and embedded
Build name scripts/build-name.sh --bump Same (increments per build)

Both produce the same artifact structure: a single vmlinuz with embedded LZ4 initramfs CPIO. The build parity is verified via the initramfs manifest file.

Flash pipeline #

ac-os flash extends the build with USB write:

  1. Full rebuild (binary + initramfs + kernel)
  2. GPT partition table with 512MB ESP
  3. FAT32 format labeled AC-NATIVE
  4. Kernel copied to EFI/BOOT/BOOTX64.EFI (or splash chainloader + KERNEL.EFI)
  5. config.json with handle + colors from handle-colors API
  6. Credentials injected (Claude token, GitHub PAT, Claude settings)

ac-os upload always rebuilds first (kernel embeds git hash at compile time), then uploads to OTA release endpoint.