Environment Variables

Overview

Shannon uses environment variables for configuration across all services. This page documents all 100+ configuration options with types, defaults, and impact.

Quick Reference

Category	Variables	Service
Core Runtime	3	All
LLM Provider Keys	11	LLM Service
Web Search	6	LLM Service
Data Stores	17	All
Service Endpoints	8	All
Model Routing	13	Orchestrator, LLM Service
Cache & Rate Limiting	8	All
Tool Execution	11	Orchestrator, Agent Core
Security	6	Gateway, Orchestrator
Observability	5	All
WASI Sandbox	4	Agent Core, LLM Service
Integrations	13	LLM Service
Advanced	20+	Orchestrator

Total: 100+ configuration variables

Configuration File

Copy .env.example to .env and customize:

cp .env.example .env
nano .env

Restart services after changes:

docker compose restart

Core Runtime

ENVIRONMENT

Type: String Default: dev Valid Values: dev, staging, prod Services: All Hot-Reload: No (requires restart) Controls logging verbosity and policy enforcement.

ENVIRONMENT=prod

Impact:

dev: Verbose logging, relaxed policies
staging: Moderate logging, standard policies
prod: Minimal logging, strict policies

DEBUG

Type: Boolean Default: false Valid Values: true, false Services: All Hot-Reload: No Enable debug logging across all services.

DEBUG=true

Impact:

true: Debug-level logs, stack traces
false: Info-level logs only

SERVICE_NAME

Type: String Default: shannon-llm-service Services: LLM Service Hot-Reload: No Service identifier for logging and telemetry.

SERVICE_NAME=shannon-llm-service

LLM Provider API Keys

OPENAI_API_KEY

Type: String Required: At least one provider key Services: LLM Service Hot-Reload: Yes OpenAI API key for GPT models.

OPENAI_API_KEY=sk-...

Models Enabled: GPT-5, GPT-5-mini, GPT-5-nano

Required for semantic memory features (text embeddings). Without this key, vector search and agent memory will be disabled.

ANTHROPIC_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Anthropic API key for Claude models.

ANTHROPIC_API_KEY=sk-ant-...

Models Enabled: Claude 4.5 Sonnet, Claude 4.1 Opus, Claude 4.5 Haiku

GOOGLE_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Google AI API key for Gemini models.

GOOGLE_API_KEY=...

Models Enabled: Gemini Pro, Gemini Flash

GROQ_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Groq API key for fast inference.

GROQ_API_KEY=...

Models Enabled: Llama 3, Mixtral

XAI_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes xAI API key for Grok models.

XAI_API_KEY=...

DEEPSEEK_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes DeepSeek API key.

DEEPSEEK_API_KEY=...

QWEN_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Qwen API key for Alibaba Cloud models.

QWEN_API_KEY=...

MISTRAL_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Mistral API key.

MISTRAL_API_KEY=...

AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY

Type: String Services: LLM Service Hot-Reload: Yes AWS credentials for Bedrock models.

AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

Models Enabled: Claude (Bedrock), Llama (Bedrock), Titan

ZAI_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes ZAI API key.

ZAI_API_KEY=...

Web Search Providers

WEB_SEARCH_PROVIDER

Type: String Default: google Valid Values: google, serper, serpapi, searchapi, bing, exa, firecrawl Services: LLM Service Hot-Reload: Yes Active web search provider.

WEB_SEARCH_PROVIDER=google

Providers:

searchapi — SearchAPI.io — multi-engine search ($0.004/call)

GOOGLE_SEARCH_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Google Custom Search API key.

GOOGLE_SEARCH_API_KEY=...
GOOGLE_SEARCH_ENGINE_ID=...

Obtain from: https://console.cloud.google.com/apis/credentials

SERPER_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Serper.dev API key (Google Search API alternative).

SERPER_API_KEY=...

Obtain from: https://serper.dev

BING_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Microsoft Bing Search API key.

BING_API_KEY=...

EXA_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Exa AI search API key.

EXA_API_KEY=...

FIRECRAWL_API_KEY

Type: String Services: LLM Service Hot-Reload: Yes Firecrawl API key for web scraping.

FIRECRAWL_API_KEY=...

SEARCHAPI_API_KEY

Type: String Required: No Default: (none) Services: LLM Service Hot-Reload: Yes API key for SearchAPI.io. Get one at searchapi.io.

