Skip to content

Environment Variables Reference

Complete reference for all environment variables used in Aegis.

Overview

Environment variables are defined in /home/agent/projects/aegis-core/.env and loaded by Docker Compose.

Security: Never commit .env to version control. Use .env.example for templates.

Database Variables

POSTGRES_HOST

PostgreSQL database host.

Type: string Default: host.docker.internal Format: Hostname or IP address Used by: Dashboard, Scheduler

Example: 

POSTGRES_HOST=host.docker.internal
POSTGRES_HOST=10.10.10.103
POSTGRES_HOST=postgres.example.com

POSTGRES_PORT

PostgreSQL database port.

Type: integer Default: 5432 Used by: Dashboard, Scheduler

Example: 

POSTGRES_PORT=5432

POSTGRES_USER

PostgreSQL username.

Type: string Default: agent Used by: Dashboard, Scheduler

Example: 

POSTGRES_USER=agent

POSTGRES_PASSWORD

PostgreSQL password.

Type: string Default: agent Used by: Dashboard, Scheduler Security: Change in production

Example: 

POSTGRES_PASSWORD=secure_password_here

POSTGRES_DB

PostgreSQL database name.

Type: string Default: aegis Used by: Dashboard, Scheduler

Example: 

POSTGRES_DB=aegis

LLM API Keys

ZAI_API_KEY

Primary Z.ai API key for GLM-4.7.

Type: string (format: {id}.{secret}) Required: Yes Used by: Dashboard, Scheduler Rate Limit: ~8 req/min

Example: 

ZAI_API_KEY=14392bf733914c24a77d2d36a2c7d4bd.z9QhBPXv2X6pwwHf

Getting a Key: Sign up at https://z.ai

ZAI_API_KEY_FALLBACK

Fallback Z.ai API key.

Type: string Required: No Used by: Dashboard (automatic failover)

Example: 

ZAI_API_KEY_FALLBACK=51a97fb60c4748e592d78bd687fba025.kJiYmb2HAfiuLnPr

ZAI_BASE_URL

Z.ai API base URL.

Type: string (URL) Default: https://api.z.ai/api/anthropic/v1 Used by: Dashboard

Example: 

ZAI_BASE_URL=https://api.z.ai/api/anthropic/v1

ZAI_ANTHROPIC_BASE

Z.ai Anthropic-compatible endpoint.

Type: string (URL) Default: https://api.z.ai/api/anthropic Used by: Dashboard

Example: 

ZAI_ANTHROPIC_BASE=https://api.z.ai/api/anthropic

PERPLEXITY_API_KEY

Perplexity API key for deep research.

Type: string Required: No (only for deep briefings) Used by: Intel deep briefing generation

Example: 

PERPLEXITY_API_KEY=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

Getting a Key: https://www.perplexity.ai/settings/api

CLAUDE_CODE_OAUTH_TOKEN

Claude Code OAuth token.

Type: string Required: No Used by: Claude Code integration

Example: 

CLAUDE_CODE_OAUTH_TOKEN=token_here

Communication Services

GITHUB_TOKEN

GitHub Personal Access Token.

Type: string (format: github_pat_...) Required: Yes (for GitHub operations) Used by: Dashboard, MCP GitHub server Scopes: repo, read:org, read:user

Example: 

GITHUB_TOKEN=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

Creating a Token: 1. Go to GitHub Settings → Developer settings → Personal access tokens 2. Generate new token (classic) 3. Select scopes: repo, read:org, read:user 4. Copy token

TELEGRAM_BOT_TOKEN

Telegram bot token.

Type: string (format: {id}:{token}) Required: Yes (for Telegram alerts) Used by: Dashboard, MCP Telegram server

Example: 

TELEGRAM_BOT_TOKEN=8595357001:AAEQlNjve9pDdgM0ibQhr1GM_6KYt6HHUfg

Creating a Bot: 1. Message @BotFather on Telegram 2. Send /newbot 3. Follow prompts 4. Copy token

TELEGRAM_CHAT_ID

Telegram chat ID for alerts.

