Environment Variables
Arkenos manages most API keys through the API Keys dashboard page (encrypted in the database). Only a few infrastructure variables need .env files.
Root .env (Docker Compose)
When using Docker Compose, the root .env only needs one variable:
| Variable | Required | Description |
|---|
POSTGRES_PASSWORD | Yes | PostgreSQL password |
BETTER_AUTH_SECRET | No | Session encryption secret (has a default, override for production) |
Backend (backend/.env)
For local development (without Docker), configure the backend directly:
| Variable | Required | Description |
|---|
POSTGRES_PASSWORD | Yes | PostgreSQL password (used to build DATABASE_URL) |
DATABASE_URL | No | Full PostgreSQL connection string (overrides auto-built URL if set) |
DB_HOST | No | Database host (default: localhost, set to postgres in Docker) |
.env as a fallback — the dashboard takes priority.
POSTGRES_PASSWORD is the only truly required environment variable for the backend. Everything else is managed through the dashboard or has sensible defaults.
Frontend (frontend/.env.local)
| Variable | Required | Description |
|---|
NEXT_PUBLIC_API_URL | Yes | Backend API URL (e.g., http://localhost:4201/api) |
BETTER_AUTH_SECRET | Yes (Docker) | Better Auth secret (set via docker-compose, or manually for local dev) |
BETTER_AUTH_URL | Yes (Docker) | Better Auth URL (set via docker-compose) |
DATABASE_URL | Yes (Docker) | Database connection for Better Auth (set via docker-compose) |
LiveKit, Google, Resemble, and Deepgram keys are no longer needed in the frontend .env. The frontend fetches provider data through the backend API, which resolves keys from the dashboard.
Agent
The agent requires no .env file. On startup, it calls the backend’s /api/settings/keys/agent endpoint and injects all keys (including LiveKit) into the process environment before connecting.
| Variable | Required | Description |
|---|
BACKEND_API_URL | No | Defaults to http://localhost:8000/api. Only set this if the backend runs on a different host/port. |
All provider keys — LiveKit, Google, Resemble, STT providers — are fetched from the backend dashboard automatically. No .env file needed.
Dashboard-Managed Keys
These keys are configured at API Keys in the dashboard. They are encrypted with AES-256-GCM and stored in the database.
| Provider | Keys | Purpose |
|---|
| LiveKit | API Key, API Secret, Server URL | Real-time voice infrastructure |
| Google | API Key | Gemini LLM for conversational intelligence |
| Resemble AI | API Key | Text-to-speech voice synthesis |
| Twilio | Account SID, Auth Token | Phone number management and SIP telephony |
| AssemblyAI | API Key | Speech-to-text (STT option) |
| Deepgram | API Key | Speech-to-text (STT option) |
| ElevenLabs | API Key | Speech-to-text (STT option) |
Auto-Provisioned (No Config Needed)
These were previously environment variables but are now fully automated:
| Old Variable | What Happens Now |
|---|
TWILIO_SIP_DOMAIN | Auto-derived from LIVEKIT_URL |
LIVEKIT_SIP_TRUNK_ID | Auto-provisioned on first outbound call |
ENCRYPTION_KEY | Auto-generated and stored in database on first boot |
FRONTEND_URL | Defaults to http://localhost:3000 |
PORT | Defaults to 8000 |
DEBUG | Defaults to true |
Custom Agent Infrastructure
These variables are only needed if you use custom Python agents:
| Variable | Default | Description |
|---|
MINIO_ENDPOINT | localhost:9000 | MinIO server address |
MINIO_ACCESS_KEY | minioadmin | MinIO access key |
MINIO_SECRET_KEY | minioadmin | MinIO secret key |
MINIO_BUCKET | arkenos | MinIO bucket name |
DOCKER_SOCKET | unix:///var/run/docker.sock | Docker socket path |
BASE_AGENT_IMAGE | arkenos-agent-base:latest | Base Docker image for custom agents |
CONTAINER_NETWORK | arkenos_default | Docker network for agent containers |
CONTAINER_TIMEOUT_SECONDS | 3600 | Timeout for custom agent containers |
CODING_AGENT_PROVIDER | gemini | AI provider for the coding assistant |
Telemetry
| Variable | Default | Description |
|---|
NEXT_PUBLIC_TELEMETRY | true | Set to false to disable anonymous product telemetry (PostHog) |
NEXT_PUBLIC_TELEMETRY=false to opt out.