SEARCHAPI_API_KEY=...

Data Stores

PostgreSQL

POSTGRES_HOST

Type: String Default: postgres Services: Gateway, Orchestrator Hot-Reload: No PostgreSQL hostname.

POSTGRES_HOST=postgres

POSTGRES_PORT

Type: Integer Default: 5432 Range: 1-65535 Services: Gateway, Orchestrator Hot-Reload: No PostgreSQL port.

POSTGRES_PORT=5432

POSTGRES_DB

Type: String Default: shannon Services: Gateway, Orchestrator Hot-Reload: No PostgreSQL database name.

POSTGRES_DB=shannon

POSTGRES_USER

Type: String Default: shannon Services: Gateway, Orchestrator Hot-Reload: No PostgreSQL username.

POSTGRES_USER=shannon

POSTGRES_PASSWORD

Type: String Default: shannon Services: Gateway, Orchestrator Hot-Reload: No PostgreSQL password.

POSTGRES_PASSWORD=secure-password

Security: Change in production!

POSTGRES_SSLMODE

Type: String Default: disable Valid Values: disable, require, verify-ca, verify-full Services: Gateway, Orchestrator Hot-Reload: No SSL mode for PostgreSQL connections.

POSTGRES_SSLMODE=require

Redis

REDIS_HOST

Type: String Default: redis Services: All Hot-Reload: No Redis hostname.

REDIS_HOST=redis

REDIS_PORT

Type: Integer Default: 6379 Services: All Hot-Reload: No Redis port.

REDIS_PORT=6379

REDIS_PASSWORD

Type: String Default: Empty Services: All Hot-Reload: No Redis password (if authentication enabled).

REDIS_PASSWORD=secure-password

REDIS_TTL_SECONDS

Type: Integer Default: 3600 Range: 0-∞ (0 = no expiration) Services: All Hot-Reload: Yes Default TTL for Redis keys.

REDIS_TTL_SECONDS=3600

Impact: Cache duration for sessions, events, responses

REDIS_URL

Type: String Default: redis://redis:6379 Services: All Hot-Reload: No Full Redis connection URL.

REDIS_URL=redis://redis:6379
# With auth:
REDIS_URL=redis://:password@redis:6379

LLM_REDIS_URL

Type: String Default: Empty (uses REDIS_URL) Services: LLM Service Hot-Reload: No Dedicated Redis instance for LLM response caching.

LLM_REDIS_URL=redis://llm-redis:6379

Use Case: Separate LLM cache from session data for scaling

Qdrant (Vector Store)

QDRANT_URL

Type: String Default: http://qdrant:6333 Services: Orchestrator, LLM Service Hot-Reload: No Qdrant connection URL.

QDRANT_URL=http://qdrant:6333

QDRANT_HOST / QDRANT_PORT

Type: String / Integer Default: qdrant / 6333 Services: Orchestrator, LLM Service Hot-Reload: No Alternative to QDRANT_URL (host/port separately).

QDRANT_HOST=qdrant
QDRANT_PORT=6333

Service Endpoints

TEMPORAL_HOST

Type: String Default: temporal:7233 Services: Orchestrator Hot-Reload: No Temporal server address.

TEMPORAL_HOST=temporal:7233

LLM_SERVICE_URL

Type: String Default: http://llm-service:8000 Services: Orchestrator, Agent Core Hot-Reload: No LLM Service endpoint.

LLM_SERVICE_URL=http://llm-service:8000

AGENT_CORE_ADDR

Type: String Default: agent-core:50051 Services: Orchestrator Hot-Reload: No Agent Core gRPC address.

AGENT_CORE_ADDR=agent-core:50051

ORCHESTRATOR_GRPC

Type: String Default: orchestrator:50052 Services: Gateway Hot-Reload: No Orchestrator gRPC endpoint.

ORCHESTRATOR_GRPC=orchestrator:50052

ADMIN_SERVER

Type: String Default: http://orchestrator:8081 Services: Gateway Hot-Reload: No Admin/SSE server for streaming events.

ADMIN_SERVER=http://orchestrator:8081

CONFIG_PATH

Type: String Default: ./config/features.yaml Services: Orchestrator, Agent Core Hot-Reload: Yes (with file watcher) Path to feature flags configuration.

