Fun AI Lab

Most AI agent tools are prompt-chaining libraries wrapped around an API call. They send text back and forth, remember a few turns of conversation, and stop there.

elizaOS takes a fundamentally different path.

Rather than treating AI as a simple text completion tool, elizaOS builds an agentic operating system—a modular runtime designed to give autonomous agents direct access to memory, hardware, native operating system APIs, web services, and crypto wallets.

Whether you want to deploy a self-directed personal assistant on a local desktop, orchestrate coding agents, or run an autonomous agent directly on a dedicated bare-metal Linux machine, elizaOS provides the scaffolding to make it happen.

---

Why Agentic Operating Systems Matter

Building an AI agent that actually executes real work requires far more than connecting an LLM to a chat interface. Real-world execution demands:

1. Persistent State and Memory: Keeping track of goals, past interactions, documents, and environment changes across long execution spans.
2. Device and Environment Bridges: Reaching beyond the browser to access native device features like hardware controls, cameras, local file storage, and OS-level messaging.
3. Strict Execution Boundaries: Allowing agents to take real-world actions (such as sending messages or signing blockchain transactions) inside safe approval bounds.
4. Model Agnosticism: Switching between local models (via Ollama or Llama.cpp) and cloud providers (OpenAI, Anthropic) without rewriting your application logic.

elizaOS handles these infrastructure requirements at the framework layer. Instead of reinventing state management and API connections for every project, developers build on top of a unified runtime designed specifically for persistent, action-oriented software agents.

---

The Anatomy of elizaOS: Core Stack Breakdown

The elizaOS repository is structured as a TypeScript monorepo with clean separation between the core engine, application hosting layers, and user interfaces.

elizaos/eliza
├── packages/
│   ├── core/         # AgentRuntime, memory primitives, state machine, plugin contracts
│   ├── agent/        # Standalone agent runtime & HTTP backend server
│   ├── app-core/    # Shared app hosting, API orchestration, platform bridges
│   ├── ui/          # React interface components for web, mobile, and desktop
│   └── elizaos/     # Scaffolding, management, and deployment CLI

1. @elizaos/core

The kernel of the entire system. It defines the AgentRuntime, manages the core message loop, handles vector/relational memory primitives, and enforces plugin contracts. It does not care where the agent runs—only how the agent processes inputs, evaluates context, and triggers actions.

2. @elizaos/agent

A standalone HTTP backend server that wraps @elizaos/core. This component allows agents to run as headless daemons capable of receiving webhooks, background events, and remote commands.

3. Native Bridges & Device Controls

Through native platform connectors, elizaOS agents can access camera hardware, location services, contacts, system notifications, and desktop browser engines.

4. Non-Custodial Web3 Execution

elizaOS natively supports EVM and Solana wallet interfaces. Agents can query on-chain balances, compose smart contract interactions, and trigger crypto operations within strict, pre-configured permission and approval boundaries.

5. elizaOS/os (Bare-Metal Engine)

For applications requiring direct hardware control, the companion repository elizaOS/os offers bootable Linux and Android system images. This converts single-board computers or native hardware into standalone, physical AI devices.

---

Architecture Flow: How elizaOS Processes Input

The diagram below illustrates how an event moves through the elizaOS runtime—from user interfaces through memory state evaluation to physical or digital execution:

graph TD
    A[Input Signal: Web, Voice, Mobile, Webhook] --> B[app-core / HTTP Backend]
    B --> C[@elizaos/core AgentRuntime]

    subgraph Core Execution Engine
        C --> D[Memory & Knowledge Retrieval]
        C --> E[State Engine & Context Assembly]
        E --> F[Model Engine LLM/Local Provider]
    end

    F --> G{Action Evaluation}

    G -->|Native System| H[Device Bridge: Camera, Location, Storage]
    G -->|Web / API| I[Workspace & Web Connectors]
    G -->|Web3 Wallet| J[EVM / Solana Approval Gate]

    H --> K[Unified Response Loop]
    I --> K
    J --> K
    K --> L[Output / Feedback State]

---

Feature Matrix: elizaOS vs. Standard Agent Frameworks

To understand how elizaOS fits into the ecosystem, let’s look at how its native architecture compares to typical LLM wrapper frameworks:

Dimension	Standard Frameworks	elizaOS
Primary Focus	Prompt chaining & simple RAG pipelines	Full agentic execution, state management & hardware control
System Access	Restricted to standard API endpoints	Native OS bridges (Desktop, Mobile, Bootable ISO)
Runtime Environment	Python / Node script process	TypeScript monorepo, CLI, Web/Mobile clients, dedicated OS distros
Web3 Capabilities	Third-party community extensions	Native EVM & Solana non-custodial wallet operations with approval boundaries
Plugin Architecture	Custom tool definitions	Standardized TypeScript plugin contracts with state/action hooks

---

Quickstart: Running elizaOS from Source

Getting started with elizaOS requires Node.js and Bun. Follow these steps to clone, configure, and launch the repository locally.

1. Clone the Repository & Install Dependencies

