# elizaOS/eliza: an agentic operating system that runs apps, not just an agent

> elizaOS is a TypeScript monorepo for autonomous agents, with a core runtime, a user-facing Eliza app, a CLI, and first-party plugins. The README is strong on architecture and thin on operational detail, so the interesting question is what you actually get when you run it.

**elizaOS/eliza** — Open source agentic operating system. Apps on elizaOS elizaOS runs apps, not just an agent.

- Repository: https://github.com/elizaOS/eliza
- Website: https://elizaos.ai/
- Stars: 19,509 · Forks: 5,770
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/elizaos-eliza

## What elizaOS/eliza actually is, and who it is for

The README calls elizaOS an "open-source TypeScript framework and product stack for autonomous AI agents" and describes the repository as a monorepo holding the core runtime, the Eliza app, the CLI, cloud services, native bridges, and first-party plugins. The distinction that matters is in the project's own framing: apps run on elizaOS, so the unit of deployment is an application hosted by the runtime rather than a single conversational agent.

That shapes the audience. If you want a chat loop and a model key, this is more machinery than you need. If you are building a product where an agent has to hold memory, call tools, reach device APIs, and expose its own views inside a host application, the repository layout is aimed at you. The README lists the intended capabilities plainly: chat, voice, memory, knowledge and document workflows; messaging connectors; calendar, reminders, inbox, goals and health domains; browser and desktop automation; native device bridges for camera, phone, messages, contacts and location; non-custodial EVM and Solana wallet operations with approval boundaries; and scheduled workflows with coding-agent orchestration.

It also states the boundary that most summaries skip. Availability depends on the operating system, installed plugins, granted permissions, and configured model or service providers, and package-level READMEs hold the exact support and setup for each capability. The top-level README is a map, not a contract.

## The runtime, the plugin contract, and where the app shell sits

The architecture is legible from the package list. @elizaos/core defines AgentRuntime along with the canonical types, the message loop, memory and state primitives, and the plugin contracts. @elizaos/agent assembles a standalone agent and an HTTP backend around that runtime. @elizaos/app-core provides shared application hosting, API, and platform orchestration for Eliza app targets, while @elizaos/ui holds the shared React UI used by app surfaces.

The extension point is a Plugin object. According to the README, a plugin can register actions, providers, evaluators, services, model handlers, routes, events, tests, and app views. That list is the real design decision here. Most agent frameworks stop at actions and providers; registering routes and app views means a plugin can ship its own interface, which is what makes the "apps on elizaOS" claim more than a slogan. A calendar plugin can bring a calendar screen, not just a tool the model calls.

Model routing is layered rather than fixed. The framework is described as model-agnostic, and the README states that Eliza can route each model capability to local, direct-provider, or Eliza Cloud backends. @elizaos/plugin-local-inference supplies the on-device path, with an Eliza-1 registry containing 2B, 4B, 9B, and 27B text tiers based on Gemma 4 plus local embeddings, speech, vision, and image-generation assets. Hardware detection picks supported backends, and eligible operations can run without a network connection once the assets are downloaded. The README is explicit that local inference is not forced on hardware that cannot support it, which is the right default but also means your effective capability set depends on the machine.

## Running Eliza from source with Bun

The README pins Bun and Node versions in package.json and tells you to install those versions first. The engines field in package.json shows node 24.15.0. The clone uses a blob filter to avoid pulling history you do not need, then bun install, then bun run dev.

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

Two details in the README are worth reading twice. First, bun install also prepares submodules and patches, and the postinstall script in package.json confirms the scale of that work: it builds shared i18n data, patches nested core dist files, patches a punycode deprecation, patches llama-cpp-capacitor, patches an Electrobun Linux CEF profile, ensures workspace symlinks, builds private workspace packages, builds views, and ensures a fused inference install. That is a lot of mutation happening behind a single install command. Second, the legacy archive artifact bundle is never pulled implicitly; you fetch it deliberately with bun run fetch:archive-artifacts if you need those fixtures.