CONFIG_PATH=./config/features.yaml

MODELS_CONFIG_PATH

Type: String Default: ./config/models.yaml Services: LLM Service, Orchestrator Hot-Reload: Yes (with file watcher) Path to model and pricing configuration.

MODELS_CONFIG_PATH=./config/models.yaml

EVENTS_INGEST_URL

Type: String Default: http://orchestrator:8081/events Services: Agent Core Hot-Reload: No Event ingestion endpoint.

EVENTS_INGEST_URL=http://orchestrator:8081/events

Model Routing and Budgets

DEFAULT_MODEL_TIER

Type: String Default: small Valid Values: small, medium, large Services: Orchestrator Hot-Reload: Yes Default model tier for tasks.

DEFAULT_MODEL_TIER=small

Tiers:

small: GPT-5-nano, Claude Haiku (~$0.15/1M tokens)
medium: GPT-5-mini, Claude Sonnet (~$3-15/1M tokens)
large: GPT-5.1, Claude Opus (~$15-75/1M tokens)

COMPLEXITY_MODEL_ID

Type: String Default: gpt-5 Services: Orchestrator Hot-Reload: Yes Model used for complexity analysis.

COMPLEXITY_MODEL_ID=gpt-5

DECOMPOSITION_MODEL_ID

Type: String Default: claude-sonnet-4-5-20250929 Services: Orchestrator Hot-Reload: Yes Model used for task decomposition.

DECOMPOSITION_MODEL_ID=claude-sonnet-4-5-20250929

MAX_TOKENS

Type: Integer Default: 2000 Range: 1-∞ Services: LLM Service Hot-Reload: Yes Default max output tokens per LLM call.

MAX_TOKENS=2000

TEMPERATURE

Type: Float Default: 0.7 Range: 0.0-2.0 Services: LLM Service Hot-Reload: Yes Default temperature for LLM sampling.

TEMPERATURE=0.7

Impact:

0.0: Deterministic, focused
0.7: Balanced creativity
1.0+: More random, creative

MAX_TOKENS_PER_REQUEST

Type: Integer Default: 10000 Range: 1-∞ Services: Orchestrator Hot-Reload: Yes Maximum total tokens per task request.

MAX_TOKENS_PER_REQUEST=10000

Impact: Hard budget limit, task fails when exceeded

MAX_COST_PER_REQUEST

Type: Float Default: 0.50 Range: 0.0-∞ Services: Orchestrator Hot-Reload: Yes Maximum cost (USD) per task request.

MAX_COST_PER_REQUEST=0.50

Impact: Task fails when cost exceeds this limit

LLM_DISABLE_BUDGETS

Type: Integer Default: 1 Valid Values: 0, 1 Services: Orchestrator, LLM Service Hot-Reload: Yes Budget enforcement location.

LLM_DISABLE_BUDGETS=1

Values:

1: Orchestrator manages budgets (recommended)
0: LLM service enforces budgets

HISTORY_WINDOW_MESSAGES

Type: Integer Default: 50 Range: 1-∞ Services: Orchestrator Hot-Reload: Yes Number of messages to include in conversation history.

HISTORY_WINDOW_MESSAGES=50

HISTORY_WINDOW_DEBUG_MESSAGES

Type: Integer Default: 75 Services: Orchestrator Hot-Reload: Yes History window size for debug mode.

HISTORY_WINDOW_DEBUG_MESSAGES=75

WORKFLOW_SYNTH_BYPASS_SINGLE

Type: Boolean Default: true Services: Orchestrator Hot-Reload: Yes Skip synthesis for single-result workflows.

WORKFLOW_SYNTH_BYPASS_SINGLE=true

Impact:

true: Faster for simple tasks (skips synthesis step)
false: Always synthesize results

TOKEN_BUDGET_PER_AGENT

Type: Integer Default: Empty (unlimited) Services: Orchestrator Hot-Reload: Yes Token budget per agent execution.

TOKEN_BUDGET_PER_AGENT=5000

TOKEN_BUDGET_PER_TASK

Type: Integer Default: Empty (unlimited) Services: Orchestrator Hot-Reload: Yes Token budget per entire task.

TOKEN_BUDGET_PER_TASK=20000

Cache and Rate Limiting

ENABLE_CACHE

Type: Boolean Default: true Services: LLM Service Hot-Reload: Yes Enable LLM response caching.

