PLAN.md — elizaOS Live build order

The phased work order to take elizaOS Live from "empty scaffold" to "boots into a working elizaOS live desktop on real USB hardware, with the AI app ready, optional Tor privacy mode, and optional encrypted persistent storage."

This is a multi-week project. Each phase has a clear success criterion; don't jump phases. With the containerized build (see Phase 1) a full ISO is ~1–1.5 h cold, and incremental rebuilds (just binary) are ~10 min — several phases still need iteration.

Detailed, file-level implementation specs for each phase live in docs/specs/. This PLAN is the map; the specs are the turn-by-turn directions.

Current status (2026-05-19)

What exists right now:

• A containerized build pipeline (Dockerfile, build.sh, build-iso.sh, acng.conf, Justfile) that builds the ISO on any host with Docker — no Vagrant, no libvirt, no host-specific setup. See docs/build-infrastructure.md.
• 6 genuine Tails Trixie-compat fixes found while getting the build to run (5 builder-box fixes + 1 package-list fix — gdisk/mtools for the partitioning initramfs hook). All upstream-worthy.
• Complete file-level specs for every implementation phase (2–9) plus a product hardening plan for distribution, updates, production readiness, and the demo debt that still blocks a real release.
• elizaOS OS-branding overlays for boot menus, Plymouth, greeter, light blue/white GNOME defaults, wallpaper, identity strings, and Tails attribution.
• The elizaOS desktop app builds and is staged into the Tails overlay. The ISO install hook copies it to /opt/milady, fixes permissions, and removes the staging copy. /opt/milady is an internal runtime path until the app package itself is renamed.
• A narrow elizaOS capability broker exists at /usr/local/lib/elizaos/capability-runner. For the first rebuild it is intentionally conservative: status/privacy/persistence helpers plus exact sudo only for root-status; package/network mutation is deferred until an approval-gated policy layer exists.
• Privacy-mode, autolaunch, and ~/.eliza Persistent Storage overlays are implemented locally. QEMU has proven the normal greeter/desktop/app path on the latest validated local ISO artifact, and USB flash/readback passed on a prior artifact. The current gate is rebuilding/validating the exact release commit if the branch moves, then repeat USB flash/readback, real USB boot, persistence, and privacy behavior.
• The old root-level usbeliza Linux prototype was removed from this branch; this variant is the active Linux distro path.

See ROADMAP.md for the honest road from here to a real, fully-working demo.

v1.0 scope (locked 2026-05-14)

USB-only distribution with two storage modes and a privacy toggle. No install-to-internal-disk yet — see § Deferred for the rationale.

Storage modes (pick at boot)

1. Amnesia (default) — RAM only, no disk writes, full wipe on shutdown. Required for "borrowed laptop / hotel / zero footprint". Tails' default behavior, kept identical.
2. Persistent USB (opt-in) — LUKS-encrypted partition on the USB stick. Reuses Tails' native Persistent Storage (tps) tool unchanged. Selected dirs bind-mount from the LUKS partition.

Privacy mode (independent of storage mode)

• Normal (default) — Tor routing OFF, direct internet, fast.
• Privacy Mode (opt-in) — Tor routing ON, using the preserved upstream Tor plumbing.

Both axes combine freely: 4 valid configurations.

Mode parity contract

The product target is that the same features work in all four configurations. The only intended differences are:

• Speed (Tor is slower than direct internet)
• Trace footprint (amnesia writes no user state, persistent leaves encrypted data on USB)

See docs/mode-parity.md for the exhaustive feature matrix. Anything that doesn't work in one mode gets a documented known-gap entry; no silent feature loss. Phase 8 builds the harness that proves this. Until the rebuilt ISO passes QEMU and real-USB validation, the matrix is an acceptance target, not production evidence.

Known v1.0 privacy gap: embedded browser/OAuth surfaces are not production-claimable in Privacy Mode until explicit proxy behavior is proven. The live OS routing exists, but the app/browser layer still needs validation and possibly runtime proxy injection. Documented in docs/privacy-mode-v1-gap.md. Closing this is v1.1 work.

