elizaOS
Getting Started

Installation

Complete guide to installing ElizaOS and setting up your development environment

Installation

This guide covers the complete installation process for ElizaOS, including system requirements, dependencies, and different installation methods.

ElizaOS v1.2.0 requires Node.js v23.3.0 (exact version) and Bun v1.2.15 or higher for optimal compatibility and performance.

System Requirements

Operating System

  • macOS: Works on both Intel and Apple Silicon Macs
  • Linux: Compatible with most distributions (Ubuntu 20.04+, CentOS 8+, Debian 11+)
  • Windows: Must be installed within WSL 2, not native Windows

Hardware Requirements

  • Memory: Minimum 4GB RAM (8GB+ recommended)
  • Storage: At least 2GB free disk space
  • CPU: Modern multi-core processor recommended

Network Requirements

  • Internet connection for package installation
  • Access to npm/GitHub registries
  • Firewall permissions for API access (if using external LLMs)

Prerequisites

Install Node.js

Using Homebrew (Recommended):

# Install Node.js 23.3.0
brew install node@23
brew link node@23 --force --overwrite

# Verify installation
node --version  # Should show v23.3.0

Using Node Version Manager (nvm):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install and use Node.js 23.3.0
nvm install 23.3.0
nvm use 23.3.0
nvm alias default 23.3.0

# Verify installation
node --version  # Should show v23.3.0

Using Node Version Manager (nvm) - Recommended:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install and use Node.js 23.3.0
nvm install 23.3.0
nvm use 23.3.0
nvm alias default 23.3.0

# Verify installation
node --version  # Should show v23.3.0

Using Package Managers:

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_23.x | sudo -E bash -
sudo apt-get install -y nodejs

# CentOS/RHEL/Fedora
curl -fsSL https://rpm.nodesource.com/setup_23.x | sudo bash -
sudo yum install -y nodejs

# Arch Linux
sudo pacman -S nodejs npm

Install WSL 2 first (Required):

# Run in PowerShell as Administrator
wsl --install

Inside WSL 2 (Ubuntu):

# Update packages
sudo apt update && sudo apt upgrade

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install Node.js 23.3.0
nvm install 23.3.0
nvm use 23.3.0
nvm alias default 23.3.0

# Verify installation
node --version  # Should show v23.3.0

Install Bun

Using Homebrew (Recommended):

brew install oven-sh/bun/bun

# Verify installation
bun --version  # Should show v1.2.15

Using the official installer:

curl -fsSL https://bun.sh/install | bash

# Verify installation
bun --version  # Should show v1.2.15

Using the official installer:

curl -fsSL https://bun.sh/install | bash

# Verify installation
bun --version  # Should show v1.2.15

Note: After installation, you may need to add Bun to your PATH:

echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Inside WSL 2 (Ubuntu):

curl -fsSL https://bun.sh/install | bash

# Add to PATH
echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
bun --version  # Should show v1.2.15

Platform Notes:

  • macOS: Works on both Intel and Apple Silicon Macs
  • Linux: Compatible with most distributions
  • Windows: Must be installed within WSL 2, not native Windows
  • Alternative: You can use npm instead of bun, but bun is recommended for better performance

Verify Installation

Check that all dependencies are correctly installed:

# Check Node.js version
node --version  # Should be v23.3.0 (exact version required)

# Check Bun version
bun --version   # Should be v1.2.15 (recommended)

Ensure you have the exact Node.js version v23.3.0 installed. Other versions may cause compatibility issues with ElizaOS.

Installation Methods

This is the fastest way to get started with ElizaOS v1.2.0. The CLI handles most configuration automatically and provides enhanced project management features.

The CLI provides the fastest way to get started:

# Install the CLI globally
bun install -g @elizaos/cli

# Verify installation
elizaos --version

# Create your first project (interactive mode)
elizaos create

# Or specify project type directly
elizaos create my-agent --type project

New CLI Features in v1.2.0:

  • Interactive project creation wizard
  • Multiple project types: project, plugin, agent, tee
  • Automatic dependency installation
  • Environment configuration assistance
  • Plugin discovery and management
  • Enhanced testing framework
  • Build and deployment automation

Method 2: Manual Installation

For more control over the setup process:

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

# Install dependencies
bun install

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your configuration

# Start the development server
bun dev

Method 3: Docker Installation

Docker provides a consistent environment across different platforms and simplifies deployment.

Prerequisites:

  • Docker Engine 20.10+ (24.0+ recommended)
  • Docker Compose 2.0+ (2.20+ recommended)
# Clone the repository
git clone https://github.com/elizaos/eliza.git
cd eliza

# Copy environment configuration
cp .env.example .env
# Edit .env with your configuration

# Build and start containers
docker-compose up -d

# View logs
docker-compose logs -f

# Stop containers
docker-compose down

Docker Verification:

# Check Docker version
docker --version      # Should be 20.10+

# Check Docker Compose version
docker compose version  # Should be 2.0+

Environment Configuration

Create a .env file in your project root with the following configuration:

Core Environment Variables