ENABLE_CACHE=true

Impact:

true: Cache responses in Redis, faster & cheaper
false: Always hit LLM API

CACHE_SIMILARITY_THRESHOLD

Type: Float Default: 0.95 Range: 0.0-1.0 Services: LLM Service Hot-Reload: Yes Semantic similarity threshold for cache hits.

CACHE_SIMILARITY_THRESHOLD=0.95

Impact:

1.0: Exact matches only
0.95: Very similar queries
0.8: Looser matching (more cache hits, less accuracy)

RATE_LIMIT_REQUESTS

Type: Integer Default: 100 Services: Gateway Hot-Reload: Yes Requests per window per API key.

RATE_LIMIT_REQUESTS=100

RATE_LIMIT_WINDOW

Type: Integer Default: 60 Range: 1-∞ (seconds) Services: Gateway Hot-Reload: Yes Rate limit window duration.

RATE_LIMIT_WINDOW=60

Combined:

RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60
# = 100 requests per 60 seconds

WEB_SEARCH_RATE_LIMIT

Type: Integer Default: 120 Services: LLM Service Hot-Reload: Yes Web search requests per minute.

WEB_SEARCH_RATE_LIMIT=120

CALCULATOR_RATE_LIMIT

Type: Integer Default: 2000 Services: LLM Service Hot-Reload: Yes Calculator tool requests per minute.

CALCULATOR_RATE_LIMIT=2000

PYTHON_EXECUTOR_RATE_LIMIT

Type: Integer Default: 60 Services: Agent Core Hot-Reload: Yes Python code execution requests per minute.

PYTHON_EXECUTOR_RATE_LIMIT=60

PARTIAL_CHUNK_CHARS

Type: Integer Default: 512 Services: LLM Service Hot-Reload: Yes Characters per streaming chunk.

PARTIAL_CHUNK_CHARS=512

Tool Execution and Workflow

TOOL_PARALLELISM

Type: Integer Default: 1 Range: 1-∞ (1 = sequential) Services: Orchestrator, Agent Core Hot-Reload: Yes Concurrent tool executions.

TOOL_PARALLELISM=1

Impact:

1: Sequential execution (slower, safer)
5: 5 tools in parallel (faster, more resources)
10+: High parallelism (fastest, highest resource usage)

ENABLE_TOOL_SELECTION

Type: Integer Default: 1 Valid Values: 0, 1 Services: Orchestrator Hot-Reload: Yes Automatic tool selection by planner.

ENABLE_TOOL_SELECTION=1

Values:

1: Planner auto-selects tools (recommended)
0: Manual tool specification only

PRIORITY_QUEUES

Type: String Default: off Valid Values: on, off Services: Orchestrator Hot-Reload: Yes Enable priority-based task queuing.

PRIORITY_QUEUES=on

STREAMING_RING_CAPACITY

Type: Integer Default: 1000 Services: Orchestrator Hot-Reload: No Ring buffer capacity for streaming events.

STREAMING_RING_CAPACITY=1000

COMPRESSION_TRIGGER_RATIO

Type: Float Default: 0.75 Range: 0.0-1.0 Services: Orchestrator Hot-Reload: Yes Context compression trigger threshold.

COMPRESSION_TRIGGER_RATIO=0.75

Impact: Compress context when 75% of token budget used

COMPRESSION_TARGET_RATIO

Type: Float Default: 0.375 Range: 0.0-1.0 Services: Orchestrator Hot-Reload: Yes Target size after compression.

COMPRESSION_TARGET_RATIO=0.375

ENFORCE_TIMEOUT_SECONDS

Type: Integer Default: 90 Services: Agent Core Hot-Reload: Yes Tool execution timeout.

ENFORCE_TIMEOUT_SECONDS=90

ENFORCE_MAX_TOKENS

Type: Integer Default: 32768 Services: Agent Core Hot-Reload: Yes Maximum tokens per agent execution.

ENFORCE_MAX_TOKENS=32768

ENFORCE_RATE_RPS

Type: Integer Default: 20 Services: Agent Core Hot-Reload: Yes Rate limit (requests per second) for agent operations.

ENFORCE_RATE_RPS=20

ENFORCE_CB_ERROR_THRESHOLD

