Skip to content
Get packs

Guide · Open source

How to use Eliza (elizaOS): install from source and run it

Updated · written with AI from the project's own documentation and checked against our catalogue data

elizaOS is an open-source TypeScript framework and product stack for running autonomous AI agents. This guide explains what the elizaOS repository contains, how to clone and start it from source, and which commands you will use most. It is written for readers who are comfortable with a terminal and want to build or run an agent on their own machine.

ElizaelizaOS/eliza · ★ 19.8k · MIT

Quick start

  1. 1Check prerequisites. Install Git, Bun, and the Node.js version pinned in package.json. Bun's version is also pinned there.
  2. 2Clone the repository. Run the git clone command with the --filter=blob:none flag from the README.
  3. 3Enter the folder. Change into the eliza directory with cd eliza.
  4. 4Install dependencies. Run bun install. This also prepares submodules, patches and the desktop inference library.
  5. 5Start the app. Run bun run dev to start the app, or bun run dev:local to use the local runtime chooser with your own provider keys.

What is elizaOS and what does the repository contain?

elizaOS is described in its README as a framework and product stack for autonomous AI agents. The monorepo includes a core runtime, the Eliza app, a command-line tool, cloud services, native bridges, and first-party plugins.

The framework is model-agnostic, so it can use local models or hosted model providers. Plugins add abilities such as chat, memory, messaging connectors, and browser automation.

  • @elizaos/core defines AgentRuntime, the shared types, memory and state primitives, and plugin contracts.
  • @elizaos/agent assembles a standalone agent and HTTP backend around the core runtime.
  • @elizaos/ui contains the shared React UI used by app surfaces.
  • plugins/ holds first-party model, connector, domain, app, and device plugins.

Choose a starting point before you install

The README lists several routes. If you only want to use Eliza, the README points to the web app, the Eliza downloads page, or a published GitHub release. You do not need to build from source for that.

Building from source is the route for developers. Use it if you want to run this repository, change code, or build an agent or plugin.

  • Use Eliza: open the web app, visit Eliza downloads, or use a GitHub release.
  • Run this repository: follow the source steps below.
  • Build an agent or plugin: start with the runtime and the developer docs.

Install and run Eliza from source

The repository pins Bun and Node.js versions in package.json. Install those versions first, and make sure Git is available. Then clone the repository, enter the folder, install dependencies, and start the app.

According to the README, bun install also prepares submodules and patches, and builds or verifies the staged desktop libelizainference. The embedding GGUF model is downloaded automatically during local-inference warmup.

  • Prerequisites: Bun (version pinned in package.json), Node.js (version pinned in package.json), and Git.
  • Python 3.11+ is needed only for benchmarks.
git clone --filter=blob:none https://github.com/elizaos/eliza.git cd eliza bun install bun run dev

Pick the right run command

The README lists several repository commands. The two you will use most at the start are bun run dev, which starts the app, and bun run start, which runs the standalone agent host without a UI.

bun run dev:local starts the app and API with a runtime chooser. The README says it runs a local agent with your own provider keys and does not require Eliza Cloud sign-in.

  • bun run dev:local: app and API, local agent, own provider keys, no Cloud sign-in required.
  • bun run start: standalone agent host, API only, no UI.
  • bun run build: builds the workspace with Turbo.
  • bun run verify: runs dependency, type, lint, and audit gates.
  • bun run test: runs the repository end-to-end test lane.
  • bun run cloud:mock: runs a local Eliza Cloud stack with mocks.
bun run dev:local bun run start

Understand models: local, own keys, or Eliza Cloud

Eliza can route each model capability to a local backend, a direct model provider using your own keys, or Eliza Cloud. The README says local inference is not forced on hardware that cannot support it.

The Eliza-1 on-device path is provided by @elizaos/plugin-local-inference. The README says the current registry has 2B, 4B, 9B, and 27B text tiers based on Gemma 4. After the required assets are downloaded, eligible operations can run without a network connection. Eliza Cloud is optional.

Build an agent or plugin with the plugin system

To embed the runtime directly without an application host, import @elizaos/core. A plugin exports a Plugin object. Plugins can register actions, providers, evaluators, services, model handlers, routes, events, tests, and app views.

Read the plugin component guide in the official docs and the first-party implementations under plugins/ before writing your own.

  • Actions, providers, evaluators, services, model handlers, routes, events, tests, app views.

Know the contribution and plugin rules

The README says contribution rules are required for all issues and pull requests. New features need maintainer discussion and approval first. Submit changes as a pull request against develop.

The README also says third-party plugins and registry listings are no longer accepted. Related issues and pull requests will be closed as out of scope.

  • Submit pull requests against the develop branch.
  • Follow AGENTS.md and the owning package's README.
  • Third-party plugin submissions and registry listings are not accepted.

What people use it for

  • Building a TypeScript AI agent that runs on your own computer.
  • Writing a plugin that adds actions or providers to the runtime.
  • Running a personal assistant with your own model provider keys.
  • Testing local inference with the Eliza-1 on-device path.
  • Running the standalone agent host as an API without a UI.

Frequently asked questions

Is elizaOS free and open source?

Yes. The repository is licensed under the MIT licence and written in TypeScript. The README also lists optional paid or hosted services such as Eliza Cloud, and live benchmarks may incur usage costs for model providers.

What do I need to install elizaOS?

You need Git, Bun and Node.js. The Bun and Node.js versions are pinned in package.json. Python 3.11 or newer is only needed for benchmarks.

What is the install command for elizaOS?

Clone the repository with git clone --filter=blob:none https://github.com/elizaos/eliza.git, then run cd eliza, bun install and bun run dev.

Can I run elizaOS without a cloud account?

Yes. The README says bun run dev:local runs a local agent with your own provider keys and does not require Eliza Cloud sign-in. Eliza Cloud is described as optional.

Is elizaOS a good alternative to LangChain, AutoGPT, CrewAI or AutoGen?

elizaOS is a TypeScript framework with a large monorepo that includes an app, CLI and plugins. LangChain, AutoGPT, CrewAI and Microsoft AutoGen are comparable projects. Pick elizaOS if you want TypeScript and a plugin system; the README does not compare it directly with those tools.

Why does my elizaOS install fail?

The README says the setup assumes Bun, Node versions and command-line work. Check that your Bun and Node.js versions match package.json, and that Git is installed. The package READMEs document setup for each capability.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use elizaOS if you are a developer who wants to build AI agents or plugins in TypeScript, or if you want a personal assistant that runs on your own hardware or with your own provider keys. Pick a simpler tool if you want a one-click chat app or a small, stable library, since this repository is a large monorepo that assumes command-line work.

Install options & downloads