Skip to content

Commit 1d05606

Browse files
yungalgoyungalgo
authored
Merge pull request #67 from elizaOS/add-projects/environment-variables-page
add env var information + page
2 parents f84c982 + 0c46238 commit 1d05606

File tree

4 files changed

+173
-4
lines changed

4 files changed

+173
-4
lines changed

‎docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@
5353
{
5454
"group": "PROJECTS",
5555
"pages": [
56-
"projects/overview"
56+
"projects/overview",
57+
"projects/environment-variables"
5758
]
5859
},
5960
{

‎projects/environment-variables.mdx‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
title: Environment Variables
3+
description: Server configuration environment variables for ElizaOS
4+
---
5+
6+
This document describes the server configuration environment variables for ElizaOS.
7+
8+
## Server Security & Authentication
9+
10+
### ELIZA_SERVER_AUTH_TOKEN
11+
12+
Controls API authentication for the ElizaOS server.
13+
14+
```bash .env
15+
ELIZA_SERVER_AUTH_TOKEN=your-secret-token
16+
```
17+
18+
**How it works:**
19+
- Set this as your server's required API key
20+
- External apps must send `X-API-KEY: your-secret-token` header when calling your `/api/*` endpoints
21+
- Server rejects requests with wrong/missing keys (401 Unauthorized)
22+
23+
- **Default**: Unset (no authentication required)
24+
- **Security**: When unset, all API endpoints are publicly accessible
25+
- **CORS**: OPTIONS requests are always allowed for preflight
26+
27+
**Example:**
28+
```bash
29+
# API call with authentication
30+
curl -H "X-API-KEY: mysecrettoken123" \
31+
-H "Content-Type: application/json" \
32+
http://localhost:3000/api/agents
33+
```
34+
35+
## Web UI Control
36+
37+
### ELIZA_UI_ENABLE
38+
39+
Controls whether the web user interface is served by the server.
40+
41+
- **Purpose**: Enable or disable the web UI for security and deployment flexibility
42+
- **Values**:
43+
- `true` - Force enable UI
44+
- `false` - Force disable UI
45+
- **Default Behavior**:
46+
- Development (`NODE_ENV=development`): UI enabled
47+
- Production (`NODE_ENV=production`): UI disabled for security
48+
- **Usage**:
49+
```bash
50+
# Force enable in production
51+
ELIZA_UI_ENABLE=true
52+
53+
# Force disable in development
54+
ELIZA_UI_ENABLE=false
55+
56+
# Use automatic behavior
57+
ELIZA_UI_ENABLE=
58+
```
59+
- **Security**: Disabling UI reduces attack surface by removing web interface
60+
- **API Access**: API endpoints remain available regardless of UI setting
61+
62+
<Info>
63+
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.
64+
</Info>
65+
66+
## Environment Mode
67+
68+
### NODE_ENV
69+
70+
Controls the application environment and affects various behaviors including default UI settings and security policies.
71+
72+
- **Values**: `development`, `production`
73+
- **Default**: `development`
74+
- **Effects**:
75+
- CSP (Content Security Policy) configuration
76+
- Default UI enable/disable behavior
77+
- Error message verbosity
78+
- Debugging features availability
79+
80+
## Examples
81+
82+
### Production Deployment (Secure)
83+
84+
```bash .env
85+
NODE_ENV=production
86+
ELIZA_SERVER_AUTH_TOKEN=secure-random-token-here
87+
ELIZA_UI_ENABLE=false
88+
```
89+
90+
### Development Setup (Convenient)
91+
92+
```bash .env
93+
NODE_ENV=development
94+
# ELIZA_SERVER_AUTH_TOKEN= # Unset for easy development
95+
# ELIZA_UI_ENABLE= # Unset for automatic behavior (UI enabled)
96+
```
97+
98+
### Headless API Server
99+
100+
```bash .env
101+
ELIZA_SERVER_AUTH_TOKEN=api-only-token
102+
ELIZA_UI_ENABLE=false
103+
```
104+
105+
### Public Web Application
106+
107+
```bash .env
108+
NODE_ENV=production
109+
ELIZA_SERVER_AUTH_TOKEN=my-api-key
110+
ELIZA_UI_ENABLE=true
111+
```
112+
113+
## Security Considerations
114+
115+
<Warning>
116+
**API Authentication**: In production, always set `ELIZA_SERVER_AUTH_TOKEN` to prevent unauthorized access to your agent's API endpoints.
117+
</Warning>
118+
119+
1. **Default Security**: In production mode with default settings:
120+
- Web UI is disabled
121+
- API endpoints are open (no authentication)
122+
- This prevents accidental exposure of the dashboard but leaves APIs accessible
123+
124+
2. **Recommended Production Setup**:
125+
- Set `ELIZA_SERVER_AUTH_TOKEN` to a strong, random value
126+
- Keep `ELIZA_UI_ENABLE=false` unless you need the web interface
127+
- Use HTTPS in production (configure via reverse proxy)
128+
129+
3. **Development Convenience**:
130+
- Default settings optimize for easy development
131+
- UI is enabled automatically
132+
- No authentication required
133+
134+
## Related Configuration
135+
136+
For a complete list of all available environment variables including database connections, model providers, and plugin settings, see:
137+
- [Project Overview - Environment Configuration](/projects/overview#environment-configuration)
138+
- [`.env.example`](https://github.com/elizaos/eliza/blob/main/.env.example) in the repository - Template file showing all available environment variables with example values
139+
140+
<Note>
141+
**`.env` vs `.env.example`**:
142+
- `.env` - Your actual working environment file with real secret values (never commit this file)
143+
- `.env.example` - Template file with example/placeholder values (safe to commit as reference)
144+
</Note>
145+
146+
## What's Next?
147+
148+
<CardGroup cols={2}>
149+
<Card title="Deploy a Project" icon="rocket" href="/guides/deploy-a-project">
150+
Learn to deploy your ElizaOS project securely
151+
</Card>
152+
153+
<Card title="CLI Environment Commands" icon="terminal" href="/cli-reference/env">
154+
Manage environment variables with the CLI
155+
</Card>
156+
157+
<Card title="API Reference" icon="code" href="/api-reference">
158+
Explore the REST API that these variables protect
159+
</Card>
160+
161+
<Card title="Project Overview" icon="folder" href="/projects/overview">
162+
Return to the complete project documentation
163+
</Card>
164+
</CardGroup>

‎projects/overview.mdx‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ export default project;
215215

216216
## Environment Configuration
217217

218-
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.
218+
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.
219219

220220
```bash .env
221221
# Model Providers
@@ -236,6 +236,10 @@ LOG_LEVEL=info
236236
NODE_ENV=production
237237
```
238238

239+
<Tip>
240+
For detailed information about server security, authentication, and UI configuration environment variables, see the [Environment Variables](/projects/environment-variables) documentation.
241+
</Tip>
242+
239243
## Running Projects Locally
240244

241245
Start your project with the elizaOS CLI:
@@ -396,7 +400,7 @@ See the [Deploy a Project](/guides/deploy-a-project) guide for detailed instruct
396400
</Accordion>
397401
</AccordionGroup>
398402

399-
## Next Steps
403+
## What's Next?
400404

401405
<CardGroup cols={2}>
402406
<Card title="Quickstart" icon="play" href="/quickstart">

‎runtime/sessions-api.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1950,7 +1950,7 @@ class SessionsAPIClient:
19501950
return response.json()
19511951
```
19521952
1953-
## Next Steps
1953+
## What's Next?
19541954
19551955
<CardGroup cols={2}>
19561956
<Card title="WebSocket Integration" icon="wifi" href="/api-reference/websocket/socketio-real-time-connection">

0 commit comments

Comments
 (0)