Type: Float Default: 0.5 Range: 0.0-1.0 Services: Agent Core Hot-Reload: Yes Circuit breaker error rate threshold.

ENFORCE_CB_ERROR_THRESHOLD=0.5

Impact: Circuit opens when 50% of requests fail

ENFORCE_CB_WINDOW_SECONDS

Type: Integer Default: 30 Services: Agent Core Hot-Reload: Yes Circuit breaker measurement window.

ENFORCE_CB_WINDOW_SECONDS=30

ENFORCE_CB_MIN_REQUESTS

Type: Integer Default: 20 Services: Agent Core Hot-Reload: Yes Minimum requests before circuit breaker activates.

ENFORCE_CB_MIN_REQUESTS=20

Approvals and Security

APPROVAL_ENABLED

Type: Boolean Default: false Services: Orchestrator Hot-Reload: Yes Enable human-in-the-loop approvals.

APPROVAL_ENABLED=true

APPROVAL_COMPLEXITY_THRESHOLD

Type: Float Default: 0.5 Range: 0.0-1.0 Services: Orchestrator Hot-Reload: Yes Complexity threshold requiring approval.

APPROVAL_COMPLEXITY_THRESHOLD=0.5

APPROVAL_DANGEROUS_TOOLS

Type: String (comma-separated) Default: file_system,code_execution Services: Orchestrator Hot-Reload: Yes Tools requiring approval.

APPROVAL_DANGEROUS_TOOLS=file_system,code_execution,database_query

APPROVAL_TIMEOUT_SECONDS

Type: Integer Default: 1800 Services: Orchestrator Hot-Reload: Yes Approval request timeout (30 minutes).

APPROVAL_TIMEOUT_SECONDS=1800

JWT_SECRET

Type: String Default: development-only-secret-change-in-production Services: Gateway Hot-Reload: No JWT signing secret.

JWT_SECRET=secure-random-256-bit-key

Security: Must change in production!

GATEWAY_SKIP_AUTH

Type: Integer Default: 1 Valid Values: 0, 1 Services: Gateway Hot-Reload: Yes (restart recommended) Skip authentication (development only).

GATEWAY_SKIP_AUTH=0  # Enable auth

Security: Must set to 0 in production!

Templates

TEMPLATE_FALLBACK_ENABLED

Type: Boolean Default: false Services: Orchestrator Hot-Reload: Yes Fallback to AI when template fails.

TEMPLATE_FALLBACK_ENABLED=true

Observability and Telemetry

OTEL_SERVICE_NAME

Type: String Default: shannon-llm-service Services: All Hot-Reload: No Service name for OpenTelemetry.

OTEL_SERVICE_NAME=shannon-llm-service

OTEL_EXPORTER_OTLP_ENDPOINT

Type: String Default: localhost:4317 Services: All Hot-Reload: No OTLP exporter endpoint.

OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317

OTEL_ENABLED

Type: Boolean Default: false Services: All Hot-Reload: No Enable OpenTelemetry tracing.

OTEL_ENABLED=true

LOG_FORMAT

Type: String Default: plain Valid Values: plain, json Services: Agent Core (Rust) Hot-Reload: No Log output format.

LOG_FORMAT=json

METRICS_PORT

Type: Integer Default: 2112 Services: All Hot-Reload: No Prometheus metrics port.

METRICS_PORT=2112

Python WASI Sandbox

PYTHON_WASI_WASM_PATH

Type: String Default: ./wasm-interpreters/python-3.11.4.wasm Services: Agent Core, LLM Service Hot-Reload: No Path to Python WASI interpreter.

PYTHON_WASI_WASM_PATH=./wasm-interpreters/python-3.11.4.wasm

PYTHON_WASI_SESSION_TIMEOUT

Type: Integer Default: 3600 Services: LLM Service Hot-Reload: Yes Python session timeout (seconds).

PYTHON_WASI_SESSION_TIMEOUT=3600

WASI_MEMORY_LIMIT_MB

Type: Integer Default: 512 Services: Agent Core Hot-Reload: Yes WASI sandbox memory limit (MB).

WASI_MEMORY_LIMIT_MB=512

WASI_TIMEOUT_SECONDS

Type: Integer Default: 60 Services: Agent Core Hot-Reload: Yes WASI execution timeout.

WASI_TIMEOUT_SECONDS=60

OpenAPI and MCP

