Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js 23+

Required for running elizaOS projects

bun

Fast JavaScript runtime and package manager
Windows Users: WSL 2 (Windows Subsystem for Linux) is required. elizaOS runs on Linux and macOS natively. Install WSL 2 before proceeding.

​
Step 1: Install Node.js

elizaOS requires Node.js version 23.3.0 or higher.
1

Check if Node.js is installed

Open your terminal and run:
node --version
If you see v23.3.0 or higher, you’re good to go. Otherwise, continue to the next step.
2

Install Node.js

Download and install Node.js from the official website:
Using Homebrew:
brew install node@23
Or download the installer from nodejs.org
3

Verify installation

node --version
npm --version
You should see version numbers for both commands.

​
Step 2: Install bun

bun is a fast JavaScript runtime and package manager that elizaOS uses for development and package management.
1

Install bun

Run the official installation script:
curl -fsSL https://bun.sh/install | bash
The script will install bun and add it to your PATH.
2

Restart your terminal

Close and reopen your terminal to ensure bun is available in your PATH.
3

Verify installation

bun --version
You should see a version number (elizaOS uses bun 1.3.5 or higher).

​
Step 3: Install elizaOS

You have two options for getting started with elizaOS:
Clone the entire elizaOS repository to access all packages, plugins, and examples:
1

Clone the repo

git clone https://github.com/elizaos/eliza.git
cd eliza
2

Install dependencies

bun install
This will install all dependencies for the monorepo.
3

Build the project

bun run build
This compiles all TypeScript packages and prepares them for use.
This option is recommended if you want to:
  • Explore example projects
  • Contribute to elizaOS
  • Access all plugins and packages
  • Run the development environment

​
Step 4: Configure Environment Variables

Create a .env file in your project root to configure API keys and settings:
1

Copy the example file

If you cloned the repository:
cp .env.example .env
2

Add your API keys

Open .env in your text editor and add at least one AI model provider:
.env
# OpenAI (recommended for getting started)
OPENAI_API_KEY=sk-your-key-here

# Or use other providers:
# ANTHROPIC_API_KEY=your-key-here
# GOOGLE_GENERATIVE_AI_API_KEY=your-key-here

# Or run locally with Ollama (no API key needed)
# OLLAMA_API_ENDPOINT=http://localhost:11434
Never commit your .env file to version control. Add it to .gitignore!
3

Optional: Configure database

By default, elizaOS uses an in-memory database. For persistence, configure PostgreSQL:
.env
# PostgreSQL connection URL
POSTGRES_URL=postgresql://user:password@localhost:5432/eliza

# Or use PGLite for a lightweight option
PGLITE_DATA_DIR=./.eliza/.elizadb

​
Step 5: Verify Installation

Let’s verify everything is working correctly: 
# From the eliza directory
bun run build
echo "Installation complete!"
If you see no errors, congratulations! You’re ready to build your first agent.

​
Next Steps

Quick Start

Build your first AI agent in 5 minutes

What You Can Build

Explore what’s possible with elizaOS

​
Troubleshooting

If you see an error about Node.js version:
# Use nvm to switch versions
nvm use 23

# Or set it as default
nvm alias default 23
If bun is not recognized after installation:
  1. Restart your terminal
  2. Check if bun is in your PATH: 
    echo $PATH | grep .bun
  3. Manually add to your shell config: 
    # For bash (~/.bashrc) or zsh (~/.zshrc)
export PATH="$HOME/.bun/bin:$PATH"
For Windows users having WSL 2 issues:
  1. Ensure WSL 2 is installed: wsl --version
  2. Update WSL: wsl --update
  3. Set WSL 2 as default: wsl --set-default-version 2
  4. Install Ubuntu: wsl --install -d Ubuntu
If you encounter build errors:
# Clean and rebuild
bun run clean
bun install
bun run build
Need more help? Join our Discord community or check the GitHub issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us