Type: integer (as string) Required: Yes (for Telegram alerts) Used by: Dashboard

Example: 

TELEGRAM_CHAT_ID=1275129801

Finding Chat ID: 1. Message your bot 2. Visit https://api.telegram.org/bot{TOKEN}/getUpdates 3. Look for chat.id in response

VONAGE_API_KEY

Vonage API key.

Type: string Required: Yes (for WhatsApp) Used by: Dashboard

Example: 

VONAGE_API_KEY=b5e9b438

VONAGE_API_SECRET

Vonage API secret.

Type: string Required: Yes (for WhatsApp) Used by: Dashboard

Example: 

VONAGE_API_SECRET=5c4LNSMyZBYDNXht

VONAGE_APPLICATION_ID

Vonage application ID.

Type: string (UUID) Required: Yes (for WhatsApp) Used by: Dashboard

Example: 

VONAGE_APPLICATION_ID=3b60dc5c-44e6-402c-91ae-3731717bb2e7

VONAGE_WHATSAPP_NUMBER

WhatsApp Business Account number.

Type: string (digits only, no +) Required: Yes (for WhatsApp) Used by: Dashboard

Example: 

VONAGE_WHATSAPP_NUMBER=447441443388

VONAGE_PRIVATE_KEY_B64

Base64-encoded Vonage private key.

Type: string (base64) Required: Yes (for WhatsApp) Used by: Dashboard Format: Base64-encoded PEM private key

Example: 

VONAGE_PRIVATE_KEY_B64=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0t...

Encoding Key: 

cat private.key | base64 -w 0 > private.key.b64

VONAGE_SIGNATURE_SECRET

Vonage webhook signature secret.

Type: string Required: No (optional, for webhook verification) Used by: Dashboard

Example: 

VONAGE_SIGNATURE_SECRET=your_secret_here

Note: If not set, webhook signature verification is disabled.

DISCORD_ALERTS_CHANNEL

Discord channel ID for alerts.

Type: string (integer as string) Required: No Used by: Dashboard

Example: 

DISCORD_ALERTS_CHANNEL=1455049130614329508

DISCORD_JOURNAL_CHANNEL

Discord channel ID for journal entries.

Type: string (integer as string) Required: No Used by: Dashboard

Example: 

DISCORD_JOURNAL_CHANNEL=1455049131725816023

Payment Services

STRIPE_PUBLISHABLE_KEY

Stripe publishable key (client-side).

Type: string (format: pk_live_... or pk_test_...) Required: Yes (for payments) Used by: Dashboard (frontend)

Example: 

STRIPE_PUBLISHABLE_KEY=pk_live_51Sk71uGXYX2yjS5iby5kHGDRcmIU6v4ArsrJhRA4x6VcT1HiTX6TiBLYB9ab7vDDzmWjk5TjeJu2g4tb38RojmU700l6pCMSCn

STRIPE_SECRET_KEY

Stripe secret key (server-side).

Type: string (format: sk_live_... or sk_test_...) Required: Yes (for payments) Used by: Dashboard (backend) Security: Never expose publicly

Example: 

STRIPE_SECRET_KEY=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

STRIPE_WEBHOOK_SECRET

Stripe webhook signing secret.

Type: string (format: whsec_...) Required: Yes (for webhooks) Used by: Dashboard

Example: 

STRIPE_WEBHOOK_SECRET=whsec_pQ65Zc2ZooSWqWrlg6O5hfOAGnsk6o03

Finding Secret: 1. Go to Stripe Dashboard → Developers → Webhooks 2. Click on your webhook endpoint 3. Click "Reveal" under "Signing secret"

STRIPE_PRICE_DEVELOPER

Stripe price ID for Developer tier.

Type: string (format: price_...) Required: No Used by: Dashboard

Example: 

STRIPE_PRICE_DEVELOPER=price_1234567890

STRIPE_PRICE_PRO

Stripe price ID for Pro tier.

Type: string Required: No Used by: Dashboard

STRIPE_PRICE_ENTERPRISE

Stripe price ID for Enterprise tier.