OpenAPI Integration

OPENAPI_ALLOWED_DOMAINS

Type: String Default: * Services: LLM Service Hot-Reload: Yes Allowed domains for OpenAPI spec fetching.

OPENAPI_ALLOWED_DOMAINS=*
# Or specific domains:
OPENAPI_ALLOWED_DOMAINS=api.example.com,api2.example.com

OPENAPI_MAX_SPEC_SIZE

Type: Integer Default: 5242880 (5 MB) Services: LLM Service Hot-Reload: Yes Maximum OpenAPI spec file size.

OPENAPI_MAX_SPEC_SIZE=5242880

OPENAPI_FETCH_TIMEOUT

Type: Integer Default: 30 Services: LLM Service Hot-Reload: Yes Timeout for fetching OpenAPI specs.

OPENAPI_FETCH_TIMEOUT=30

OPENAPI_RETRIES

Type: Integer Default: 3 Services: LLM Service Hot-Reload: Yes Retry attempts for OpenAPI operations (spec fetching and API calls).

OPENAPI_RETRIES=3

MCP Integration

MCP_ALLOWED_DOMAINS

Type: String Default: * Services: LLM Service Hot-Reload: Yes Allowed domains for MCP servers.

MCP_ALLOWED_DOMAINS=*

MCP_MAX_RESPONSE_BYTES

Type: Integer Default: 10485760 (10 MB) Services: LLM Service Hot-Reload: Yes Maximum MCP response size.

MCP_MAX_RESPONSE_BYTES=10485760

MCP_RETRIES

Type: Integer Default: 3 Services: LLM Service Hot-Reload: Yes MCP request retry attempts.

MCP_RETRIES=3

MCP_TIMEOUT_SECONDS

Type: Integer Default: 10 Services: LLM Service Hot-Reload: Yes MCP request timeout.

MCP_TIMEOUT_SECONDS=10

MCP_REGISTER_TOKEN

Type: String Default: Empty Services: LLM Service Hot-Reload: Yes Authentication token for MCP server registration.

MCP_REGISTER_TOKEN=secret-token

MCP_RATE_LIMIT_DEFAULT

Type: Integer Default: 60 Services: LLM Service Hot-Reload: Yes Default rate limit for MCP tools (requests/minute).

MCP_RATE_LIMIT_DEFAULT=60

MCP_CB_FAILURES

Type: Integer Default: 5 Services: LLM Service Hot-Reload: Yes Circuit breaker failure threshold for MCP.

MCP_CB_FAILURES=5

MCP_CB_RECOVERY_SECONDS

Type: Integer Default: 60 Services: LLM Service Hot-Reload: Yes Circuit breaker recovery time.

MCP_CB_RECOVERY_SECONDS=60

MCP_COST_TO_TOKENS

Type: Integer Default: 0 Services: LLM Service Hot-Reload: Yes Token cost multiplier for MCP tools.

MCP_COST_TO_TOKENS=100

Advanced Orchestrator Controls

EVENTLOG_BATCH_SIZE

Type: Integer Default: 100 Services: Orchestrator Hot-Reload: Yes Events per batch for database writes.

EVENTLOG_BATCH_SIZE=100

EVENTLOG_BATCH_INTERVAL_MS

Type: Integer Default: 100 Services: Orchestrator Hot-Reload: Yes Batch interval (milliseconds).

EVENTLOG_BATCH_INTERVAL_MS=100

RATE_LIMIT_INTERVAL_MS

Type: Integer Default: 60000 Services: Orchestrator Hot-Reload: Yes Rate limit window (milliseconds).

RATE_LIMIT_INTERVAL_MS=60000

Worker Concurrency

Configure Temporal worker concurrency per priority queue:

# Default workers (all priorities)
WORKER_ACT=10
WORKER_WF=10

# Critical priority
WORKER_ACT_CRITICAL=12
WORKER_WF_CRITICAL=12

# High priority
WORKER_ACT_HIGH=10
WORKER_WF_HIGH=10

# Normal priority
WORKER_ACT_NORMAL=8
WORKER_WF_NORMAL=8

# Low priority
WORKER_ACT_LOW=4
WORKER_WF_LOW=4

Impact:

Higher values = more concurrency, more resource usage
Lower values = less concurrency, lower resource usage

LLM_TIMEOUT_SECONDS

