elizaos--eliza/packages/app

@elizaos/app

The cross-platform renderer shell for elizaOS — the top-level Vite application that boots the Eliza agent UI on web browsers, Electrobun desktop (macOS/Windows/Linux), and Capacitor-wrapped iOS/Android.

This package is private (not published to npm) and has no CLI binary. It is the composition root: it wires the @elizaos/* plugins and UI packages into a bootable app and hands off rendering to @elizaos/ui. The packaged dist/ output is consumed by the Electrobun desktop shell and by Capacitor for mobile. Nothing imports from this package; it imports from everything else.

For the agent-facing deep dive (boot sequence, plugin loader, white-label seam, gotchas), see AGENTS.md.

Layout

app.config.ts        App identity (appId, appName, envPrefix, urlScheme, branding)
capacitor.config.ts  Capacitor mobile config (derived from app.config.ts)
vite.config.ts       Build config — alias resolution, chunk splitting, Vite plugins
index.html           HTML shell (tokens replaced at build by appShellMetadataPlugin)
src/
  main.tsx           React boot: plugin loading, root render, platform init
  app-config.ts      Re-exports APP_CONFIG and derived branding/namespace constants
  deep-link-routing.ts  Custom URL scheme → hash route mapping
  mobile-*.ts        Capacitor bridges + app lifecycle
vite/                Browser-bundle Vite plugins (native-module-stub-plugin.ts)
scripts/             Build, plugin build, Playwright runner, mobile preflight/install
test/                Vitest unit tests + Playwright specs
ios/ android/        Native projects generated by Capacitor
public/ dist/        Static assets / Vite build output

Commands

Run from the repo root with --cwd packages/app, or from inside the package directly.

bun run dev            # Vite dev server (renderer only; UI port from ELIZA_UI_PORT, default 2138)
bun run build          # Full app build (scripts/build.mjs)
bun run build:web      # Vite build only (no Capacitor sync)
bun run plugin:build   # Plugin-only build
bun run preview        # Vite preview server
bun run lint           # Biome check
bun run typecheck      # tsc --noEmit
bun run test           # Vitest unit tests
bun run test:e2e       # Playwright UI smoke (ui-smoke config)

# Mobile
bun run ios            # Build + open Xcode
bun run android        # Build + open Android Studio
bun run cap:sync       # Capacitor sync (both platforms) + patch iOS plist

The desktop shell is built by Electrobun from the repo root (bun run dev:desktop), not from inside this package — packages/app only produces the renderer.

Config

App identity lives in app.config.ts (envPrefix: "ELIZA"); copy that file to white-label a new app. Runtime/build env vars use the ELIZA_ prefix. See AGENTS.md for the full env var table; .env.example documents the build-time VITE_* flags.

Launch Surface

All boot/launch surfaces are black #000000 (DEFAULT_BACKGROUND_COLOR, the base field under the home ShaderBackground's orange ember glow): the native splashes (capacitor.config.ts, Android launch resources, iOS LaunchScreen.storyboard) and the persistent host-chrome surfaces (index.html FOUC background, <meta name="theme-color"> / manifest colors via app.config.ts, the renderer root CSS). The persistent surfaces stay visible under the app (iOS home-indicator safe-area, overscroll), so they must equal the default home background base for bleed-through to be invisible — and boot never paints orange. The brand accent stays #FF5800.

License

MIT