Locked design decisions

Architecture: full-fork of Tails, additive modifications

• Tails source lives in tails/ at this directory's root (~6000 tracked files, copied from a Tails stable clone).
• We never delete Tails code. All elizaOS additions are overlays, hooks, package-list additions, and replacement files inside Tails' tree. Tor, AppArmor, MAC spoofing, Persistent Storage, Plymouth — all stay intact.
• Primary user-facing strings should say elizaOS Live. Tails is credited in legal/about surfaces, while upstream names remain in engineering paths where they are required by the live-OS plumbing.
• Matches packages/os/android/vendor/eliza/ precedent in this monorepo (brand vendor tree inside system structure).

Build system: containerized (Phase 1 — done)

Tails' upstream build drives a Vagrant + libvirt VM. We replaced that with a plain container — the container is the build environment. Any dev on Linux/macOS/Windows/CI runs just build and gets the same ISO. The earlier Vagrant attempt is documented (and buried) in docs/build-infrastructure.md; don't resurrect it.

Distribution architecture: ISO fallback plus verified updates

The production release shape is not "rebuild the ISO for every app change." The intended architecture is:

• bake a known-good elizaOS app/runtime into the read-only ISO as the factory fallback
• store app/runtime updates in encrypted Persistent Storage
• select a persistent runtime only after boot-time signature and hash verification against a signed manifest
• fall back to the ISO runtime if persistence is absent, corrupted, revoked, incompatible, or fails verification
• deliver local models through a signed model catalog and signed/hash-pinned downloads, not by silently baking large/private models into every ISO
• update the base OS through signed full ISOs first, then signed Tails-style incremental kits or binary deltas where safe
• support enterprise channels with policy pins, internal mirrors, revocation, staged rollout rings, and non-secret fleet evidence

The checked verifier foundation now exists for signed app/runtime manifests, root-owned materialization, and baked-runtime fallback. Production keys, downloader UX, revocation, mirrors, rollback health promotion, model downloads, and provenance gates are still release work. Until those exist, builds are demos or test artifacts even if they boot.

First-boot UX: elizaOS-branded greeter + elizaOS app

Tails uses a GTK greeter (tails-greeter) at first boot. We keep this UX — it's battle-tested for live-USB scenarios — and rebrand it.

Boot sequence:

1. boot menu — pick "elizaOS" or "elizaOS — Privacy Mode"
2. Plymouth splash (elizaOS wordmark)
3. elizaOS greeter (rebranded tails-greeter):
   • Language / keyboard / formats
   • Admin password (sudo)
   • MAC spoofing on/off
   • Persistent Storage: "Unlock" (if exists) / "Create" (first time)
4. GNOME loads (Tails default DE, kept)
5. The elizaOS app auto-launches as the always-on home window — chat-driven onboarding for personal choices (name, what to build first, provider sign-in). It is not a kiosk: the normal GNOME desktop stays usable, and the app is supervised by a root-owned systemd service so closing/crashing it relaunches it.

System-level choices go through the GTK greeter. Personal/AI choices go through the elizaOS app.

Branding

• Full elizaOS brand in OS UI: boot splash, greeter title + colors, GNOME theme, wallpaper. Tails onion logo replaced with elizaOS artwork.
• No visible derivative branding in the primary boot/greeter/desktop path. Attribution is visible in credits/about/license surfaces.
• Tails attribution in:
  • /usr/share/doc/elizaos-tails/CREDITS
  • About elizaOS page (system)
  • License/credits docs shipped with the image
• License posture: GPL-3.0-or-later (inherited from Tails). Our Apache-2 contributions dual-licensed where possible.

GPU access works in BOTH modes

Kernel loads GPU drivers (amdgpu, i915, nvidia, nouveau) regardless of where root filesystem lives. Vulkan / CUDA / ROCm all functional from USB boot. Local LLM gets full GPU acceleration on user's hardware.

Feature parity matrix (high level — full version in docs/mode-parity.md)

(✓ = works. ⚠ = works with caveat. ✗ = wipes on reboot by design.)