Type: Integer Default: 120 Services: Orchestrator Hot-Reload: Yes Timeout for LLM API calls.

LLM_TIMEOUT_SECONDS=120

Miscellaneous

SHANNON_WORKSPACE

Type: String Default: ./workspace Services: Agent Core Hot-Reload: No Workspace directory for file operations.

SHANNON_WORKSPACE=./workspace

SHANNON_SESSION_WORKSPACES_DIR

Type: String Default: /tmp/shannon-sessions Services: Gateway, Agent Core Hot-Reload: No Base directory for session-isolated workspace files. Each session gets a subdirectory.

SHANNON_SESSION_WORKSPACES_DIR=/tmp/shannon-sessions

SHANNON_USE_WASI_SANDBOX

Type: Boolean (0/1) Default: 0 Services: Agent Core Hot-Reload: No Enable WASI sandbox for file operations. When enabled, file access is mediated through the Firecracker executor for security isolation.

SHANNON_USE_WASI_SANDBOX=1

SHANNON_MAX_WORKSPACE_SIZE_MB

Type: Integer Default: 100 Services: Agent Core Hot-Reload: No Maximum disk quota per session workspace in megabytes.

SHANNON_MAX_WORKSPACE_SIZE_MB=100

SEED_DATA

Type: Boolean Default: false Services: All Hot-Reload: No Seed Qdrant with sample data on startup.

SEED_DATA=true

AGENT_TIMEOUT_SECONDS

Type: Integer Default: 600 Services: Agent Core Hot-Reload: Yes Maximum runtime per agent execution.

AGENT_TIMEOUT_SECONDS=600

Configuration Examples

Development

ENVIRONMENT=dev
DEBUG=true
GATEWAY_SKIP_AUTH=1
ENABLE_CACHE=true
DEFAULT_MODEL_TIER=small
MAX_COST_PER_REQUEST=0.10
TOOL_PARALLELISM=3

Production

ENVIRONMENT=prod
DEBUG=false
GATEWAY_SKIP_AUTH=0
JWT_SECRET=<secure-256-bit-key>
POSTGRES_PASSWORD=<secure-password>
REDIS_PASSWORD=<secure-password>
ENABLE_CACHE=true
DEFAULT_MODEL_TIER=medium
MAX_COST_PER_REQUEST=1.00
TOOL_PARALLELISM=5
OTEL_ENABLED=true
LOG_FORMAT=json

High Performance

TOOL_PARALLELISM=10
WORKER_ACT_CRITICAL=30
WORKER_WF_CRITICAL=15
ENABLE_CACHE=true
CACHE_SIMILARITY_THRESHOLD=0.90
STREAMING_RING_CAPACITY=2000

Cost Optimized

DEFAULT_MODEL_TIER=small
MAX_COST_PER_REQUEST=0.25
MAX_TOKENS_PER_REQUEST=5000
ENABLE_CACHE=true
CACHE_SIMILARITY_THRESHOLD=0.95
WORKFLOW_SYNTH_BYPASS_SINGLE=true

Troubleshooting

See Configuration Troubleshooting for common issues.

Docker Compose

Docker deployment guide

Kubernetes

Kubernetes deployment

Performance Tuning

Optimize performance

Security

Security hardening

Getting Started

Cloud Platforms

Operations

​Overview

​Quick Reference

​Configuration File

​Core Runtime

​ENVIRONMENT

​DEBUG

​SERVICE_NAME

​LLM Provider API Keys

​OPENAI_API_KEY

​ANTHROPIC_API_KEY

​GOOGLE_API_KEY

​GROQ_API_KEY

​XAI_API_KEY

​DEEPSEEK_API_KEY

​QWEN_API_KEY

​MISTRAL_API_KEY

​AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY

​ZAI_API_KEY

​Web Search Providers

​WEB_SEARCH_PROVIDER

​GOOGLE_SEARCH_API_KEY

​SERPER_API_KEY

​BING_API_KEY

​EXA_API_KEY

​FIRECRAWL_API_KEY

​SEARCHAPI_API_KEY

​Data Stores

​PostgreSQL

​POSTGRES_HOST

​POSTGRES_PORT

​POSTGRES_DB

​POSTGRES_USER

​POSTGRES_PASSWORD

​POSTGRES_SSLMODE

​Redis