Type: string Required: No Used by: Dashboard

STRIPE_PRICE_STARTER

Stripe price ID for Starter tier.

Type: string Required: No Used by: Dashboard

STRIPE_PRICE_RESEARCH_PRO

Stripe price ID for Research Pro tier.

Type: string Required: No Used by: Dashboard

RESEND_API_KEY

Resend API key for transactional emails.

Type: string (format: re_...) Required: Yes (for email) Used by: Dashboard (Intel digests, notifications)

Example: 

RESEND_API_KEY=re_THdUYh4Q_KhHWxDVby6wcgRvPbopoLE8h

Getting a Key: https://resend.com/api-keys

Service Configuration

AEGIS_BASE_URL

Base URL for Aegis dashboard.

Type: string (URL) Default: https://aegisagent.ai Used by: Dashboard (webhooks, redirects)

Example: 

AEGIS_BASE_URL=https://aegisagent.ai

AEGIS_EMAIL_USER_ID

Email address for Aegis workspace.

Type: string (email) Default: aegis@richardbankole.com Used by: Dashboard (email triage)

Example: 

AEGIS_EMAIL_USER_ID=aegis@richardbankole.com

PLAYWRIGHT_URL

Playwright screenshot API URL.

Type: string (URL) Default: http://playwright:3000 Used by: Scheduler (visual monitoring)

Example: 

PLAYWRIGHT_URL=http://playwright:3000

OLLAMA_HOST

Ollama API host for local models.

Type: string (URL) Default: http://host.docker.internal:11434 Used by: Dashboard, Scheduler

Example: 

OLLAMA_HOST=http://127.0.0.1:11434
OLLAMA_HOST=http://host.docker.internal:11434

OLLAMA_BASE_URL

Alternative to OLLAMA_HOST.

Type: string (URL) Default: http://host.docker.internal:11434 Used by: Dashboard

FALKORDB_HOST

FalkorDB (knowledge graph) host.

Type: string Default: host.docker.internal Used by: Dashboard (Graphiti client)

Example: 

FALKORDB_HOST=host.docker.internal
FALKORDB_HOST=localhost

FALKORDB_PORT

FalkorDB port.

Type: integer Default: 6379 Used by: Dashboard

Example: 

FALKORDB_PORT=6379

SMTP Configuration

SMTP_HOST

SMTP server host.

Type: string Default: smtp.resend.com Used by: Dashboard (email digests)

Example: 

SMTP_HOST=smtp.resend.com

SMTP_PORT

SMTP server port.

Type: integer Default: 587 Used by: Dashboard

Example: 

SMTP_PORT=587
SMTP_PORT=465  # SSL
SMTP_PORT=25   # Plain

SMTP_USER

SMTP username.

Type: string Default: ${RESEND_API_KEY} Used by: Dashboard

Example: 

SMTP_USER=re_THdUYh4Q_KhHWxDVby6wcgRvPbopoLE8h

Note: For Resend, use API key as username.

SMTP_PASSWORD

SMTP password.

Type: string Default: ${RESEND_API_KEY} Used by: Dashboard

Example: 

SMTP_PASSWORD=re_THdUYh4Q_KhHWxDVby6wcgRvPbopoLE8h

SMTP_FROM

Default sender email address.

Type: string (email) Default: noreply@aegisagent.ai Used by: Dashboard

Example: 

SMTP_FROM=noreply@aegisagent.ai
SMTP_FROM="Aegis Intel <intel@aegisagent.ai>"

Admin Secrets

INTEL_DIGEST_ADMIN_KEY

Admin key for triggering digest sends.

Type: string Default: change-me-in-production Used by: Dashboard (digest endpoint) Security: Change in production

Example: 

INTEL_DIGEST_ADMIN_KEY=secure_random_string_here

Generating Secure Key: 

openssl rand -base64 32

Third-Party Services

MESHY_API_KEY

Meshy API key for 3D model generation.

Type: string (format: msy_...) Required: No (only for 3D features) Used by: Dashboard

Example: 