The repository commands are the ones you will actually use day to day. bun run build builds the workspace with Turbo. bun run verify runs package parity, dependency, type, lint, and audit gates. bun run test and bun run test:e2e cover the unit and integration lane and the end-to-end lane. bun run cloud:mock brings up a local Eliza Cloud stack with mocks, and cloud:mock:fresh adds a --reset flag for a clean start.

## Scaffolding a project or plugin with the elizaos CLI

The README states that the beta CLI published from this branch uses the unscoped elizaos package, which is a naming detail worth noticing because scoped variants exist elsewhere in the ecosystem. Installation is global, and the create command takes a template argument.

```bash
bun add --global elizaos@beta
elizaos create my-project --template project
elizaos create plugin-example --template plugin
```

The README draws the distinction between the two templates: projects are deployable workspaces, plugins are reusable capability packages. The packaged templates and their scaffold contracts live in packages/elizaos/templates/, so the generated layout is inspectable before you commit to it. If you would rather skip the CLI and the application host entirely, the README says to import @elizaos/core directly. It also mentions a scenario runner that provides executable integration coverage against a real runtime and, when configured, live models.

Server configuration is environment-driven. The .env.example file sets SERVER_PORT=3000 and leaves SERVER_HOST empty with a documented default of 0.0.0.0. NODE_ENV defaults to development, and ELIZA_UI_ENABLE controls whether the web UI is served: enabled in development, disabled in production, or forced either way. ELIZA_SERVER_AUTH_TOKEN is the one to read carefully, because when it is set, all /api/* routes require an X-API-KEY header with that value. Leaving it empty is the default, and that default exposes the API to anything that can reach the port.

```bash
SERVER_PORT=3000
ELIZA_SERVER_AUTH_TOKEN=
POSTGRES_URL=
PGLITE_DATA_DIR=
OPENAI_API_KEY=
```

Storage has two paths. POSTGRES_URL points at a PostgreSQL instance, while PGLITE_DATA_DIR selects PGLite, with memory:// for an in-memory database. Provider keys are separate variables: OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, ANTHROPIC_API_KEY, and OPENROUTER_API_KEY. The .env.example notes that Anthropic and OpenRouter require an embedding provider and will default to local embedding if one is not supplied. PROVIDERS_TOTAL_TIMEOUT_MS defaults to 1000, and the comment states that when providers exceed it the pipeline aborts and returns an error message. One second is aggressive for anything that touches the network, so this is the first value to raise when providers start disappearing from responses.

## Where the documentation runs out

The install path is well described. The operational path is not. The README does not document rollback, and the postinstall script patches nested package distributions, a punycode deprecation, llama-cpp-capacitor, and an Electrobun Linux CEF profile. Those patches live in patches/ and are applied during installation, but nothing in the top-level README explains how to revert them or what breaks if you skip them. On a machine where you cannot mutate dependency trees, that is a real constraint.

The release channel is the second gap. The recent releases listed for the repository are named pr-evidence-11, pr-evidence-10, and pr-evidence-9, with descriptions referencing PR #26518 and an internal CI evidence asset store. These read as CI artifacts rather than user-facing versioned releases, and the package.json version is 2.0.4 while the CLI is published as elizaos@beta. The README points users at GitHub releases for the app, but it does not describe a stable, tagged library release line for the framework itself. If your process requires pinned, semantic versions of @elizaos/core, verify that such a line exists before planning around it.

Third, the capability lists are deliberately vague. The README says availability depends on operating system, plugins, permissions, and providers, and that package-level READMEs carry the specifics. That is honest, but it means the top-level document cannot tell you whether wallet operations or native device bridges work on your target. You have to read the nearest package guide, and the repository expects that: it states that every maintained package or plugin should explain its public surface, scripts, configuration, and local constraints in its own README.md and paired CLAUDE.md or AGENTS.md.

## When elizaOS is the wrong choice, and what to use instead

If you need a single agent with a tool loop and nothing else, elizaOS is heavier than the problem. The monorepo ships a UI package, an app host, cloud service code, native bridges, and a CLI, and the install runs a postinstall chain that builds workspace packages and patches dependencies. A minimal Python or TypeScript agent loop with a provider SDK will be easier to audit and faster to deploy.

A concrete alternative in the same language is the Vercel AI SDK. The difference in approach is structural rather than cosmetic. The AI SDK gives you primitives for model calls, streaming, and tool invocation, and you compose them inside your own application; there is no runtime that owns the message loop, no plugin contract that registers routes and views, and no opinion about memory or state. elizaOS inverts that: AgentRuntime owns the loop, memory and state primitives live in @elizaos/core, and capabilities arrive as plugins that can extend the interface as well as the model. Choose the AI SDK when the agent is a feature of your app. Choose elizaOS when the agent is the host and your features are plugins.

The second case where elizaOS is wrong is any environment that requires a documented, stable release artifact. The README's own instructions point at the develop branch for source builds, and the CLI is explicitly beta. If you cannot track a moving branch, wait.

## Maintenance, upgrade cost, and the MIT licence

The repository is not archived, and the last push was on 2026-08-23. The recent release entries are CI evidence artifacts tied to pull requests rather than a versioned changelog, so upgrade planning has to come from the branch itself.

The upgrade cost is dominated by the postinstall chain rather than by API churn. Every install runs eight scripted steps, several of which patch third-party packages. When an upstream dependency changes shape, those patches are the first thing to break, and the failure surfaces during bun install rather than at runtime. The repository does provide gates for this: bun run verify runs package parity, dependency, type, lint, and audit checks, and fix-deps:check validates workspace dependencies without writing, with fix-deps and fix-deps:restore to apply or revert. Running verify before upgrading is the cheapest signal available.

The licence is MIT, which permits commercial use, modification, and redistribution with the copyright notice and permission notice preserved. Note that the licence covers this repository; the bootable Linux and Android distributions live in elizaOS/os, and Eliza Cloud is a separate hosted service with its own terms. Nothing here is legal advice, and the wallet features deserve their own review, since the README describes them as non-custodial with approval boundaries and the exact boundary semantics are documented at package level.

## Conclusion

Adopt elizaOS if you want a TypeScript runtime where agents, plugins, and installable app views share one message loop, and you are willing to run from the develop branch with Bun. Do not adopt it if you need a stable tagged release channel, a documented rollback path, or a small dependency surface; the postinstall step patches nested packages and builds private workspace packages, and the README does not describe how to undo any of it. Before committing, verify three things yourself: which Bun and Node versions package.json actually pins, whether your target platform has a first-party plugin or only a native bridge, and whether the CLI you install is the unscoped elizaos@beta package rather than something older.

## FAQ

### What is elizaOS/eliza?

It is an open source TypeScript framework and product stack for autonomous AI agents, described in its README as an agentic operating system. The monorepo contains the core runtime, the Eliza app, the CLI, cloud services, native bridges, and first-party plugins.

### How do I install and run elizaOS from source?

Install the Bun and Node versions pinned in package.json, then clone the repository, run bun install, and run bun run dev. The README notes that bun install also prepares submodules and patches.

### Does elizaOS run models locally?

The @elizaos/plugin-local-inference package provides the Eliza-1 on-device path, with 2B, 4B, 9B, and 27B text tiers based on Gemma 4 plus local embeddings, speech, vision, and image-generation assets. The README states that local inference is not forced on hardware that cannot support it, and that Eliza can route each capability to local, direct-provider, or Eliza Cloud backends.

### Is Eliza Cloud required to use elizaOS?

No. The README states that Eliza Cloud is optional and that the local runtime and direct model-provider configuration remain first-class paths. Cloud provides account and authentication services, hosted model routing, deployment, and cross-device services.

## Sources

- [Official documentation](https://elizaos.ai/)
- [Official README](https://github.com/elizaOS/eliza#readme)
- [Project repository](https://github.com/elizaOS/eliza)
- [Release notes](https://github.com/elizaOS/eliza/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/elizaos-eliza