Skip to main content
Version: 1.0.10

Start Command

Start the Eliza agent with configurable plugins and services.

Usage​

elizaos start [options]

Options​

OptionDescription
-c, --configureForce reconfiguration of services and AI models (bypasses saved configuration)
--character [paths...]Character file(s) to use - accepts paths or URLs
--buildBuild the project before starting
--no-buildSkip the build step before starting
-p, --port <port>Port to listen on (default: 3000)
--quietSuppress all non-error output to the console

Project Detection​

ElizaOS automatically detects the type of directory you're in and adjusts its behavior accordingly:

  • ElizaOS Projects: Loads project configuration and starts defined agents
  • ElizaOS Plugins: Runs in plugin test mode with the default character
  • Other Directories: Uses the default Eliza character

Configuration Management​

Default Configuration​

  • Uses saved configuration from previous runs
  • Loads environment variables from .env file
  • Applies project-specific settings

Force Reconfiguration​

# Bypass saved configuration and reconfigure all services
elizaos start --configure

This is useful when:

  • You've changed API keys or service credentials
  • You want to select different AI models
  • Service configurations have changed
  • Troubleshooting configuration issues

Environment Variables​

The start command automatically loads environment variables:

From .env File​

# ElizaOS looks for .env in the project directory
cd my-project
elizaos start  # Loads from ./my-project/.env

Direct Environment Variables​

# Set variables directly
OPENAI_API_KEY=your-key elizaos start

# Multiple variables
OPENAI_API_KEY=key1 DISCORD_TOKEN=token1 elizaos start

Error Handling​

Character Loading Errors​

If character files fail to load, ElizaOS will:

  1. Log Errors: Display detailed error messages for each failed character
  2. Continue Starting: Use any successfully loaded characters
  3. Fallback: Use the default Eliza character if no characters load successfully

Service Connection Errors​

  • Automatic retry for transient connection issues
  • Graceful degradation when optional services are unavailable
  • Error logging with recovery suggestions

Port Management​

Default Port​

  • Default: 3000
  • Automatically detects if port is in use
  • Suggests alternative ports if default is unavailable

Custom Port​

# Specify custom port
elizaos start --port 8080

# Check if port is available first
netstat -an | grep :8080
elizaos start --port 8080

Build Process​

Automatic Building​

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

When to Use --build​

  • First deployment: Ensure all TypeScript is compiled
  • After code changes: Refresh compiled output
  • Production deployment: Guarantee latest build
  • Troubleshooting: Eliminate build-related issues

Health Checks​

# Verify service is running
curl http://localhost:3000/health

# Check process status
ps aux | grep elizaos

# Monitor logs
tail -f elizaos.log
  • create: Create a new project to start
  • dev: Run in development mode with hot reloading
  • agent: Manage individual agents
  • env: Configure environment variables
  • stop: Stop running agents