packages/app/README.md
A personal AI assistant you run on your own devices, built on elizaOS. Cross-platform — macOS, Windows, Linux, iOS, and Android.
macOS / Linux / WSL:
curl -fsSL https://elizaOS.github.io/eliza/install.sh | bash
Windows (PowerShell):
irm https://elizaOS.github.io/eliza/install.ps1 | iex
npm install -g @elizaos/app
eliza setup
bunx @elizaos/app setup
# or
npx @elizaos/app setup
Desktop builds are published on the GitHub Releases page when a signed release has completed. Mobile distribution is store-first: TestFlight/App Store for iOS and Play testing/Play Store for Android. Developer sideload paths are for contributors and QA, not the public mobile install path.
| Platform | Format |
|---|---|
| macOS (Apple Silicon) | .dmg |
| macOS (Intel) | .dmg |
| Windows | .exe installer |
| Linux | .AppImage, .deb, .rpm when attached to the release |
| iOS | TestFlight / App Store (coming soon); local Xcode sideload for development |
| Android | Play Store (coming soon); signed QA APK attached by release CI for QA/developer install |
Developer preflight checks:
bun run preflight:ios:sideload
bun run preflight:ios:store
bun run preflight:android:sideload
bun run preflight:android:store
Developer install helpers:
# iOS: checks Xcode/device prerequisites and opens the workspace.
bun run install:ios:sideload
# Android: installs the latest local APK with adb, or builds first.
bun run install:android:adb -- --build
bun run install:android:adb -- --apk ./android/app/build/outputs/apk/debug/app-debug.apk
eliza onboard --install-daemon
eliza agent --message "hello" --thinking high
Prerequisites: Node.js >= 22, bun
git clone https://github.com/elizaOS/eliza.git
cd eliza
bun install
bun run build
cd packages/app
bun install
bun run build:desktop
bun run dev:desktop
cd packages/app
bun run dev
# iOS (requires macOS + Xcode 15+)
bun run ios
# Android (requires Android Studio + SDK 34+)
bun run android
bun run plugin:build
If the embedded agent fails to load (e.g. missing native module), the app keeps the API server up so the UI can show an error instead of "Failed to fetch". Why: Without that, one load failure would close the API server and the window would show only "Failed to fetch" with no message. See Electrobun startup and exception handling for why the guards in electrobun/src/native/agent.ts exist and must not be removed.
Dynamic plugin imports (import("@elizaos/plugin-*")) resolve from the importing file's location. In dev mode and CLI, that can miss root node_modules. We set NODE_PATH to repo root in src/runtime/eliza.ts, scripts/run-node.mjs, and electrobun/src/native/agent.ts (dev path). Why: Without this, dynamically loaded plugins fail with "Cannot find module" on boot. For Bun specifically, some published plugins have exports["."].bun = "./src/index.ts" (missing in the tarball); we patch those in scripts/patch-deps.mjs so Bun resolves via dist/. See Plugin resolution and NODE_PATH (including "Bun and published package exports").
Plugin and native deps for the packaged app are copied into eliza-dist/node_modules by the release packaging scripts (scripts/copy-runtime-node-modules.ts for Electrobun). They derive the runtime package closure from installed package metadata and the built server bundle instead of maintaining a manual allowlist. macOS Intel builds run install and build under Rosetta so x64 native binaries are included. Why: Build and release (CI, desktop binaries) explains arch, copy script, and release workflow.
# from repo root
bun run test
MIT