elizaOS
Getting Started

Configuration

Complete configuration guide for ElizaOS v1.2.0

This guide covers comprehensive configuration for ElizaOS v1.2.0, including environment setup, development workflows, project types, and best practices.

ElizaOS v1.2.0 introduces enhanced configuration management with interactive tools, improved environment handling, and streamlined development workflows.

Environment Configuration

Interactive Environment Setup

The easiest way to configure your ElizaOS environment is through the interactive CLI:

# Interactive environment configuration (recommended)
elizaos env interactive

# Edit local environment variables
elizaos env edit-local

# List all environment variables
elizaos env list

# Check environment health
elizaos env check

Manual Environment Setup

Create Environment File

# Copy example environment file
cp .env.example .env

# Edit with your preferred editor
nano .env

Core Configuration

Add essential configuration variables:

# Required: Choose at least one Model Provider API Key
OPENAI_API_KEY=your_openai_key_here
ANTHROPIC_API_KEY=your_anthropic_key_here  # Requires embedding provider
GOOGLE_GENERATIVE_AI_API_KEY=your_google_key_here
OPENROUTER_API_KEY=your_openrouter_key_here  # Requires embedding provider
GROQ_API_KEY=your_groq_key_here
OLLAMA_API_ENDPOINT=http://localhost:11434  # For local AI

# Database Configuration (choose one)
POSTGRES_URL=postgresql://user:password@localhost:5432/eliza
PGLITE_DATA_DIR=./data/pglite  # Lightweight alternative

# Server Configuration
SERVER_PORT=3000
SERVER_HOST=localhost
NODE_ENV=development
EXPRESS_MAX_PAYLOAD=2mb

Validate Configuration

# Test database connection
elizaos env test-db

# Test API keys
elizaos env test-keys

# Check overall health
elizaos env check

Project Types

ElizaOS v1.2.0 supports four distinct project types:

Project Type Selection

Full ElizaOS Application - Complete agent framework with all features - Web interface and API endpoints - Database integration and persistence - Plugin system support - Multi-platform connections bash elizaos create my-agent --type project Use when: Building a complete AI agent application

Plugin Development - Extend ElizaOS with custom functionality - Reusable components for the community - Action, provider, and evaluator development - Testing and publishing support bash elizaos create my-plugin --type plugin Use when: Creating extensions for ElizaOS

Agent Character Definition - Standalone character JSON files - Personality and behavior configuration - Quick agent prototyping - Simple deployment scenarios bash elizaos create my-character --type agent Use when: Defining agent personalities and behaviors

Trusted Execution Environment - Secure, decentralized agent deployment - Blockchain integration support - Privacy-preserving computations - Distributed agent networks bash elizaos create my-tee-agent --type tee Use when: Deploying secure, decentralized agents

Project Structure

Each project type has its own structure:

my-agent/
├── .env                # Environment variables
├── .env.example        # Environment template
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
├── characters/         # Agent character definitions
│   └── default.json    # Default character
├── knowledge/          # Knowledge base files
├── src/                # Source code
│   ├── index.ts        # Main entry point
│   └── plugins/        # Custom plugins
├── tests/              # Test files
└── docs/               # Documentation
plugin-my-plugin/
├── package.json        # Plugin metadata
├── tsconfig.json       # TypeScript configuration
├── src/
│   ├── index.ts        # Plugin entry point
│   ├── actions/        # Custom actions
│   ├── providers/      # Custom providers
│   └── evaluators/     # Custom evaluators
├── tests/              # Plugin tests
├── examples/           # Usage examples
└── README.md           # Plugin documentation
my-character/
├── character.json      # Agent definition
├── knowledge/          # Knowledge files
├── prompts/            # Custom prompts
└── config/             # Configuration files

Development Workflow

Development Commands

# Start development server with hot-reload
elizaos dev

# Start with specific character

elizaos dev --character characters/my-agent.json

# Start with build

elizaos dev --build

# Start on custom port

elizaos dev --port 8080

# Reconfigure services

elizaos dev --configure

Development Features: - Hot-reload on file changes - Detailed logging and debugging - Live configuration updates - Real-time error reporting

# Run all tests
elizaos test

# Run component tests
elizaos test component

# Run end-to-end tests
elizaos test e2e

