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. Linux and Android distribution tooling lives in packages/os.

Choose a starting point

Goal	Start here
Use Eliza	Open the web app, visit Eliza downloads, or use a published GitHub release
Run this repository	Follow Run Eliza from source
Build an agent or plugin	Start with the runtime and the developer docs
Contribute	Read the required contribution rules and AGENTS.md
Run a whole device as elizaOS	Start with the build requirements and target guides in packages/os

Run Eliza from source

The repository pins Bun and Node versions in package.json. Install those versions, 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 start       # run the standalone agent host
bun run build       # build the workspace with Turbo
bun run verify      # dependency, type, lint, and audit gates
bun run test        # repository unit/integration 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.

Benchmark

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.

What is in the stack?

Eliza

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

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/.

Local inference

@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

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.

elizaOS distributions

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

Build an agent

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.

Repository map

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 and paired AGENTS.md. Read the nearest package guide before making changes.

Contributing

Important

Read this before you open an issue or pull request. These rules are required. Work must support the approved minimum viable product (MVP) and product requirements document (PRD). Maintainers will close unnecessary work. Contributors who submit unnecessary work will be subject to penalties set by maintainers.

Issue scope

Report a real bug or a missing requirement in the approved MVP. Link the relevant PRD section and MVP plan item. Show the problem, its effect on users, and the expected result. Follow this guide and the owning package's guide.

Do not submit work for minor points with no useful effect. Do not add unnecessary tests, defensive code, validation, or truncation. Do not expand the MVP through an issue or pull request. For a new feature, first discuss it with human maintainers. Maintainers must approve it and add it to the PRD and MVP plan before an implementation issue or pull request is opened. If the requirement is unclear or you cannot find the approved plan, ask maintainers before you start.

Pull request requirements

• Prove a useful improvement. Show a failure before the fix and a successful result after it, a gain in accuracy or another relevant score, or a demonstrated improvement to an approved capability. State the test conditions and results.
• Make the code simpler. Remove unnecessary code. Combine duplicate types and functions. Use existing work. Add a type or code only when the approved task needs it. Explain why existing code cannot meet that need.
• Explain the choice. Show what you researched, the alternatives you examined, and why the selected implementation is the best fit. Keep the explanation proportional to the change.
• Test the real behavior. Run the relevant end-to-end flow and provide the commands, setup, results, and evidence for the reviewed commit. Use existing tests first. Avoid new unit tests, tests that only check mocks, and tests that repeat the implementation. A test count or a passing mock is not proof that the product works. Run the required package checks and repository checks. For documentation-only changes, check the text and links; do not add artificial runtime tests. State any failed or blocked checks.
• For every UI change, upload an MP4 walkthrough to the PR. Explain the change in the video and show the complete user flow working. Include video evidence of the changed behavior, desktop and mobile before-and-after screenshots, the app visual audit, and detailed steps for a reviewer to test the change. Screenshots alone do not meet the video requirement.
• Write every issue and PR in ASD-STE100 Simplified Technical English. Use short, direct sentences and consistent terms. Explain necessary technical terms. A non-technical reader must be able to understand the problem, change, and test steps.

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 guide. Include verification of the changed behavior.

Report vulnerabilities privately through GitHub Security Advisories or security@elizalabs.ai.

License

MIT