​REDIS_HOST

​REDIS_PORT

​REDIS_PASSWORD

​REDIS_TTL_SECONDS

​REDIS_URL

​LLM_REDIS_URL

​Qdrant (Vector Store)

​QDRANT_URL

​QDRANT_HOST / QDRANT_PORT

​Service Endpoints

​TEMPORAL_HOST

​LLM_SERVICE_URL

​AGENT_CORE_ADDR

​ORCHESTRATOR_GRPC

​ADMIN_SERVER

​CONFIG_PATH

​MODELS_CONFIG_PATH

​EVENTS_INGEST_URL

​Model Routing and Budgets

​DEFAULT_MODEL_TIER

​COMPLEXITY_MODEL_ID

​DECOMPOSITION_MODEL_ID

​MAX_TOKENS

​TEMPERATURE

​MAX_TOKENS_PER_REQUEST

​MAX_COST_PER_REQUEST

​LLM_DISABLE_BUDGETS

​HISTORY_WINDOW_MESSAGES

​HISTORY_WINDOW_DEBUG_MESSAGES

​WORKFLOW_SYNTH_BYPASS_SINGLE

​TOKEN_BUDGET_PER_AGENT

​TOKEN_BUDGET_PER_TASK

​Cache and Rate Limiting

​ENABLE_CACHE

​CACHE_SIMILARITY_THRESHOLD

​RATE_LIMIT_REQUESTS

​RATE_LIMIT_WINDOW

​WEB_SEARCH_RATE_LIMIT

​CALCULATOR_RATE_LIMIT

​PYTHON_EXECUTOR_RATE_LIMIT

​PARTIAL_CHUNK_CHARS

​Tool Execution and Workflow

Overview

Quick Reference

Configuration File

Core Runtime

ENVIRONMENT

DEBUG

SERVICE_NAME

LLM Provider API Keys

OPENAI_API_KEY

ANTHROPIC_API_KEY

GOOGLE_API_KEY

GROQ_API_KEY

XAI_API_KEY

DEEPSEEK_API_KEY

QWEN_API_KEY

MISTRAL_API_KEY

AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY

ZAI_API_KEY

Web Search Providers

WEB_SEARCH_PROVIDER

GOOGLE_SEARCH_API_KEY

SERPER_API_KEY

BING_API_KEY

EXA_API_KEY

FIRECRAWL_API_KEY

SEARCHAPI_API_KEY

Data Stores

PostgreSQL

POSTGRES_HOST

POSTGRES_PORT

POSTGRES_DB

POSTGRES_USER

POSTGRES_PASSWORD

POSTGRES_SSLMODE

Redis

REDIS_HOST

REDIS_PORT

REDIS_PASSWORD

REDIS_TTL_SECONDS

REDIS_URL

LLM_REDIS_URL

Qdrant (Vector Store)

QDRANT_URL

QDRANT_HOST / QDRANT_PORT

Service Endpoints

TEMPORAL_HOST

LLM_SERVICE_URL

AGENT_CORE_ADDR

ORCHESTRATOR_GRPC

ADMIN_SERVER

CONFIG_PATH

MODELS_CONFIG_PATH

EVENTS_INGEST_URL

Model Routing and Budgets

DEFAULT_MODEL_TIER

COMPLEXITY_MODEL_ID

DECOMPOSITION_MODEL_ID

MAX_TOKENS

TEMPERATURE

MAX_TOKENS_PER_REQUEST

MAX_COST_PER_REQUEST

LLM_DISABLE_BUDGETS

HISTORY_WINDOW_MESSAGES

HISTORY_WINDOW_DEBUG_MESSAGES

WORKFLOW_SYNTH_BYPASS_SINGLE

TOKEN_BUDGET_PER_AGENT

TOKEN_BUDGET_PER_TASK

Cache and Rate Limiting

ENABLE_CACHE

CACHE_SIMILARITY_THRESHOLD

RATE_LIMIT_REQUESTS

RATE_LIMIT_WINDOW

WEB_SEARCH_RATE_LIMIT

CALCULATOR_RATE_LIMIT

PYTHON_EXECUTOR_RATE_LIMIT

PARTIAL_CHUNK_CHARS

Tool Execution and Workflow

TOOL_PARALLELISM

ENABLE_TOOL_SELECTION

PRIORITY_QUEUES