MESHY_API_KEY=msy_OUAYIcr5ioVYJBaqMQjyi98j2WliVVBAfZP5

Getting a Key: https://www.meshy.ai/

MESHY_WEBHOOK_SECRET

Meshy webhook secret for verification.

Type: string Required: No Used by: Dashboard

Example: 

MESHY_WEBHOOK_SECRET=KneYsrWzJE03Lr05oa3IUHDvDvwLTxBR

ANNAS_SECRET_KEY

Anna's Archive API secret.

Type: string Required: No Used by: MCP Anna's Archive server

Example: 

ANNAS_SECRET_KEY=HgwAFwcWbQ9vswNc7frqhFvgm6hBF

ANNAS_BASE_URL

Anna's Archive base URL.

Type: string (URL) Default: https://annas-archive.li Used by: MCP Anna's Archive server

ANNAS_DOWNLOAD_PATH

Download directory for books.

Type: string (path) Default: /home/agent/downloads/annas-archive Used by: MCP Anna's Archive server

Environment-Specific Settings

Development

# Use test keys
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...

# Local services
POSTGRES_HOST=localhost
OLLAMA_HOST=http://localhost:11434

Production

# Use live keys
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...

# Docker internal networking
POSTGRES_HOST=host.docker.internal
OLLAMA_HOST=http://host.docker.internal:11434

# Strong admin keys
INTEL_DIGEST_ADMIN_KEY=$(openssl rand -base64 32)

Variable Precedence

  1. Docker Compose environment section (highest)
  2. .env file
  3. System environment variables
  4. Application defaults (lowest)

Security Best Practices

1. Never Commit Secrets

# .gitignore
.env
.env.local
.env.production
*.key
*.pem

2. Use Strong Keys

# Generate secure random strings
openssl rand -base64 32

# Generate UUID
uuidgen

3. Rotate Keys Regularly

  • API keys: Every 90 days
  • Webhook secrets: Every 6 months
  • Database passwords: Every year

4. Principle of Least Privilege

  • GitHub token: Only required scopes
  • Database user: Only required permissions
  • API keys: Only required services

5. Separate Environments

.env.development
.env.staging
.env.production

6. Encrypt at Rest

# Store in encrypted volume
~/.secure/

Validation

Check Required Variables

#!/bin/bash
required_vars=(
  "POSTGRES_HOST"
  "ZAI_API_KEY"
  "GITHUB_TOKEN"
  "TELEGRAM_BOT_TOKEN"
  "STRIPE_SECRET_KEY"
)

for var in "${required_vars[@]}"; do
  if [ -z "${!var}" ]; then
    echo "ERROR: $var is not set"
    exit 1
  fi
done

echo "All required variables are set"

Test Database Connection

psql -h $POSTGRES_HOST -p $POSTGRES_PORT -U $POSTGRES_USER -d $POSTGRES_DB -c "SELECT 1"

Test API Keys

# Z.ai
curl -H "Authorization: Bearer $ZAI_API_KEY" https://api.z.ai/health

# Stripe
curl -u $STRIPE_SECRET_KEY: https://api.stripe.com/v1/balance

# GitHub
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

Troubleshooting

Variable Not Found

Problem: Application can't find environment variable

Solution: 1. Check .env file exists 2. Verify variable name (case-sensitive) 3. Restart Docker container: docker-compose restart 4. Check docker-compose.yml passes variable

Invalid API Key

Problem: API returns 401 Unauthorized

Solution: 1. Verify key is correct (copy-paste errors) 2. Check key hasn't expired 3. Verify key has required scopes 4. Test with curl

Database Connection Failed

Problem: Can't connect to PostgreSQL

Solution: 1. Check host: Use host.docker.internal from container 2. Verify port: Default is 5432 3. Check credentials match 4. Ensure PostgreSQL is running

Webhook Signature Fails

Problem: Webhook returns 401

Solution: 1. Verify STRIPE_WEBHOOK_SECRET matches dashboard 2. Check raw body is used (not parsed JSON) 3. Test with Stripe CLI: stripe listen --forward-to localhost:8080/webhook

See Also