> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Complete environment variable reference for Shannon configuration

## 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](#core-runtime)                     | 3         | All                       |
| [LLM Provider Keys](#llm-provider-api-keys)       | 11        | LLM Service               |
| [Web Search](#web-search-providers)               | 6         | LLM Service               |
| [Data Stores](#data-stores)                       | 17        | All                       |
| [Service Endpoints](#service-endpoints)           | 8         | All                       |
| [Model Routing](#model-routing-and-budgets)       | 13        | Orchestrator, LLM Service |
| [Cache & Rate Limiting](#cache-and-rate-limiting) | 8         | All                       |
| [Tool Execution](#tool-execution-and-workflow)    | 11        | Orchestrator, Agent Core  |
| [Security](#approvals-and-security)               | 6         | Gateway, Orchestrator     |
| [Observability](#observability-and-telemetry)     | 5         | All                       |
| [WASI Sandbox](#python-wasi-sandbox)              | 4         | Agent Core, LLM Service   |
| [Integrations](#openapi-and-mcp)                  | 13        | LLM Service               |
| [Advanced](#advanced-orchestrator-controls)       | 20+       | Orchestrator              |

**Total**: 100+ configuration variables

## Configuration File

Copy `.env.example` to `.env` and customize:

```bash theme={null}
cp .env.example .env
nano .env
```

Restart services after changes:

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
OPENAI_API_KEY=sk-...
```

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

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

### ANTHROPIC\_API\_KEY

**Type**: String
**Services**: LLM Service
**Hot-Reload**: Yes

Anthropic API key for Claude models.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
XAI_API_KEY=...
```

### DEEPSEEK\_API\_KEY

**Type**: String
**Services**: LLM Service
**Hot-Reload**: Yes

DeepSeek API key.

```bash theme={null}
DEEPSEEK_API_KEY=...
```

### QWEN\_API\_KEY

**Type**: String
**Services**: LLM Service
**Hot-Reload**: Yes

Qwen API key for Alibaba Cloud models.

```bash theme={null}
QWEN_API_KEY=...
```

### MISTRAL\_API\_KEY

**Type**: String
**Services**: LLM Service
**Hot-Reload**: Yes

Mistral API key.

```bash theme={null}
MISTRAL_API_KEY=...
```

### AWS\_ACCESS\_KEY\_ID / AWS\_SECRET\_ACCESS\_KEY

**Type**: String
**Services**: LLM Service
**Hot-Reload**: Yes

AWS credentials for Bedrock models.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
GOOGLE_SEARCH_API_KEY=...
GOOGLE_SEARCH_ENGINE_ID=...
```

Obtain from: [https://console.cloud.google.com/apis/credentials](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).

```bash theme={null}
SERPER_API_KEY=...
```

Obtain from: [https://serper.dev](https://serper.dev)

### BING\_API\_KEY

**Type**: String
**Services**: LLM Service
**Hot-Reload**: Yes

Microsoft Bing Search API key.

```bash theme={null}
BING_API_KEY=...
```

### EXA\_API\_KEY

**Type**: String
**Services**: LLM Service
**Hot-Reload**: Yes

Exa AI search API key.

```bash theme={null}
EXA_API_KEY=...
```

### FIRECRAWL\_API\_KEY

**Type**: String
**Services**: LLM Service
**Hot-Reload**: Yes

Firecrawl API key for web scraping.

```bash theme={null}
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](https://www.searchapi.io).

```bash theme={null}
SEARCHAPI_API_KEY=...
```

## Data Stores

### PostgreSQL

#### POSTGRES\_HOST

**Type**: String
**Default**: `postgres`
**Services**: Gateway, Orchestrator
**Hot-Reload**: No

PostgreSQL hostname.

```bash theme={null}
POSTGRES_HOST=postgres
```

#### POSTGRES\_PORT

**Type**: Integer
**Default**: `5432`
**Range**: 1-65535
**Services**: Gateway, Orchestrator
**Hot-Reload**: No

PostgreSQL port.

```bash theme={null}
POSTGRES_PORT=5432
```

#### POSTGRES\_DB

**Type**: String
**Default**: `shannon`
**Services**: Gateway, Orchestrator
**Hot-Reload**: No

PostgreSQL database name.

```bash theme={null}
POSTGRES_DB=shannon
```

#### POSTGRES\_USER

**Type**: String
**Default**: `shannon`
**Services**: Gateway, Orchestrator
**Hot-Reload**: No

PostgreSQL username.

```bash theme={null}
POSTGRES_USER=shannon
```

#### POSTGRES\_PASSWORD

**Type**: String
**Default**: `shannon`
**Services**: Gateway, Orchestrator
**Hot-Reload**: No

PostgreSQL password.

```bash theme={null}
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.

```bash theme={null}
POSTGRES_SSLMODE=require
```

### Redis

#### REDIS\_HOST

**Type**: String
**Default**: `redis`
**Services**: All
**Hot-Reload**: No

Redis hostname.

```bash theme={null}
REDIS_HOST=redis
```

#### REDIS\_PORT

**Type**: Integer
**Default**: `6379`
**Services**: All
**Hot-Reload**: No

Redis port.

```bash theme={null}
REDIS_PORT=6379
```

#### REDIS\_PASSWORD

**Type**: String
**Default**: Empty
**Services**: All
**Hot-Reload**: No

Redis password (if authentication enabled).

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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).

```bash theme={null}
QDRANT_HOST=qdrant
QDRANT_PORT=6333
```

## Service Endpoints

### TEMPORAL\_HOST

**Type**: String
**Default**: `temporal:7233`
**Services**: Orchestrator
**Hot-Reload**: No

Temporal server address.

```bash theme={null}
TEMPORAL_HOST=temporal:7233
```

### LLM\_SERVICE\_URL

**Type**: String
**Default**: `http://llm-service:8000`
**Services**: Orchestrator, Agent Core
**Hot-Reload**: No

LLM Service endpoint.

```bash theme={null}
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.

```bash theme={null}
AGENT_CORE_ADDR=agent-core:50051
```

### ORCHESTRATOR\_GRPC

**Type**: String
**Default**: `orchestrator:50052`
**Services**: Gateway
**Hot-Reload**: No

Orchestrator gRPC endpoint.

```bash theme={null}
ORCHESTRATOR_GRPC=orchestrator:50052
```

### ADMIN\_SERVER

**Type**: String
**Default**: `http://orchestrator:8081`
**Services**: Gateway
**Hot-Reload**: No

Admin/SSE server for streaming events.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
HISTORY_WINDOW_MESSAGES=50
```

### HISTORY\_WINDOW\_DEBUG\_MESSAGES

**Type**: Integer
**Default**: `75`
**Services**: Orchestrator
**Hot-Reload**: Yes

History window size for debug mode.

```bash theme={null}
HISTORY_WINDOW_DEBUG_MESSAGES=75
```

### WORKFLOW\_SYNTH\_BYPASS\_SINGLE

**Type**: Boolean
**Default**: `true`
**Services**: Orchestrator
**Hot-Reload**: Yes

Skip synthesis for single-result workflows.

```bash theme={null}
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.

```bash theme={null}
TOKEN_BUDGET_PER_AGENT=5000
```

### TOKEN\_BUDGET\_PER\_TASK

**Type**: Integer
**Default**: Empty (unlimited)
**Services**: Orchestrator
**Hot-Reload**: Yes

Token budget per entire task.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
RATE_LIMIT_REQUESTS=100
```

### RATE\_LIMIT\_WINDOW

**Type**: Integer
**Default**: `60`
**Range**: 1-∞ (seconds)
**Services**: Gateway
**Hot-Reload**: Yes

Rate limit window duration.

```bash theme={null}
RATE_LIMIT_WINDOW=60
```

**Combined**:

```bash theme={null}
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.

```bash theme={null}
WEB_SEARCH_RATE_LIMIT=120
```

### CALCULATOR\_RATE\_LIMIT

**Type**: Integer
**Default**: `2000`
**Services**: LLM Service
**Hot-Reload**: Yes

Calculator tool requests per minute.

```bash theme={null}
CALCULATOR_RATE_LIMIT=2000
```

### PYTHON\_EXECUTOR\_RATE\_LIMIT

**Type**: Integer
**Default**: `60`
**Services**: Agent Core
**Hot-Reload**: Yes

Python code execution requests per minute.

```bash theme={null}
PYTHON_EXECUTOR_RATE_LIMIT=60
```

### PARTIAL\_CHUNK\_CHARS

**Type**: Integer
**Default**: `512`
**Services**: LLM Service
**Hot-Reload**: Yes

Characters per streaming chunk.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
PRIORITY_QUEUES=on
```

### STREAMING\_RING\_CAPACITY

**Type**: Integer
**Default**: `1000`
**Services**: Orchestrator
**Hot-Reload**: No

Ring buffer capacity for streaming events.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
COMPRESSION_TARGET_RATIO=0.375
```

### ENFORCE\_TIMEOUT\_SECONDS

**Type**: Integer
**Default**: `90`
**Services**: Agent Core
**Hot-Reload**: Yes

Tool execution timeout.

```bash theme={null}
ENFORCE_TIMEOUT_SECONDS=90
```

### ENFORCE\_MAX\_TOKENS

**Type**: Integer
**Default**: `32768`
**Services**: Agent Core
**Hot-Reload**: Yes

Maximum tokens per agent execution.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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).

```bash theme={null}
APPROVAL_TIMEOUT_SECONDS=1800
```

### JWT\_SECRET

**Type**: String
**Default**: `development-only-secret-change-in-production`
**Services**: Gateway
**Hot-Reload**: No

JWT signing secret.

```bash theme={null}
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).

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
OTEL_SERVICE_NAME=shannon-llm-service
```

### OTEL\_EXPORTER\_OTLP\_ENDPOINT

**Type**: String
**Default**: `localhost:4317`
**Services**: All
**Hot-Reload**: No

OTLP exporter endpoint.

```bash theme={null}
OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
```

### OTEL\_ENABLED

**Type**: Boolean
**Default**: `false`
**Services**: All
**Hot-Reload**: No

Enable OpenTelemetry tracing.

```bash theme={null}
OTEL_ENABLED=true
```

### LOG\_FORMAT

**Type**: String
**Default**: `plain`
**Valid Values**: `plain`, `json`
**Services**: Agent Core (Rust)
**Hot-Reload**: No

Log output format.

```bash theme={null}
LOG_FORMAT=json
```

### METRICS\_PORT

**Type**: Integer
**Default**: `2112`
**Services**: All
**Hot-Reload**: No

Prometheus metrics port.

```bash theme={null}
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.

```bash theme={null}
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).

```bash theme={null}
PYTHON_WASI_SESSION_TIMEOUT=3600
```

### WASI\_MEMORY\_LIMIT\_MB

**Type**: Integer
**Default**: `512`
**Services**: Agent Core
**Hot-Reload**: Yes

WASI sandbox memory limit (MB).

```bash theme={null}
WASI_MEMORY_LIMIT_MB=512
```

### WASI\_TIMEOUT\_SECONDS

**Type**: Integer
**Default**: `60`
**Services**: Agent Core
**Hot-Reload**: Yes

WASI execution timeout.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
OPENAPI_MAX_SPEC_SIZE=5242880
```

#### OPENAPI\_FETCH\_TIMEOUT

**Type**: Integer
**Default**: `30`
**Services**: LLM Service
**Hot-Reload**: Yes

Timeout for fetching OpenAPI specs.

```bash theme={null}
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).

```bash theme={null}
OPENAPI_RETRIES=3
```

### MCP Integration

#### MCP\_ALLOWED\_DOMAINS

**Type**: String
**Default**: `*`
**Services**: LLM Service
**Hot-Reload**: Yes

Allowed domains for MCP servers.

```bash theme={null}
MCP_ALLOWED_DOMAINS=*
```

#### MCP\_MAX\_RESPONSE\_BYTES

**Type**: Integer
**Default**: `10485760` (10 MB)
**Services**: LLM Service
**Hot-Reload**: Yes

Maximum MCP response size.

```bash theme={null}
MCP_MAX_RESPONSE_BYTES=10485760
```

#### MCP\_RETRIES

**Type**: Integer
**Default**: `3`
**Services**: LLM Service
**Hot-Reload**: Yes

MCP request retry attempts.

```bash theme={null}
MCP_RETRIES=3
```

#### MCP\_TIMEOUT\_SECONDS

**Type**: Integer
**Default**: `10`
**Services**: LLM Service
**Hot-Reload**: Yes

MCP request timeout.

```bash theme={null}
MCP_TIMEOUT_SECONDS=10
```

#### MCP\_REGISTER\_TOKEN

**Type**: String
**Default**: Empty
**Services**: LLM Service
**Hot-Reload**: Yes

Authentication token for MCP server registration.

```bash theme={null}
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).

```bash theme={null}
MCP_RATE_LIMIT_DEFAULT=60
```

#### MCP\_CB\_FAILURES

**Type**: Integer
**Default**: `5`
**Services**: LLM Service
**Hot-Reload**: Yes

Circuit breaker failure threshold for MCP.

```bash theme={null}
MCP_CB_FAILURES=5
```

#### MCP\_CB\_RECOVERY\_SECONDS

**Type**: Integer
**Default**: `60`
**Services**: LLM Service
**Hot-Reload**: Yes

Circuit breaker recovery time.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
EVENTLOG_BATCH_SIZE=100
```

### EVENTLOG\_BATCH\_INTERVAL\_MS

**Type**: Integer
**Default**: `100`
**Services**: Orchestrator
**Hot-Reload**: Yes

Batch interval (milliseconds).

```bash theme={null}
EVENTLOG_BATCH_INTERVAL_MS=100
```

### RATE\_LIMIT\_INTERVAL\_MS

**Type**: Integer
**Default**: `60000`
**Services**: Orchestrator
**Hot-Reload**: Yes

Rate limit window (milliseconds).

```bash theme={null}
RATE_LIMIT_INTERVAL_MS=60000
```

### Worker Concurrency

Configure Temporal worker concurrency per priority queue:

```bash theme={null}
# 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.

```bash theme={null}
LLM_TIMEOUT_SECONDS=120
```

## Miscellaneous

### SHANNON\_WORKSPACE

**Type**: String
**Default**: `./workspace`
**Services**: Agent Core
**Hot-Reload**: No

Workspace directory for file operations.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
SHANNON_MAX_WORKSPACE_SIZE_MB=100
```

### SEED\_DATA

**Type**: Boolean
**Default**: `false`
**Services**: All
**Hot-Reload**: No

Seed Qdrant with sample data on startup.

```bash theme={null}
SEED_DATA=true
```

### AGENT\_TIMEOUT\_SECONDS

**Type**: Integer
**Default**: `600`
**Services**: Agent Core
**Hot-Reload**: Yes

Maximum runtime per agent execution.

```bash theme={null}
AGENT_TIMEOUT_SECONDS=600
```

## Configuration Examples

### Development

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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](/en/deployment/configuration-troubleshooting) for common issues.

## Related Documentation

<CardGroup cols={2}>
  <Card title="Docker Compose" icon="docker" href="/en/deployment/docker-compose">
    Docker deployment guide
  </Card>

  <Card title="Kubernetes" icon="cubes" href="/en/deployment/kubernetes">
    Kubernetes deployment
  </Card>

  <Card title="Performance Tuning" icon="gauge" href="/en/deployment/performance-tuning">
    Optimize performance
  </Card>

  <Card title="Security" icon="shield" href="/en/deployment/security">
    Security hardening
  </Card>
</CardGroup>