Phase 0 — Scaffold ✅ DONE

• Directory packages/os/linux/variants/milady-tails/
• README + PLAN + docs/
• Tails source copied to tails/
• Justfile

Phase 1 — Base ISO builds + boots ✅ DONE

Goal: the build pipeline runs against our Tails tree and produces a bootable ISO indistinguishable from upstream Tails.

Spec: docs/build-infrastructure.md

• Containerized build pipeline — Dockerfile, build.sh, build-iso.sh, acng.conf, Justfile (recipes build / build-fast / config / binary / nspawn / boot / clean / cache-clean)
• apt-cacher-ng wired in — required (Tails' chroot has Tor-only DNS that's dead at build time; apt reaches packages via the proxy by IP) and it caches downloads so rebuilds are fast
• 6 Tails Trixie-compat fixes (builder-box interface naming, ifupdown, isc-dhcp-client, qemu-guest-agent, vagrant agent channel, and gdisk/mtools for the partitioning initramfs hook)
• lb config go/no-go passes in the container
• Full lb build produced a finished .iso in out/
• Boot the ISO in QEMU via -cdrom; confirm Tails greeter appears
• Success: base ISO boots to the upstream Tails greeter

Phase 2 — Rebrand the greeter to elizaOS (system-level UI) 🔨 IN PROGRESS

Goal: Tails greeter still does its job, but visually it's elizaOS.

Spec: docs/specs/phase-2-rebrand.md — enumerates every file (greeter title/logo/CSS, boot menu, Plymouth, GNOME theme, wallpaper, os-release, issue), the real elizaOS asset sources, and the hard "do not rename" list (apt sources, /usr/share/doc/tails, TAILS_* keys, session-wired filenames).

• Greeter: window title → "Welcome to elizaOS!", header logo, dark CSS
• Boot menu title "Tails" → "elizaOS" (GRUB + syslinux)
• Plymouth theme → elizaOS wordmark
• GNOME default → dark elizaOS theme
• Default wallpaper + screensaver background → elizaOS
• /etc/os-release → elizaos-tails identity (keep all TAILS_* keys)
• /etc/issue MOTD → elizaOS
• Tails attribution: About/legal credits and /usr/share/doc/elizaos-tails/CREDITS
• Boot ISO in QEMU, confirm elizaOS primary branding and legal/about attribution

Brand assets are pre-rendered (greeter logo, about logo, Plymouth wordmark, wallpaper, screensaver bg) from real elizaOS sources.

Phase 3 — Privacy-mode toggle (boot-menu pick) 🔨 OVERLAY IMPLEMENTED

Goal: Two boot menu entries flip Tor routing on/off. Both produce the same elizaOS product surface, with speed/provider caveats documented.

Spec: docs/specs/phase-3-privacy-mode.md

• lib/live/config/0001-elizaos-privacy-mode — reads the privacy kernel cmdline flag (elizaos_privacy=1, with compatibility for elizaos.privacy=on) → writes /etc/elizaos/privacy-mode; malformed values fail closed to privacy/Tor mode
• etc/ferm/ferm-direct.conf — permissive firewall (Tor NAT-redirects dropped), the privacy=off counterpart to Tails' Tor-only ferm.conf
• dispatcher.d/00-firewall.sh + 10-tor.sh branch on the flag
• Boot entries: GRUB (grub.cfg edit) + syslinux (10-syslinux_customize)
• resolv.conf handled per-mode
• Test both boot entries in QEMU; confirm direct + Tor traffic

Phase 4 — Bake the elizaOS app into the ISO 🔨 OVERLAY IMPLEMENTED

Goal: /opt/milady/ exists in the chroot, contains a runnable binary.

Spec: docs/specs/phase-4-bake-milady-app.md — the real build sequence, the 9100-install-milady hook design, and the runtime-package validation direction.

