This document describes the server configuration environment variables for ElizaOS.

​
Server Security & Authentication

​
ELIZA_SERVER_AUTH_TOKEN

Controls API authentication for the ElizaOS server.
.env
ELIZA_SERVER_AUTH_TOKEN=your-secret-token
How it works:
  • Set this as your server’s required API key
  • External apps must send X-API-KEY: your-secret-token header when calling your /api/* endpoints
  • Server rejects requests with wrong/missing keys (401 Unauthorized)
  • Default: Unset (no authentication required)
  • Security: When unset, all API endpoints are publicly accessible
  • CORS: OPTIONS requests are always allowed for preflight
Example: 
# API call with authentication
curl -H "X-API-KEY: mysecrettoken123" \
     -H "Content-Type: application/json" \
     http://localhost:3000/api/agents

​
Web UI Control

​
ELIZA_UI_ENABLE

Controls whether the web user interface is served by the server.
  • Purpose: Enable or disable the web UI for security and deployment flexibility
  • Values:
    • true - Force enable UI
    • false - Force disable UI
  • Default Behavior:
    • Development (NODE_ENV=development): UI enabled
    • Production (NODE_ENV=production): UI disabled for security
  • Usage: 
    # Force enable in production
ELIZA_UI_ENABLE=true

# Force disable in development  
ELIZA_UI_ENABLE=false

# Use automatic behavior
ELIZA_UI_ENABLE=
  • Security: Disabling UI reduces attack surface by removing web interface
  • API Access: API endpoints remain available regardless of UI setting
When the UI is disabled, non-API routes return a 403 Forbidden response with a message explaining that the web UI is disabled. The dashboard URL is only shown on startup when the UI is enabled.

​
Environment Mode

​
NODE_ENV

Controls the application environment and affects various behaviors including default UI settings and security policies.
  • Values: development, production
  • Default: development
  • Effects:
    • CSP (Content Security Policy) configuration
    • Default UI enable/disable behavior
    • Error message verbosity
    • Debugging features availability

​
Examples

​
Production Deployment (Secure)

.env
NODE_ENV=production
ELIZA_SERVER_AUTH_TOKEN=secure-random-token-here
ELIZA_UI_ENABLE=false

​
Development Setup (Convenient)

.env
NODE_ENV=development
# ELIZA_SERVER_AUTH_TOKEN=  # Unset for easy development
# ELIZA_UI_ENABLE=         # Unset for automatic behavior (UI enabled)

​
Headless API Server

.env
ELIZA_SERVER_AUTH_TOKEN=api-only-token
ELIZA_UI_ENABLE=false

​
Public Web Application

.env
NODE_ENV=production
ELIZA_SERVER_AUTH_TOKEN=my-api-key
ELIZA_UI_ENABLE=true

​
Security Considerations

API Authentication: In production, always set ELIZA_SERVER_AUTH_TOKEN to prevent unauthorized access to your agent’s API endpoints.
  1. Default Security: In production mode with default settings:
    • Web UI is disabled
    • API endpoints are open (no authentication)
    • This prevents accidental exposure of the dashboard but leaves APIs accessible
  2. Recommended Production Setup:
    • Set ELIZA_SERVER_AUTH_TOKEN to a strong, random value
    • Keep ELIZA_UI_ENABLE=false unless you need the web interface
    • Use HTTPS in production (configure via reverse proxy)
  3. Development Convenience:
    • Default settings optimize for easy development
    • UI is enabled automatically
    • No authentication required
For a complete list of all available environment variables including database connections, model providers, and plugin settings, see:
.env vs .env.example:
  • .env - Your actual working environment file with real secret values (never commit this file)
  • .env.example - Template file with example/placeholder values (safe to commit as reference)

​
See Also

Deploy a Project

Learn to deploy your ElizaOS project securely

CLI Environment Commands

Manage environment variables with the CLI

API Reference

Explore the REST API that these variables protect

Project Overview

Return to the complete project documentation