Quickstart

Create your first AI agent in under 5 minutes with the ElizaOS CLI.

Prerequisites

Before you begin, ensure you have:

• Node.js (v23.3.0 exact version required)
• Bun package manager (v1.2.15 or higher)
• API Key from OpenAI, Anthropic, Google AI, or local AI setup (Ollama)
• Windows Users: WSL 2 required
• Database: PostgreSQL or PGLite (automatic with CLI)

Step 1: Install the CLI

Install the ElizaOS CLI globally:

bun install -g @elizaos/cli

Verify the installation:

elizaos --version

Step 2: Create Your First Agent

Create a new agent project using the interactive CLI:

# Interactive mode (recommended for beginners)
elizaos create

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

The CLI will prompt you to choose:

• Project Type: Select project (full ElizaOS application)
• Project Type: Select project (full ElizaOS application), plugin, agent, or tee
• Database: Select pglite (lightweight, no setup required) or postgres (production-ready)
• Model Provider: Select from local, openai, claude, openrouter, ollama, or google
• Embedding Model: Required for Claude and OpenRouter (select from local, openai, ollama, or google)

Step 3: Configure Your Agent

Navigate to your project directory:

cd my-first-agent

Set up your environment variables using the new v1.2.0 environment management:

# Interactive environment setup (recommended)
elizaos env interactive

# Or edit environment variables directly
elizaos env edit-local

# Or manually edit .env file
nano .env

Add your API key and basic configuration:

# Required: Choose one AI provider
OPENAI_API_KEY=your_api_key_here
# ANTHROPIC_API_KEY=your_anthropic_key_here
# GOOGLE_GENERATIVE_AI_API_KEY=your_google_key_here
# OPENROUTER_API_KEY=your_openrouter_key_here
# OLLAMA_API_ENDPOINT=http://localhost:11434  # For local AI

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

# Optional: Server configuration
SERVER_PORT=3000
SERVER_HOST=localhost
NODE_ENV=development

# Optional: Discord integration (if using Discord plugin)
DISCORD_APPLICATION_ID=your_discord_app_id
DISCORD_API_TOKEN=your_discord_bot_token

Step 4: Start Your Agent

Build and start your agent:

# Start in production mode
elizaos start

# Or start in development mode (with hot-reload)
elizaos dev

# Build before starting (recommended for first run)
elizaos start --build

Your agent will start and be available at:

• Web Interface: http://localhost:3000 (or your configured port)
• Console: Interactive chat in your terminal
• API: RESTful API endpoints for agent management

Step 5: Test Your Agent

1. Web Interface: Open your browser to http://localhost:3000
2. Start a conversation with your agent
3. Try different questions and commands
4. Observe responses and behavior

Testing Commands (New in v1.2.0)

# Run basic tests
elizaos test

# Run component tests
elizaos test component

# Run end-to-end tests
elizaos test e2e

# Check environment configuration
elizaos env list

Next Steps

Now that your agent is running, you can:

Development Workflow

Basic Development Commands

# Start development server with hot-reload
elizaos dev

# Start with specific character files
elizaos dev --character characters/my-agent.json

# Build and test your changes
elizaos test
elizaos test component  # Run only component tests
elizaos test e2e       # Run only end-to-end tests

# Update CLI and dependencies
elizaos update
elizaos update --check  # Check for updates without installing

Plugin Management

# List available plugins
elizaos plugins list

# Add a plugin to your project
elizaos plugins add @elizaos/plugin-discord

# Remove a plugin
elizaos plugins remove @elizaos/plugin-discord

Troubleshooting

Common Issues

Agent won't start?

• Verify your API key is correctly set: elizaos env list
• Check that Node.js v23.3.0 (exact version) is installed: node --version
• Ensure port 3000 is available or use --port option: elizaos dev --port 8080
• Try building first: elizaos start --build
• Check database connection: elizaos env test-db

Agent not responding?

• Check the console for error messages
• Verify your API key is valid and has credits
• Try restarting with elizaos start --configure
• Check database connection: elizaos env test-db

CLI or dependency issues?

• Update the CLI: bun update -g @elizaos/cli
• Check for updates: elizaos update --check
• Reinstall dependencies: bun install

Plugin problems?

• List available plugins: elizaos plugins list
• List installed plugins: elizaos plugins installed-plugins
• Remove problematic plugin: elizaos plugins remove <plugin-name>
• Check plugin compatibility with v1.2.0
• Verify plugin order (sql must be first, bootstrap must be last)

Getting Help

• Environment Check: elizaos env check
• CLI Help: elizaos --help or elizaos <command> --help
• Troubleshooting Guide: Check our comprehensive guide
• Community: Join the Discord community
• FAQ: Review frequently asked questions

Congratulations! You've successfully created your first AI agent with ElizaOS v1.2.0.

What You've Accomplished

• Installed the ElizaOS CLI
• Created a new agent project
• Configured environment variables
• Started your first agent
• Tested basic functionality

Ready for More?

Explore the configuration guide to learn about advanced features, or dive into plugin development to extend your agent's capabilities.