# Run tests with coverage
elizaos test --coverage

# Run specific test file
elizaos test --file my-test.spec.ts

Testing Features: - Unit and integration tests - Component testing framework - End-to-end testing support - Coverage reporting

# Build for production
elizaos start --build

# Start production server
elizaos start

# Background process
nohup elizaos start > elizaos.log 2>&1 &

# With environment file
elizaos start --env production

Deployment Features: - Production optimizations - Environment-specific configs - Background process support - Logging and monitoring

Plugin Management

Plugin Commands

# List available plugins
elizaos plugins list

# List installed plugins
elizaos plugins installed-plugins

# Add a plugin
elizaos plugins add @elizaos/plugin-discord

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

# Update plugins
elizaos update --packages

Discord Plugin

Connect your agent to Discord servers

Telegram Plugin

Enable Telegram bot functionality

Twitter Plugin

Integrate with Twitter/X platform

OpenAI Plugin

Enhanced OpenAI model integration

Plugin Selection Guide

Platform Integrations - @elizaos/plugin-discord - Discord bot functionality - @elizaos/plugin-telegram - Telegram integration - @elizaos/plugin-twitter - Twitter/X platform - @elizaos/plugin-slack - Slack workspace integration When to use: Connect your agent to messaging platforms

Model Providers - @elizaos/plugin-openai - OpenAI models (GPT-4, etc.) - @elizaos/plugin-anthropic - Claude models - @elizaos/plugin-google - Google AI models - @elizaos/plugin-ollama - Local model support When to use: Integrate different AI model providers

Blockchain Integrations - @elizaos/plugin-ethereum - Ethereum blockchain - @elizaos/plugin-solana - Solana blockchain - @elizaos/plugin-defi - DeFi protocols - @elizaos/plugin-nft - NFT marketplace integration When to use: Build blockchain-enabled agents

Utility Plugins - @elizaos/plugin-image - Image generation and processing - @elizaos/plugin-search - Web search capabilities - @elizaos/plugin-calendar - Calendar and scheduling - @elizaos/plugin-files - File system operations When to use: Add specific functionality to your agent

Environment Variables Reference

Core Variables

# Model Provider (choose at least one)
OPENAI_API_KEY=your_openai_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
GROQ_API_KEY=your_groq_key_here
OLLAMA_API_ENDPOINT=http://localhost:11434

# Database Configuration (choose one)
POSTGRES_URL=postgresql://user:password@localhost:5432/eliza
PGLITE_DATA_DIR=./data/pglite

# Server Configuration
SERVER_PORT=3000
SERVER_HOST=localhost
NODE_ENV=development
EXPRESS_MAX_PAYLOAD=2mb

# Logging Configuration
LOG_LEVEL=info  # Options: fatal, error, warn, info, debug, trace
LOG_DIAGNOSTIC=false
QUIET_MODE=false

# UI Configuration
ELIZA_UI_ENABLE=true  # Auto-enabled in dev, disabled in prod
ELIZA_SERVER_AUTH_TOKEN=your_auth_token_here

# Character Configuration
REMOTE_CHARACTER_URLS=  # Comma-separated URLs

# Security
SECRET_SALT=your_secret_salt_here  # For encryption

# CLI Configuration
ELIZA_NONINTERACTIVE=false  # Disable interactive features
SKIP_POSTINSTALL=0  # Skip git submodule init
IGNORE_BOOTSTRAP=  # Skip bootstrap plugin (not recommended)

Additional Service Configuration

# Voice Services (Eleven Labs)
ELEVENLABS_API_KEY=your_elevenlabs_key_here
ELEVENLABS_VOICE_ID=your_voice_id_here

# Monitoring (Sentry)
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

# Branch Configuration (for deployment)
ELIZA_BRANCH=main

Platform Integration Variables

# Discord Configuration
DISCORD_APPLICATION_ID=your_discord_app_id
DISCORD_API_TOKEN=your_discord_bot_token
DISCORD_ENABLE_SLASH_COMMANDS=true
DISCORD_ENABLE_VOICE=false
# Telegram Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_ENABLE_GROUPS=true
TELEGRAM_WEBHOOK_URL=https://your-domain.com/webhook
# Twitter Configuration (choose one method)
# Method 1: Username/Password
TWITTER_USERNAME=your_twitter_username
TWITTER_PASSWORD=your_twitter_password
TWITTER_EMAIL=your_twitter_email

