elizaOS · yungalgo · Sep 13, 2025 · Sep 13, 2025
diff --git a/docs.json b/docs.json
@@ -53,7 +53,8 @@
           {
             "group": "PROJECTS",
             "pages": [
-              "projects/overview"
+              "projects/overview",
+              "projects/environment-variables"
             ]
           },
           {

diff --git a/projects/environment-variables.mdx b/projects/environment-variables.mdx
@@ -0,0 +1,164 @@
+---
+title: Environment Variables
+description: Server configuration environment variables for ElizaOS
+---
+
+This document describes the server configuration environment variables for ElizaOS.
+
+## Server Security & Authentication
+
+### ELIZA_SERVER_AUTH_TOKEN
+
+Controls API authentication for the ElizaOS server.
+
+```bash .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:**
+```bash
+# 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**:
+  ```bash
+  # 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
+
+<Info>
+  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.
+</Info>
+
+## 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)
+
+```bash .env
+NODE_ENV=production
+ELIZA_SERVER_AUTH_TOKEN=secure-random-token-here
+ELIZA_UI_ENABLE=false
+```
+
+### Development Setup (Convenient)
+
+```bash .env
+NODE_ENV=development
+# ELIZA_SERVER_AUTH_TOKEN=  # Unset for easy development
+# ELIZA_UI_ENABLE=         # Unset for automatic behavior (UI enabled)
+```
+
+### Headless API Server
+
+```bash .env
+ELIZA_SERVER_AUTH_TOKEN=api-only-token
+ELIZA_UI_ENABLE=false
+```
+
+### Public Web Application
+
+```bash .env
+NODE_ENV=production
+ELIZA_SERVER_AUTH_TOKEN=my-api-key
+ELIZA_UI_ENABLE=true
+```
+
+## Security Considerations
+
+<Warning>
+  **API Authentication**: In production, always set `ELIZA_SERVER_AUTH_TOKEN` to prevent unauthorized access to your agent's API endpoints.
+</Warning>
+
+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
+
+## Related Configuration
+
+For a complete list of all available environment variables including database connections, model providers, and plugin settings, see:
+- [Project Overview - Environment Configuration](/projects/overview#environment-configuration)
+- [`.env.example`](https://github.com/elizaos/eliza/blob/main/.env.example) in the repository - Template file showing all available environment variables with example values
+
+<Note>
+  **`.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)
+</Note>
+
+## What's Next?
+
+<CardGroup cols={2}>
+  <Card title="Deploy a Project" icon="rocket" href="/guides/deploy-a-project">
+    Learn to deploy your ElizaOS project securely
+  </Card>
+
+  <Card title="CLI Environment Commands" icon="terminal" href="/cli-reference/env">
+    Manage environment variables with the CLI
+  </Card>
+
+  <Card title="API Reference" icon="code" href="/api-reference">
+    Explore the REST API that these variables protect
+  </Card>
+
+  <Card title="Project Overview" icon="folder" href="/projects/overview">
+    Return to the complete project documentation
+  </Card>
+</CardGroup>
diff --git a/projects/overview.mdx b/projects/overview.mdx
@@ -215,7 +215,7 @@ export default project;
 
 ## Environment Configuration
 
-Projects use `.env` files for your API key management and configuration. Define these at the project level to start, then you can define them at the agent level in multi-agent projects using the `secrets` array in your character `.ts`/`.json` object.
+Projects come with `.env` files for API keys and configuration, plus `.env.example` with additional variables you can copy. Define these at the project level to start, then you can define them at the agent level in multi-agent projects using the `secrets` array in your character `.ts`/`.json` object.
 
 ```bash .env
 # Model Providers
@@ -236,6 +236,10 @@ LOG_LEVEL=info
 NODE_ENV=production
 ```
 
+<Tip>
+  For detailed information about server security, authentication, and UI configuration environment variables, see the [Environment Variables](/projects/environment-variables) documentation.
+</Tip>
+
 ## Running Projects Locally
 
 Start your project with the elizaOS CLI:
@@ -396,7 +400,7 @@ See the [Deploy a Project](/guides/deploy-a-project) guide for detailed instruct
   </Accordion>
 </AccordionGroup>
 
-## Next Steps
+## What's Next?
 
 <CardGroup cols={2}>
   <Card title="Quickstart" icon="play" href="/quickstart">

diff --git a/runtime/sessions-api.mdx b/runtime/sessions-api.mdx
@@ -1950,7 +1950,7 @@ class SessionsAPIClient:
         return response.json()
 ```
 
-## Next Steps
+## What's Next?
 
 <CardGroup cols={2}>
   <Card title="WebSocket Integration" icon="wifi" href="/api-reference/websocket/socketio-real-time-connection">