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)
This subsection applies to the DeepAgents / API path. Codex / Cursor daily chat and internal Services do not require an additional LLM API key; see 4.12. Separate API capabilities such as voice still require their own configuration.
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY | Anthropic API key (Claude series) |
OPENAI_API_KEY | OpenAI API key (GPT + multimedia generation) |
Other configured providers include BEDROCK_API_KEY / BEDROCK_REGION, OPENROUTER_API_KEY, and SILICONFLOW_API_KEY. SiliconFlow and OpenRouter models are enabled through the settings allowlist. Optional endpoint overrides are OPENROUTER_BASE_URL and SILICONFLOW_BASE_URL; see .env.example. These API credentials are independent of Codex/Cursor supplier login.
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/).
For Cloudflare R2, use https://<ACCOUNT_ID>.r2.cloudflarestorage.com as S3_ENDPOINT_URL. An empty region resolves to auto for R2 and us-east-1 otherwise. S3_CHECKSUM_MODE=auto uses when_required for custom endpoints; S3_ADDRESSING_STYLE=path is available for compatible deployments that require path addressing. Configure bucket CORS if the browser fetches signed URLs directly. See the full R2 example in .env.example.
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 |
11.10 Optional supplier runtimes
Use .env.example as the configuration reference. Set JELLYFISH_RUNTIME_ENABLED=1, JELLYFISH_RUNTIME_ACCESS_MODE=trusted_shared, JELLYFISH_RUNTIME_BACKEND=local, and UVICORN_WORKERS=1. This requires macOS/Linux and the chosen CLI in the backend environment. With Docker, set either/both pinned build arguments JELLYFISH_CODEX_CLI_VERSION=0.154.0 and JELLYFISH_CURSOR_CLI_VERSION=2026.09.15-d2fe57e, rebuild the application container, then reload Nginx. These are documented installation-tested versions, not a promise of full production validation.
The operator reads the host key with python3 launcher.py --superadmin-key (Docker: docker compose exec openjellyfish python launcher.py --superadmin-key) and enters it at /superadmin. Log in to the supplier and grant selected models to existing admins. JELLYFISH_OWNER_USER_ID is obsolete. Native supplier login is separate from Jellyfish API keys.
Runtime state defaults to data/runtime; Docker persists it through /app/data. Back up the database, credential vault and encryption key together. The host management key defaults to config/superadmin.key for direct deployment and /app/data/superadmin.key in Docker. A custom JELLYFISH_SUPERADMIN_KEY_FILE must be the same process environment variable for the backend and key CLI. The local backend is for trusted teams, including when the whole app runs in Docker; it is not per-tenant container isolation.