# Method 2: API Keys
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

# Common settings
TWITTER_ENABLE_POST_GENERATION=true
TWITTER_POST_IMMEDIATELY=false
# Ethereum Configuration
EVM_PRIVATE_KEY=your_ethereum_private_key
EVM_PROVIDER_URL=https://mainnet.infura.io/v3/your_key
EVM_CHAINS=mainnet,sepolia,base,arbitrum,polygon

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

# TEE Configuration
TEE_MODE=LOCAL  # Options: LOCAL, DOCKER, PRODUCTION
WALLET_SECRET_SALT=your_wallet_secret_salt_here

Best Practices

Environment Setup

Use Environment Templates

Start with the provided .env.example file:

cp .env.example .env

Secure API Keys

Never commit API keys to version control:

# Add to .gitignore
echo ".env" >> .gitignore
echo ".env.local" >> .gitignore

Use Environment-Specific Files

Create separate environment files:

.env.development
.env.staging
.env.production

Validate Configuration

Regularly check your configuration:

elizaos env check

Development Workflow

  1. Start with Interactive Setup: Use elizaos env interactive for initial configuration
  2. Use Development Mode: Run elizaos dev for active development
  3. Test Regularly: Use elizaos test to catch issues early
  4. Keep Updated: Run elizaos update --check regularly
  5. Monitor Logs: Use appropriate LOG_LEVEL settings

Plugin Management

  1. Choose Carefully: Only install plugins you need
  2. Keep Updated: Update plugins with elizaos update --packages
  3. Test Compatibility: Test plugins after updates
  4. Monitor Performance: Remove unused plugins

Common Workflows

Setting Up a New Agent

Create Project

elizaos create my-agent --type project
cd my-agent

Configure Environment

elizaos env interactive

Add Required Plugins

elizaos plugins add @elizaos/plugin-discord
elizaos plugins add @elizaos/plugin-openai

Start Development

elizaos dev

Test and Deploy

elizaos test
elizaos start --build

Plugin Development

Create Plugin

elizaos create my-plugin --type plugin
cd plugin-my-plugin

Develop Plugin

elizaos dev

Test Plugin

elizaos test

Publish Plugin

elizaos publish

Troubleshooting

Common Configuration Issues

API Key Issues

# Check if API key is loaded
elizaos env list | grep OPENAI_API_KEY

# Test API key validity
elizaos env test-keys

# Common issues:
# - Extra spaces or quotes in .env
# - Wrong API key format
# - Insufficient API credits

Environment Loading Issues

# Check .env file format
cat .env | head -5

# Test environment loading
node -e "console.log(process.env.OPENAI_API_KEY)"

# Reset environment
elizaos env reset

Database Connection Issues

# Test database connection
elizaos env test-db

# Check database URL
elizaos env list | grep POSTGRES_URL

# Switch to PGLite for development
echo "PGLITE_DATA_DIR=./data/pglite" >> .env

Database Migration Issues

# Reset database
rm -rf ./data/pglite

# Recreate database
elizaos start --build

Plugin Installation Issues

# List installed plugins
elizaos plugins installed-plugins

# Remove problematic plugin
elizaos plugins remove @elizaos/plugin-name

# Update all plugins
elizaos update --packages

Plugin Compatibility Issues

# Check plugin versions
elizaos plugins list --all

# Install specific version
elizaos plugins add @elizaos/plugin-name@1.2.0

CLI Issues

# Update CLI
bun update -g @elizaos/cli

# Check CLI version
elizaos --version

# Get help
elizaos --help

Permission Issues

# Fix permissions
sudo chown -R $(whoami) ~/.bun

# Or use sudo for global install
sudo bun install -g @elizaos/cli

Getting Help

Need help with configuration? Use these resources:

Next Steps

Core Concepts

Learn about ElizaOS architecture and concepts

Plugin Development

Build your own plugins for ElizaOS

Advanced Features

Explore advanced ElizaOS features

Deployment

Deploy your agents to production

Configuration complete! Your ElizaOS v1.2.0 environment is ready for development.

Quickstart

Create your first agent in minutes

Learning Tracks

Structured learning paths for ElizaOS development