• just milady-app recipe — builds the current desktop app package on the host (the build needs the eliza-first install + setup-upstreams.mjs + MILADY_ELIZA_SOURCE=local dance — a naive bun run build:desktop fails)
• Stage the app tree into tails/config/chroot_local-includes/usr/share/elizaos/milady-app/ (.gitignore'd — it is ~2.5–2.9 GB uncompressed, far too large to commit)
• tails/config/chroot_local-hooks/9100-install-milady — installs to /opt/milady/, guards version.json, fixes perms incl. chrome-sandbox setuid, then rm -rf's the staging copy (critical for ISO size)
• Runtime package support lives in tails-common.list plus the staged app bundle. There is no committed milady-runtime.list in the current tree; production should replace this with a generated, audited package manifest instead of stale docs.
• Static usr/share/applications/milady.desktop
• Build ISO, boot, launch the elizaOS app, confirm app services in QEMU on the prior validated artifact
• Repeat for current HEAD after the latest branding/docs polish

⚠ Top risk: the app tree is ~2.9 GB uncompressed (eliza-dist/ alone is 2.2 GB) — much larger than first estimated. The resulting ISO could be 3–4 GB. And chrome-sandbox under Tails' AppArmor + read-only squashfs is the most likely "boots but won't render" failure (--no-sandbox fallback documented). See the spec + ROADMAP risk section.

Phase 5 — Auto-launch the elizaOS app on greeter exit 🔨 OVERLAY IMPLEMENTED

Goal: after the greeter exits, GNOME comes up with the elizaOS app as the first window and keeps it available as the home agent without hiding the normal desktop.

Spec: docs/specs/phase-5-6-autolaunch-and-agent.md — mostly config, not code: the current implementation uses root-owned systemd supervision plus live-user services.

• etc/systemd/system/milady.path + milady.service — root-owned system service starts when the live user session bus appears, runs the app as amnesia, and restarts it if it exits
• live-user systemd services — start the agent, renderer, and app shell using /usr/local/bin/milady and elizaOS launch helpers
• /usr/local/bin/milady — pins ELIZA_STATE_DIR=/home/amnesia/.eliza plus XDG dirs in the launch env and uses a lock to avoid duplicate app instances
• etc/dconf/db/local.d/00_Tails_defaults — light elizaOS theme, wallpaper, disable GNOME welcome dialog (don't clobber Tails' enabled-extensions)
• chroot hook runs dconf update
• Verify in QEMU on prior artifact: boot → greeter → Start → GNOME → elizaOS app/services
• Repeat for current HEAD

Phase 6 — Wire app onboarding + agent on elizaOS Live 🔨 PARTIAL OS OVERLAY

Goal: the same elizaOS app stack that runs on desktop runs on this live USB.

Spec: docs/specs/phase-5-6-autolaunch-and-agent.md.

This is not "one code delta" — it is real product integration work. The live image has to align the Electrobun/CEF runtime, embedded Bun agent, plugin package graph, ~/.eliza state, model/provider defaults, and Tails' live-user session. The demo branch includes explicit runtime guards/fallbacks; production needs cleaner package boundaries and a security review of every privileged capability.

• Replace demo-only package/runtime fallbacks with first-class production package boundaries where needed
• Decide the canonical state dir (~/.eliza) + env prefix for the OS-side launch path: /usr/local/bin/milady exports ELIZA_STATE_DIR, MILADY_STATE_DIR, ELIZAOS_*, and ELIZAOS_CAPABILITY_RUNNER
• ~/.eliza works in amnesia (tmpfs) and persistent (LUKS bind-mount)
• Verify BUILD_APP (stub + Claude backends), OPEN_APP, local LLM on GPU, the v36 3-question onboarding running in chat

Phase 7 — Persistent USB integration (Tails-native) 🔨 OVERLAY IMPLEMENTED

Goal: user opts into LUKS persistence via the greeter; elizaOS app data survives reboots; no Tails persistence code is modified, only added configuration.

Spec: docs/specs/phase-7-persistence.md — note: this Tails release uses the modern Persistent Storage (tps) stack, not the legacy tails-persistence-setup. Footprint is tiny.

• One MiladyData Feature subclass in tps/configuration/features.py (bindings for ~/.eliza, ~/.milady, ~/.config/milady, enabled_by_default=True)
• One UI row in features_view.ui.in (required or the frontend crashes)
• One on-activated hook (wipe stale runtime/cache and singleton lock state)
• 2 thin agent chat actions ("save my work…", "what's on my storage?") that shell Tails' GUI — do NOT reimplement LUKS
• Verify in QEMU with a multi-partition virtual USB

Phase 8 — Mode-parity validation 📋 SPEC'D

Goal: all 4 combos work the same. Anything that doesn't = documented gap.

Spec: docs/specs/phase-8-mode-parity-harness.md — a mode-parity.sh orchestrator for this variant's QEMU and USB-image paths.

• scripts/mode-parity.sh + scripts/mode-parity-checklist.sh
• Boots all 4 {amnesia,persistent}×{normal,privacy} combos through one shared checklist, diffs them, emits parity-report.md
• just mode-parity recipe
• Fold findings into docs/mode-parity.md

Phase 9 — Rice / customization actions 📋 SPEC'D

Goal: "Install i3", "switch tiling", "swipe-down-for-notis" — all through chat with elizaOS orchestrating Linux underneath.

Spec: docs/specs/phase-9-customization-actions.md — most substrate already exists (INSTALL_PACKAGE + its confirmation flow, OPEN_TERMINAL, SET_WALLPAPER).

• SHELL action — a thin gating layer over existing install intent plus the elizaOS capability broker. Passwordless apt sudoers/polkit overlays are not accepted in the current security model.
• SET_DESKTOP, THEME, NOTIFICATIONS actions (compose the existing install flow)
• Shared customization.ts persistence-awareness helper
• docs/customization-vocabulary.md

Phase 10 — Bare-metal USB validation ⏳ NOT STARTED

• Write ISO to real USB with guarded writer and readback verification for prior artifact
• Repeat USB write/readback for current HEAD
• Boot on real hardware (2–3 machines: Intel, AMD, NVIDIA GPU)
• Verify all Phase 1–9 features work bare-metal
• Verify persistence flow on a real USB stick
• Verify GPU acceleration on real graphics cards

Phase 11 — Release v1.0 ⏳ NOT STARTED

• Doc polish, CREDITS, license bundle, and Tails attribution audit
• License audit (every file: authored vs. Tails-derived)
• SBOM generation for OS packages and bundled app/runtime payload
• Release manifest format for ISO, checksums, model catalog, and app/runtime bundle metadata
• Signing/provenance decision: production keys if ready; otherwise mark artifacts test-signed and not production-complete
• Build reproducibility/provenance check: source revision, dependency snapshot, builder image, artifact hashes, and signing event recorded
• Recovery docs for app/runtime fallback, model deletion, failed USB writes, failed OS update, and Persistent Storage migration failure
• Confirm distribution docs accurately label missing fast-update, enterprise mirror/policy, rollback, and OS delta infrastructure as demo debt if still unimplemented
• Cut release tag and attach artifacts only after the above status is explicit in release notes
• Open a Discussions thread for v1.1 priorities

Deferred / future (v1.x and beyond)

Install-to-internal-disk mode (DEFERRED, considering carefully)

"Make this my main computer. Wipe my drive, install elizaOS on it." — would let users use elizaOS as a daily-driver Linux, trading the live-USB constraints for full hardware speed + storage.

Why deferred and being considered with respect for Tails' design:

Tails refuses to install itself to disk by design. Their reasoning:

• Disk = traceable. Log files, swap, fsync'd writes leave forensic evidence that contradicts Tails' "leave no trace" promise.
• Live-USB enforces good habits. If everything wipes on reboot, users naturally treat each session as fresh.
• The threat model assumes adversaries with physical access, who could analyze a disk image but not a powered-off RAM stick.

We respect that reasoning. An elizaOS ISO that defaults to amnesia inherits the same forensic protection. Tails users picked Tails specifically because there's no disk install option — adding one without thought betrays that choice.

That said: elizaOS Live's target audience is broader than Tails'. Many users want "AI Linux as my daily driver" without needing amnesia-on-laptop. For them, install-to-disk would be a real product.

Before we add it, we need a real design RFC covering: the threat model when installed, default full-disk encryption, the dual-boot story, the install UX (Calamares vs. an elizaOS app flow), and the Tails community pulse on the derivative. Planned target: v2.0, after v1.0 ships and real users tell us what they want. For now: don't add it.

Embedded web/OAuth proxy patches (v1.1)

Closes the Privacy Mode embedded-web gap. Patch the active app shell/runtime to inject an explicit Tor proxy into any external web/OAuth surface when elizaos.privacy=on. If CEF/Electrobun is active, that likely means --proxy-server=socks5://127.0.0.1:9050; if WebKit is active, it needs the equivalent WebKit/network-context proof.

Runtime privacy toggle (v1.2 or later)

Switch privacy modes mid-session without reboot. iptables atomic swap + tor.service start/stop + Chromium re-proxy.

Cross-distro install medium (post-v2.0)

.deb, .AppImage, Flatpak packaging. Lower priority — the live-USB IS the product.

Risk inventory

1. Tails build latent bugs — every build run so far surfaced a real Trixie-compat bug. 6 found + fixed; more may surface in the chroot hooks / binary stage. The containerized loop + apt-cacher-ng cache makes each iteration fast.
2. ISO size — the current app tree is ~2.9 GB uncompressed. On top of Tails (~1.3 GB squashfs) the ISO could be 3–4 GB. Mitigations: the 9100 hook must rm -rf the staging copy; consider a slimmer build profile; re-measure and budget. See Phase 4 spec.
3. chrome-sandbox under AppArmor + squashfs — the likely "boots but the elizaOS app won't render" failure. --no-sandbox is the documented fallback.
4. Phase 6 is real product integration — not a quick edit. CEF, embedded Bun, bundled plugins, model/provider defaults, state dirs, and supervised OS capabilities all have to agree inside the live-user session. The in-session model helps, but it still needs proof.
5. Desktop app build fragility — the desktop build needs a specific eliza-first + setup-upstreams.mjs + MILADY_ELIZA_SOURCE=local sequence; a naive bun run build:desktop fails. Encoded in just milady-app.
6. Large monorepo bloat — the vendored tails/ tree is ~6000 files. PR maintainers may push back; submodule pattern is the fallback.
7. Tor blocking cloud APIs — Anthropic/OpenAI often refuse Tor exit IPs. In Privacy Mode cloud chat may fail; local LLM still works.
8. Embedded web/OAuth proxy gap (v1.0) — live OS routing exists, but embedded browser/OAuth surfaces are not production-claimable in Privacy Mode until explicit proxy behavior is proven.
9. Cold-boot RAM attacks — theoretical threat against amnesia. Tails' memlockd zeros RAM on shutdown; we keep it.

Open questions

• Which Tails release tag to track? Currently a Tails stable clone. Pin in tails/debian/changelog; document upgrade cadence.
• Vendored tails/ git strategy — the vendored copy ships without .git; build-iso.sh git inits a throwaway repo at build time so the build works either way. Long-term: keep as committed files, or convert to a submodule of an elizaOS Tails fork. Decide before v1.0.
• Default browser in Normal Mode — Tor Browser doesn't fit direct internet. Or: no browser, elizaOS opens links in app-mode windows.
• Canonical state dir + env prefix — elizaOS Live should standardize on ~/.eliza for product state while supporting existing app/runtime paths (MILADY_*, ~/.milady) until the app package is renamed.

How to contribute

The build needs only Docker. From this directory:

just config        # ~1 min go/no-go — does the Tails config tree process?
just build         # full clean ISO → out/  (~1–1.5 h cold, faster cached)
just binary        # ~10 min incremental rebuild after editing overlay files
just nspawn        # seconds — boot the built chroot for non-GUI sanity
just boot          # boot the latest ISO in QEMU

Pick a phase, read its spec in docs/specs/, implement against the vendored tails/ tree, validate with just binary + just boot. Exploratory work until Phase 10 ships a real v1.0 ISO that boots on bare metal.