elizaos--eliza/packages/os/linux/docs/runtime-packaging.md

Runtime Packaging

The elizaOS/Electrobun app is staged into the live-build overlay at:

tails/config/chroot_local-includes/usr/share/elizaos/elizaos-app/

The 9100-install-elizaos chroot hook copies that tree to /opt/elizaos. The staged app is intentionally not slimmed in this step; the current goal is to make the bundled runtime auditable before any ISO build runs.

This is not a post-boot injection path. The app is built before the ISO build, staged as a live-build overlay artifact, installed into the read-only root filesystem during the chroot hook phase, and launched from /opt/elizaos as the normal live user. The chroot hook may set ownership, permissions, metadata, and runtime compatibility defaults; it must not download packages, resolve Node dependencies, or mutate user data.

Review Decision

Current status: acceptable for demo and release-candidate validation, not the final production packaging shape.

The current path is clean enough for a working ISO demo because it has a single staged runtime root, root-owned install destination, manifest, validation script, and smoke coverage. It is still not the ideal enterprise artifact because the Electrobun runtime tree is large and the live overlay still carries generated compatibility stubs for optional packages.

Production replacement:

• build the desktop app in CI as a deterministic signed artifact
• publish a runtime manifest with complete file inventory and package inventory
• install the signed artifact into /opt/elizaos or a versioned root-owned runtime store during image build
• keep /opt/elizaos as the immutable factory fallback
• activate later app/runtime updates only through the signed update-manager path
• remove generated stubs for required features by fixing the app dependency graph, not by hiding missing packages
• make clean checkout builds explicit: just elizaos-app must stage the app payload before just build/just binary; source-only smoke is expected to pass without the ignored 2.5-2.9 GB payload, full smoke requires the stage

The build-time prepare script is allowed only as a packaging adapter. It must stay idempotent and auditable, and every generated fallback must be declared in Resources/app/elizaos-live-overlay-manifest.json.

Manifest

scripts/prepare-elizaos-app-overlay.mjs writes:

Resources/app/elizaos-live-overlay-manifest.json

inside the staged app root. The manifest is an SBOM-style audit record for the runtime overlay. It records:

• the staged app root and installed app root (/opt/elizaos)
• source git commit and generation time
• package manifest count plus package inventory from eliza-dist/node_modules
• generated live packages and optional plugin stubs
• key app and OS entrypoints
• expected API and renderer ports
• known repository-resolution strings that must not regress to elizaOS defaults

Optional connector stubs are deliberately listed under generated.optionalPluginStubs. If a full package is present, the manifest records that the stub was not generated. If a live stub package exists without a matching manifest entry, validation fails.

Validation

Run the cheap validator after staging the app:

node scripts/validate-runtime-overlay.mjs --stage tails/config/chroot_local-includes/usr/share/elizaos/elizaos-app

The validator does not build an ISO. It checks:

• required app entrypoints such as bin/launcher, bin/bun, Resources/app/eliza-dist/entry.js, and renderer index.html
• OS overlay entrypoints such as /usr/local/bin/elizaos, the user service launchers, the renderer server, and systemd units
• manifest package count against actual package.json files
• generated optional plugin stubs and undeclared live stub packages
• dependency symlinks from the app root and bin/
• elizaOS branding in version.json and brand-config.json
• hard-coded elizaOS repo/app resolution strings in renderer and brand config
• API and renderer port defaults across the manifest, launcher wrappers, renderer server, and WebKit shell

scripts/prepare-elizaos-app-overlay.mjs --check still verifies that the staged overlay has already been patched by the prepare script. The validator is the more explicit runtime-packaging audit and should be used when the staged app is present.

Remaining Debt

This slice does not solve package slimming. The app still carries the bundled runtime tree produced by the desktop build, plus compatibility stubs for optional connectors that are not part of the live USB base runtime.

The manifest is a static audit record, not a runtime attestation. It can prove that staged files and defaults are internally consistent before a build; it cannot prove that the final ISO boots, that Electrobun launches successfully, or that no dynamic runtime import path is missed.