# Node environment
NODE_ENV=development

# Postinstall behavior
# Set to 1 to skip git submodule initialization during install
SKIP_POSTINSTALL=0

# Non-interactive mode
# Set to true to disable interactive CLI features
ELIZA_NONINTERACTIVE=false

# Bootstrap behavior
# Set to any value to skip bootstrap plugin (not recommended)
IGNORE_BOOTSTRAP=

# UI Configuration
# Controls whether the web UI is available
# Set to "true" to force enable, "false" to force disable, or leave unset for automatic behavior
# Default: enabled in development, disabled in production
ELIZA_UI_ENABLE=

# Character configuration
# URLs to load remote character files from (comma separated)
REMOTE_CHARACTER_URLS=

# Quiet mode
# Set to true to suppress non-error output
QUIET_MODE=false

Model Provider Configuration

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here

# Anthropic Configuration
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Groq Configuration
GROQ_API_KEY=your_groq_api_key_here

# Google AI Configuration
GOOGLE_GENERATIVE_AI_API_KEY=your_google_ai_api_key_here

# Eleven Labs (Voice)
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here
ELEVENLABS_VOICE_ID=your_voice_id_here

# Local AI Configuration (Ollama)
OLLAMA_API_ENDPOINT=http://localhost:11434
OLLAMA_MODEL=llama2

# OpenRouter Configuration (requires embedding provider)
OPENROUTER_API_KEY=your_openrouter_api_key_here

Database Configuration

# PostgreSQL (recommended for production)
POSTGRES_URL=postgresql://user:password@localhost:5432/eliza

# PGLite Database Directory (or use memory:// for in-memory)
# Alternative to PostgreSQL, lightweight and good for development
PGLITE_DATA_DIR=./data/pglite

Server Configuration

# Server settings
SERVER_PORT=3000
SERVER_HOST=0.0.0.0
NODE_ENV=development

# Server authentication token for API access
# When set, all /api/* routes require X-API-KEY header with this value
ELIZA_SERVER_AUTH_TOKEN=your_auth_token_here

# Express Maximum Payload Size (default: 2mb)
EXPRESS_MAX_PAYLOAD=2mb

Logging Configuration

# Logging level (fatal, error, warn, info, debug, trace)
LOG_LEVEL=info

# Diagnostic logging
LOG_DIAGNOSTIC=false

# Sentry configuration (optional)
SENTRY_LOGGING=false  # Set to true to enable
SENTRY_DSN=your_sentry_dsn_here
SENTRY_ENVIRONMENT=development
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_SEND_DEFAULT_PII=false

# Security configuration
SECRET_SALT=your_secret_salt_here  # Used for encryption

Platform Integration Variables

Discord Integration

DISCORD_APPLICATION_ID=your_discord_app_id
DISCORD_API_TOKEN=your_discord_bot_token

Telegram Integration

TELEGRAM_BOT_TOKEN=your_telegram_bot_token

Twitter Integration

TWITTER_USERNAME=your_twitter_username
TWITTER_PASSWORD=your_twitter_password
TWITTER_EMAIL=your_twitter_email
TWITTER_ENABLE_POST_GENERATION=true
TWITTER_POST_IMMEDIATELY=false

# Alternative Twitter API configuration
TWITTER_API_KEY=your_twitter_api_key
TWITTER_API_SECRET_KEY=your_twitter_api_secret_key
TWITTER_ACCESS_TOKEN=your_twitter_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_twitter_access_token_secret

Blockchain Integration

# Ethereum/EVM Configuration
EVM_PRIVATE_KEY=your_evm_private_key
EVM_CHAINS=mainnet,sepolia,base,arbitrum,polygon
EVM_PROVIDER_URL=your_rpc_url

# Solana Configuration
SOLANA_PRIVATE_KEY=your_solana_private_key
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

# TEE (Trusted Execution Environment) Configuration
TEE_MODE=LOCAL  # or DOCKER, PRODUCTION
WALLET_SECRET_SALT=your_wallet_secret_salt_here

Health Checks

After installation, run these health checks to ensure everything is set up correctly:

# Check CLI installation
elizaos --version

# Check environment variables
elizaos env list

# Test environment configuration
elizaos env interactive

# Verify database connection
elizaos env test-db

# Test API keys
elizaos env test-keys

Troubleshooting

Common Installation Issues

Platform-Specific Issues

Environment Variable Issues

Next Steps

Quick Start

Create your first ElizaOS agent in minutes

Configuration

Learn about advanced configuration options

Core Concepts

Understand the architecture and key concepts

Plugins

Explore available plugins and integrations

Quick Start Commands

Once installed, here are the most common commands to get started:

# Create a new project
elizaos create my-agent

# Start development mode
elizaos dev

# Run tests
elizaos test

# Start production server
elizaos start

# Get help
elizaos --help

Congratulations! You've successfully installed ElizaOS. Head to the Quick Start guide to create your first agent.

Getting Started

Get up and running with ElizaOS quickly and create your first AI agent

Quickstart

Create your first agent in minutes