elizaOS

Your agentic operating system.

Eliza · Eliza Cloud · elizaOS downloads · Documentation

elizaOS is an open-source TypeScript framework and product stack for autonomous AI agents. This monorepo contains the core runtime, the Eliza app, the CLI, cloud services, native bridges, and first-party plugins. Android distribution tooling lives in packages/os.

The repository pins Bun and Node versions in package.json. Install Bun, then:

git clone --filter=blob:none https://github.com/elizaos/eliza.git
cd eliza
bun install
bun run dev

bun install also prepares submodules and patches, provisions supported host build prerequisites, and builds or verifies the staged desktop libelizainference. The embedding GGUF remains runtime-managed and downloads automatically during local-inference warmup. Fetch archived artifact fixtures explicitly with bun packages/scripts/fetch-archive-artifacts.ts when needed.

Common repository commands:

bun run dev:local   # app + API with the runtime chooser (local agent, own provider keys; Cloud sign-in not required)
bun run start       # run the standalone agent host (API only, no UI; use bun run dev for the app)
bun run build       # build the workspace with Turbo
bun run verify      # dependency, type, lint, and audit gates
bun run test:quint  # application state models and invariants
bun run test        # repository end-to-end test lane
bun run test:e2e    # end-to-end lane
bun run cloud:mock  # local Eliza Cloud stack with mocks

Package build/test commands are in each package's README. Use bun run --cwd <package> <script> to scope a command.

Bun 1.4.2 (packageManager) runs the product, the build, bun run verify, and the repository scripts: run a script with bun <script>.ts. Node 24.15.0 (engines.node) is needed only for the lanes below. They fail on Bun 1.4.2, could not be shown to pass on it, or must prove behavior on Node:

• Vitest. packages/scripts/run-vitest.ts always starts Vitest on Node. Bun fails suites that Node passes (fetch of an uppercase DATA: URL, http.Server.closeAllConnections, child Node ESM probes).
• Quint conformance replays (check-quint.ts without --inventory), because they run Vitest.
• node --test suites that use module.stripTypeScriptTypes, built-in module mocks, or a nested Wrangler. Their package scripts still start with node.
• node --test --test-reporter=tap suites whose TAP output a Quint conformance check reads case by case (plugins/plugin-assistant test:files-review). bun test has no TAP reporter.
• Wrangler (wrangler dev --local accepts no request on Bun).
• packages/app launchers that load tsx (run-node-tsx.ts, run-release-check.ts) and the node:test half of run-script-tests.ts.
• CI: the Bun download in .github/actions/setup-bun-workspace, and workflow jobs that install no Bun.
• Syntax checks. node --check parses a file without running it; bun --check runs the file. The Pages Functions checks in cloud-cf-release.yml and pr-validation.yml use Node.
• Packed-package consumer checks (packages/core/scripts/verify-package.ts, the plugin-elizacloud verify-built-package.ts, and packages/ui/scripts/verify-batch-voice-package.ts). The packages declare engines.node, so the consumer runs on a real Node found on PATH.
• Install scripts of published packages (plugins/plugin-computeruse postinstall), because npm users have no Bun.
• Native and device build paths that still start node and were not proven on Bun: the packages/os/android Makefile, AOSP and Pixel scripts in packages/os/scripts/android, compile-libllama.ts (patch step), the iOS xcframework and engine scripts (build-xcframework.ts, mobile/ios/engine.ts), paradee-voice/build-native.ts, Mac App Store signing in desktop-build.ts, and the SMS gateway and Cloud gateway maintenance scripts.

Use Python 3.11+ and install the dependencies required by the selected suite, then run from the repository root:

PYTHONPATH=packages python3 -m benchmarks.orchestrator list-benchmarks
PYTHONPATH=packages python3 -m benchmarks.orchestrator run --benchmarks <id> --provider <provider> --model <model>

See benchmarks for setup. Live benchmarks require the selected provider's credentials and may incur usage costs.

Eliza is the user-facing agent app for web, desktop, and mobile targets. Its capabilities are supplied by the runtime and installed plugins, including:

• chat, voice, memory, knowledge, and document workflows;
• messaging and workspace connectors;
• calendar, reminders, inbox, goals, health, and other personal-assistant domains;
• browser and desktop automation;
• camera, phone, messages, contacts, location, and other native device bridges;
• non-custodial EVM and Solana wallet operations with approval boundaries; and
• scheduled workflows, coding-agent orchestration, and installable app views.

Availability depends on the operating system, installed plugins, granted permissions, and configured model or service providers. Package-level READMEs document the exact support and setup for each capability.

The framework is model-agnostic and extended through plugins:

• @elizaos/core defines AgentRuntime, the canonical types, authorization, memory and state primitives, and plugin contracts.
• @elizaos/agent assembles a standalone agent and HTTP backend around the core runtime.
• @elizaos/app provides shared application hosting, API, and platform orchestration for Eliza app targets.
• @elizaos/ui contains the shared React UI used by app surfaces.

A plugin exports a Plugin object. Plugins can register actions, providers, evaluators, services, model handlers, routes, events, tests, and app views. See the plugin component guide and the first-party implementations under plugins/.

@elizaos/plugin-local-inference provides the Eliza-1 on-device path. The current Eliza-1 registry contains 2B, 4B, 9B, and 27B text tiers based on Gemma 4, plus local embeddings, speech, vision, and image-generation assets. Hardware detection and model routing select supported backends; after the required assets are downloaded, eligible operations can run without a network connection.

Local inference is not forced on hardware that cannot support it. Eliza can route each model capability to local, direct-provider, or Eliza Cloud backends.

Eliza Cloud is optional. It provides account and authentication services, hosted model routing, application and agent deployment, remote connectivity, and cross-device product services. The local runtime and direct model-provider configuration remain first-class paths.

packages/os owns the bootable AOSP distribution, release manifests, and OS toolchains. Application shells and native runtime bridges live in their owning app and plugin packages.

To embed the runtime directly without an application host, import @elizaos/core. The scenario runner provides executable integration coverage against a real runtime and, when configured, live models.

packages/        runtime, hosts, UI, CLI, docs, cloud, native code, and tooling
plugins/         first-party model, connector, domain, app, and device plugins
packages/scripts/ repository-wide checks, test orchestration, and release tools
patches/         dependency patches applied during installation

Every maintained package or plugin should explain its public surface, scripts, configuration, and local constraints in its own README.md. Read that README before making changes. The root AGENTS.md is the only repository agent guide; do not add nested AGENTS.md files.

• Contributors must write and submit issues by hand on GitHub. Agents must not draft or create issues. See the human-only issue rule.
• Report real bugs or missing approved MVP requirements. Link the PRD and MVP plan. New features need human maintainer discussion and approval, then updates to both plans before implementation issues or PRs are opened.
• Prove a useful improvement with before-and-after behavior or relevant scores. Prefer cleanup, removal, reuse, and combined types and functions. Add new types or code only when necessary. Explain the research, alternatives, and choice.
• Do not add unnecessary tests, defensive code, validation, or truncation. Provide real end-to-end test results. Use existing tests first. Avoid new unit tests, mock-only proof, and tests that repeat the implementation.
• Every UI PR needs an uploaded MP4 explainer and walkthrough, video evidence of the changed flow, desktop and mobile screenshots, the app visual audit, and detailed steps to test the change.
• Write issues and PRs in ASD-STE100 Simplified Technical English. Use short, direct sentences and explain technical terms for a non-technical reader.
• Slop bounty work: star and fork the repository first, use real LLM calls, make no UI changes, and test in more than one agent client. See Slop bounty contributions.

elizaOS focuses on its first-party runtime, applications, and maintained integrations. We no longer accept third-party plugins or registry items, including new listings, listing updates, and registry submission tooling. Related issues and pull requests will be closed as out of scope.

Submit changes through a pull request against develop; follow AGENTS.md and the owning package's README. Include verification of the changed behavior.

Report vulnerabilities privately through GitHub Security Advisories or [email protected].

MIT