User Guide · 11
Environment Variable Configuration
Tip: From v2.x, all API Keys can be configured per-user in Settings → General → API Keys (AES-256-GCM encrypted storage), taking priority over environment variables. Environment variables are mainly for initial deployment or fallback.
11.1 Required (at least one)
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY | Anthropic API key (Claude series) |
OPENAI_API_KEY | OpenAI API key (GPT + multimedia generation) |
11.2 Provider Endpoint Overrides
| Variable | Description |
|---|---|
ANTHROPIC_BASE_URL | Custom Anthropic API endpoint |
OPENAI_BASE_URL | Custom OpenAI API endpoint |
11.3 Per-Capability Overrides
When a capability needs a different API Key or endpoint from the main provider:
| Capability | Key Variable | URL Variable |
|---|---|---|
| Image generation | IMAGE_API_KEY | IMAGE_BASE_URL |
| TTS voice | TTS_API_KEY | TTS_BASE_URL |
| Video generation | VIDEO_API_KEY | VIDEO_BASE_URL |
| Realtime voice S2S | S2S_API_KEY | S2S_BASE_URL |
| Speech-to-text STT | STT_API_KEY | STT_BASE_URL |
11.4 Web Search Tools
| Variable | Description |
|---|---|
CLOUDSWAY_SEARCH_KEY | CloudsWay search API (preferred) |
CLOUDSWAY_READ_URL | CloudsWay web fetch endpoint (optional override) |
CLOUDSWAY_SEARCH_URL | CloudsWay search endpoint (optional override) |
TAVILY_API_KEY | Tavily search API (fallback) |
11.5 S3 Storage (Optional)
| Variable | Description |
|---|---|
STORAGE_BACKEND | local (default) or s3 |
S3_BUCKET | S3 bucket name |
S3_REGION | S3 region |
S3_ENDPOINT_URL | Custom endpoint (MinIO/R2/OSS) |
S3_ACCESS_KEY_ID | S3 access key |
S3_SECRET_ACCESS_KEY | S3 secret key |
S3_PREFIX | S3 key prefix (optional) |
Note: JSON config files (users.json, conversations, etc.) currently remain on local disk. S3 mode only hosts the filesystem layer (
docs/,scripts/,generated/,soul/).
11.6 Encryption Master Key
| Variable | Description |
|---|---|
ENCRYPTION_KEY | AES-256-GCM master key for per-admin API Keys (if not set, auto-generates data/encryption.key on first startup) |
In production, strongly recommend explicitly setting
ENCRYPTION_KEYand backing it up properly. If the master key file is lost, all users' API Keys will be unrecoverable.
11.7 Script Sandbox Tuning
| Variable | Default | Description |
|---|---|---|
SCRIPT_CONCURRENCY | 4 | Global concurrent script count |
SCRIPT_QUEUE_TIMEOUT | 180 | Queue timeout (seconds) |
11.8 Port Configuration
| Variable | Default | Description |
|---|---|---|
BACKEND_PORT | 8000 | FastAPI port (Docker) |
FRONTEND_PORT | 3000 | Express/Vite port |
API_TARGET | http://localhost:8000 | Express proxy target |
11.9 Observability
| Variable | Description |
|---|---|
LANGFUSE_SECRET_KEY | Langfuse secret key |
LANGFUSE_PUBLIC_KEY | Langfuse public key |
LANGFUSE_HOST | Langfuse server address |
LANGCHAIN_TRACING_V2 | Enable LangSmith |
LANGCHAIN_API_KEY | LangSmith API Key |