search

elizaOS / eliza

Autonomous agents for everyone
https://elizaOS.github.io/eliza/
MIT License
15.25k stars 4.96k forks source link

readme

Eliza 🤖

Eliza Banner
📑 [Technical Report](https://arxiv.org/pdf/2501.06781) | 📖 [Documentation](https://elizaos.github.io/eliza/) | 🎯 [Examples](https://github.com/thejoven/awesome-eliza)

🌍 README Translations

中文说明 | 日本語の説明 | 한국어 설명 | Persian | Français | Português | Türkçe | Русский | Español | Italiano | ไทย | Deutsch | Tiếng Việt | עִברִית | Tagalog | Polski | Arabic | Hungarian | Srpski | Română | Nederlands | Ελληνικά

🚩 Overview

Eliza Diagram

✨ Features

Video Tutorials

AI Agent Dev School

🎯 Use Cases

🚀 Quick Start

Prerequisites

Note for Windows Users: WSL 2 is required.

Use the Starter (Recommended for Agent Creation)

Full steps and documentation can be found in the Eliza Starter Repository.

git clone https://github.com/elizaos/eliza-starter.git
cd eliza-starter
cp .env.example .env
pnpm i && pnpm build && pnpm start

Manually Start Eliza (Only recommended for plugin or platform development)

Checkout the latest release

# Clone the repository
git clone https://github.com/elizaos/eliza.git

# This project iterates fast, so we recommend checking out the latest release
git checkout $(git describe --tags --abbrev=0)
# If the above doesn't checkout the latest release, this should work:
# git checkout $(git describe --tags `git rev-list --tags --max-count=1`)

If you would like the sample character files too, then run this:

# Download characters submodule from the character repos
git submodule update --init

Edit the .env file

Copy .env.example to .env and fill in the appropriate values.

cp .env.example .env

Note: .env is optional. If you're planning to run multiple distinct agents, you can pass secrets through the character JSON

Start Eliza

pnpm i
pnpm build
pnpm start

# The project iterates fast, sometimes you need to clean the project if you are coming back to the project
pnpm clean

Interact via Browser

Once the agent is running, you should see the message to run "pnpm start:client" at the end.

Open another terminal, move to the same directory, run the command below, then follow the URL to chat with your agent.

pnpm start:client

Then read the Documentation to learn how to customize your Eliza.

Automatically Start Eliza

The start script provides an automated way to set up and run Eliza:

sh scripts/start.sh

For detailed instructions on using the start script, including character management and troubleshooting, see our Start Script Guide.

Note: The start script handles all dependencies, environment setup, and character management automatically.

Modify Character

  1. Open packages/core/src/defaultCharacter.ts to modify the default character. Uncomment and edit.

  2. To load custom characters:

    • Use pnpm start --characters="path/to/your/character.json"
    • Multiple character files can be loaded simultaneously

  3. Connect with X (Twitter)

    • change "clients": [] to "clients": ["twitter"] in the character file to connect with X

Add more plugins

  1. run npx elizaos plugins list to get a list of available plugins or visit https://elizaos.github.io/registry/

  2. run npx elizaos plugins add @elizaos-plugins/plugin-NAME to install the plugin into your instance

Additional Requirements

You may need to install Sharp. If you see an error when starting up, try installing it with the following command:

pnpm install --include=optional sharp

Using Your Custom Plugins

Plugins that are not in the official registry for ElizaOS can be used as well. Here's how:

Installation

  1. Upload the custom plugin to the packages folder:
packages/
├─plugin-example/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts        # Main plugin entry
│   ├── actions/        # Custom actions
│   ├── providers/      # Data providers
│   ├── types.ts        # Type definitions
│   └── environment.ts  # Configuration
├── README.md
└── LICENSE
  1. Add the custom plugin to your project's dependencies in the agent's package.json:
{
  "dependencies": {
    "@elizaos/plugin-example": "workspace:*"
  }
}
  1. Import the custom plugin to your agent's character.json
  "plugins": [
    "@elizaos/plugin-example",
  ],

Start Eliza with Gitpod

Open in Gitpod

Deploy Eliza in one click

Use Fleek to deploy Eliza in one click. This opens Eliza to non-developers and provides the following options to build your agent:

  1. Start with a template
  2. Build characterfile from scratch
  3. Upload pre-made characterfile

Click here to get started!

Community & contact

Citation

We now have a paper you can cite for the Eliza OS:

@article{walters2025eliza,
  title={Eliza: A Web3 friendly AI Agent Operating System},
  author={Walters, Shaw and Gao, Sam and Nerd, Shakker and Da, Feng and Williams, Warren and Meng, Ting-Chien and Han, Hunter and He, Frank and Zhang, Allen and Wu, Ming and others},
  journal={arXiv preprint arXiv:2501.06781},
  year={2025}
}

Contributors

Eliza project contributors

Star History

Star History Chart

🛠️ System Requirements

Minimum Requirements

Software Requirements

Optional Requirements

📁 Project Structure

eliza/
├── packages/
│   ├── core/           # Core Eliza functionality
│   ├── clients/        # Client implementations
│   └── actions/        # Custom actions
├── docs/              # Documentation
├── scripts/           # Utility scripts
└── examples/          # Example implementations

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

  1. Fork the repository
  2. Create a new branch: git checkout -b feature/your-feature-name
  3. Make your changes
  4. Run tests: pnpm test
  5. Submit a pull request

Types of Contributions

Code Style