# Clone the repository with blob filtering for faster setup
git clone --filter=blob:none https://github.com/elizaos/eliza.git
cd eliza

# Install workspace dependencies and initialize submodules
bun install

2. Launch Development Servers

# Start the local development environment
bun run dev

3. Useful Workspace Commands

# Build all internal packages with Turbo
bun run build

# Run linting, dependency, and type-checking verification gates
bun run verify

# Run unit and integration tests
bun run test

# Spin up a local mock instance of the Eliza Cloud stack
bun run cloud:mock

---

Creating Custom Capabilities with Plugins

Extending an elizaOS agent is straightforward thanks to its strict plugin contract. Every plugin exports a standard Plugin object that hooks into the core runtime.

Here is a minimalist example of defining a custom tool plugin in TypeScript:

import { Plugin, Action, AgentRuntime, Memory, State } from "@elizaos/core";

// Define a custom system monitoring action
const systemCheckAction: Action = {
    name: "CHECK_SYSTEM_HEALTH",
    similes: ["MONITOR_HEALTH", "CHECK_HARDWARE"],
    description: "Reports local system resource utilization.",
    validate: async (runtime: AgentRuntime, message: Memory) => {
        // Validation logic to decide if action can run
        return true;
    },
    handler: async (runtime: AgentRuntime, message: Memory, state?: State) => {
        // Core execution logic
        const memoryUsage = process.memoryUsage();
        const responseText = `System RAM in use: ${(memoryUsage.heapUsed / 1024 / 1024).toFixed(2)} MB`;

        return {
            text: responseText,
            actionStatus: "SUCCESS"
        };
    },
    examples: [
        [
            { user: "User", content: { text: "How is the system memory looking?" } },
            { user: "Agent", content: { text: "Checking memory stats now...", action: "CHECK_SYSTEM_HEALTH" } }
        ]
    ]
};

// Export the plugin package
export const systemMonitorPlugin: Plugin = {
    name: "system-monitor",
    description: "Monitors local runtime metrics",
    actions: [systemCheckAction],
    evaluators: [],
    providers: []
};

---

Real-World Use Cases

1. Persistent Executive Assistant

By combining calendar connectors, inbox monitoring, document workflows, and browser automation plugins, an elizaOS agent can summarize long email threads, schedule upcoming events, and draft routine responses autonomously.

2. Autonomous Web3 Agent

With non-custodial wallet interfaces built in, elizaOS agents can perform on-chain transaction checks, track token movements, and automatically execute pre-approved trading or staking strategies without leaking private key exposure.

3. Dedicated Hardware Appliances

Using the bootable elizaOS/os distribution, you can transform lightweight physical systems (like a Raspberry Pi or mini-PC) into dedicated hardware AI nodes. These appliances operate continuously in physical environments, handling camera inputs, voice queries, and IoT automation.

4. Automated Code & DevOps Workflows

elizaOS supports coding-agent orchestration. Developers can delegate multi-step code refactoring, pull request reviews, and continuous integration diagnostics directly to an internal background agent.

---

Common Pitfalls and Myths

Myth: “elizaOS is just a Web3 chat bot.”

Reality: While elizaOS contains robust crypto capabilities, it is a general-purpose agent runtime. You can run it completely offline with local LLMs and desktop automation plugins without touching blockchain networks.

Myth: “You must boot into a dedicated OS image to use it.”

Reality: You can run elizaOS as a lightweight CLI tool, a desktop React app, an npm package inside your existing Node backend, or a full bootable Linux image depending on your project needs.

Pitfall: Skipping Wallet Approval Boundaries

When deploying Web3 plugins, always enforce approval boundaries. Allowing an autonomous agent unfettered access to non-custodial wallets without maximum transaction caps or manual confirmation steps poses clear security risks.

Pitfall: Overloading Long-Term Memory

When building high-throughput background agents, ensure your vector database and memory state pruning parameters are configured correctly. Retaining raw chat logs without memory compression can degrade token optimization over long execution periods.

---

Actionable Tips for Developers

1. Start Small with the CLI: Use npx elizaos to scaffold new plugins rather than editing workspace core files directly.
2. Use Hybrid Models: Route fast pattern-matching tasks to local models (e.g., Llama-3-8B via Ollama) and reserve frontier APIs (Claude 3.5 Sonnet or GPT-4o) for complex decision-making steps to keep compute costs manageable.
3. Verify Code Parity: Always run bun run verify before opening pull requests to catch type mismatches, missing workspace dependencies, and broken package links early.

---

Building the Next Generation of AI Agents

The transition from simple prompt interfaces to fully autonomous systems requires open, flexible infrastructure. elizaOS provides the foundation required to bridge software models with real-world execution environments, offering developers full control over hardware interfaces, memory, and code plugins.

If you are building persistent assistants, background daemons, or dedicated physical AI hardware, explore the official repository, test out the plugins, and begin shaping the future of autonomous systems today.

📂 Explore the open-source repository on GitHub: https://github.com/elizaOS/eliza