Environment Variables

Configure Orchestre's runtime environment for API access, debugging, and customization.

Overview

Environment variables control:

• API keys for LLM providers
• Runtime behavior
• Debug settings
• Feature flags

Required Variables

API Keys

# At least one LLM provider is required
ANTHROPIC_API_KEY=sk-ant-xxx      # For Claude models
OPENAI_API_KEY=sk-xxx              # For GPT models
GEMINI_API_KEY=xxx                 # For Gemini models

MCP Server Configuration

{
  "mcpServers": {
    "orchestre": {
      "command": "node",
      "args": ["path/to/orchestre/dist/server.js"],
      "env": {
        "ANTHROPIC_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key",
        "GEMINI_API_KEY": "your-key"
      }
    }
  }
}

Configuration Methods

1. Environment File (.env)

# .env
ANTHROPIC_API_KEY=sk-ant-api03-xxx
OPENAI_API_KEY=sk-proj-xxx
GEMINI_API_KEY=AIzaSyxxx

# Optional settings
ORCHESTRE_DEBUG=true
ORCHESTRE_LOG_LEVEL=info

2. Shell Export

# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-api03-xxx"
export OPENAI_API_KEY="sk-proj-xxx"
export GEMINI_API_KEY="AIzaSyxxx"

3. Claude Code Configuration

{
  "mcpServers": {
    "orchestre": {
      "env": {
        "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}",
        "OPENAI_API_KEY": "${env:OPENAI_API_KEY}",
        "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
      }
    }
  }
}

Variable Reference

API Keys

ANTHROPIC_API_KEY

• Required: If using Claude models
• Format: sk-ant-api03-xxx
• Get from: Anthropic Console

OPENAI_API_KEY

• Required: If using GPT models
• Format: sk-proj-xxx or sk-xxx
• Get from: OpenAI Platform

GEMINI_API_KEY

• Required: If using Gemini models
• Format: AIzaSyxxx
• Get from: Google AI Studio

Runtime Settings

ORCHESTRE_DEBUG

• Type: boolean
• Default: false
• Description: Enable debug output

ORCHESTRE_DEBUG=true

ORCHESTRE_LOG_LEVEL

• Type: string
• Values: error, warn, info, debug, verbose
• Default: info

ORCHESTRE_LOG_LEVEL=debug

ORCHESTRE_CACHE_DIR

• Type: string
• Default: ~/.orchestre/cache
• Description: Directory for caching responses

ORCHESTRE_CACHE_DIR=/tmp/orchestre-cache

ORCHESTRE_TIMEOUT

• Type: number (milliseconds)
• Default: 30000
• Description: Global timeout for operations

ORCHESTRE_TIMEOUT=60000  # 1 minute

Feature Flags

ORCHESTRE_PARALLEL_AGENTS

• Type: number
• Default: 3
• Range: 1-10
• Description: Maximum parallel work streams

ORCHESTRE_PARALLEL_AGENTS=5

ORCHESTRE_AUTO_REVIEW

• Type: boolean
• Default: true
• Description: Automatic code review after changes

ORCHESTRE_AUTO_REVIEW=false

ORCHESTRE_DISTRIBUTED_MEMORY

• Type: boolean
• Default: true
• Description: Use distributed CLAUDE.md files

ORCHESTRE_DISTRIBUTED_MEMORY=true

Provider-Specific

OpenAI Organization

OPENAI_ORG_ID=org-xxx
OPENAI_API_BASE=https://api.openai.com/v1

Anthropic Beta Features

ANTHROPIC_BETA=messages-2023-12-15

Gemini Safety Settings

GEMINI_SAFETY_THRESHOLD=BLOCK_NONE

Environment-Specific Configuration

Development

# .env.development
ORCHESTRE_DEBUG=true
ORCHESTRE_LOG_LEVEL=debug
ORCHESTRE_AUTO_REVIEW=false
ORCHESTRE_CACHE_ENABLED=false

Production

# .env.production
ORCHESTRE_DEBUG=false
ORCHESTRE_LOG_LEVEL=warn
ORCHESTRE_AUTO_REVIEW=true
ORCHESTRE_CACHE_ENABLED=true

Testing

# .env.test
ORCHESTRE_USE_MOCK_LLMS=true
ORCHESTRE_TEST_MODE=true
ORCHESTRE_LOG_LEVEL=error

Security Best Practices

1. Never Commit Secrets

# .gitignore
.env
.env.local
.env.*.local

2. Use Secret Management

# Use system keychain
ANTHROPIC_API_KEY=$(security find-generic-password -s "anthropic-api-key" -w)

# Use 1Password CLI
OPENAI_API_KEY=$(op read "op://Development/OpenAI/api_key")

# Use AWS Secrets Manager
GEMINI_API_KEY=$(aws secretsmanager get-secret-value --secret-id gemini-key --query SecretString --output text)

3. Rotate Keys Regularly

# Check key age
echo "Key created: $(date -r ~/.anthropic_key)"

# Update keys monthly
crontab -e
0 0 1 * * /path/to/rotate-api-keys.sh

4. Restrict Key Permissions

# Limit API key scopes when possible
OPENAI_API_KEY=sk-proj-xxx  # Project-scoped key

Debugging

Check Environment

# List Orchestre variables
env | grep ORCHESTRE_

# Check API keys (safely)
echo "ANTHROPIC_API_KEY is $([ -z "$ANTHROPIC_API_KEY" ] && echo "not set" || echo "set")"
echo "OPENAI_API_KEY is $([ -z "$OPENAI_API_KEY" ] && echo "not set" || echo "set")"
echo "GEMINI_API_KEY is $([ -z "$GEMINI_API_KEY" ] && echo "not set" || echo "set")"

Enable Debug Mode

# Verbose output
ORCHESTRE_DEBUG=true ORCHESTRE_LOG_LEVEL=verbose

# Log API calls
ORCHESTRE_LOG_API_CALLS=true

# Save debug logs
ORCHESTRE_DEBUG_FILE=/tmp/orchestre-debug.log

Common Issues

API Key Not Found

# Error: ANTHROPIC_API_KEY not found

# Fix: Set the variable
export ANTHROPIC_API_KEY="your-key"

# Or use .env file
echo "ANTHROPIC_API_KEY=your-key" >> .env

Permission Denied

# Error: Permission denied accessing cache

# Fix: Set writable cache directory
export ORCHESTRE_CACHE_DIR="$HOME/.orchestre/cache"
mkdir -p "$ORCHESTRE_CACHE_DIR"

Rate Limit Errors

# Reduce parallel operations
export ORCHESTRE_PARALLEL_AGENTS=1

# Add delay between requests
export ORCHESTRE_RATE_LIMIT_DELAY=2000

Platform-Specific Setup

macOS

# Add to ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-xxx"
export OPENAI_API_KEY="sk-xxx"
export GEMINI_API_KEY="AIzaSyxxx"

# Use launchd for persistence
launchctl setenv ANTHROPIC_API_KEY "sk-ant-xxx"

Linux

# Add to ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-xxx"
export OPENAI_API_KEY="sk-xxx"
export GEMINI_API_KEY="AIzaSyxxx"

# System-wide in /etc/environment
ANTHROPIC_API_KEY="sk-ant-xxx"
OPENAI_API_KEY="sk-xxx"
GEMINI_API_KEY="AIzaSyxxx"

Windows

# PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-xxx"
$env:OPENAI_API_KEY = "sk-xxx"
$env:GEMINI_API_KEY = "AIzaSyxxx"

# Permanent (requires admin)
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-xxx", "User")

CI/CD Integration

GitHub Actions

# .github/workflows/deploy.yml
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

Docker

# Dockerfile
ARG ANTHROPIC_API_KEY
ARG OPENAI_API_KEY
ARG GEMINI_API_KEY

ENV ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY
ENV OPENAI_API_KEY=$OPENAI_API_KEY
ENV GEMINI_API_KEY=$GEMINI_API_KEY

# Build with args
docker build \
  --build-arg ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
  --build-arg OPENAI_API_KEY="$OPENAI_API_KEY" \
  --build-arg GEMINI_API_KEY="$GEMINI_API_KEY" \
  -t orchestre-app .

Advanced Configuration

Proxy Settings

# HTTP proxy
HTTP_PROXY=http://proxy.company.com:8080
HTTPS_PROXY=http://proxy.company.com:8080

# API-specific proxies
ANTHROPIC_PROXY=http://anthropic-proxy:8080
OPENAI_PROXY=http://openai-proxy:8080

Custom Endpoints

# Use custom API endpoints
ANTHROPIC_API_BASE=https://custom-anthropic-api.com
OPENAI_API_BASE=https://custom-openai-api.com
GEMINI_API_BASE=https://custom-gemini-api.com

Telemetry Control

# Disable telemetry
ORCHESTRE_TELEMETRY_DISABLED=true

# Custom telemetry endpoint
ORCHESTRE_TELEMETRY_ENDPOINT=https://your-telemetry.com

Migration from v2

# v2 environment variables
ORCHESTRE_API_KEY=xxx
ORCHESTRE_MODEL=gpt-4

# v3 environment variables
OPENAI_API_KEY=xxx
# Model selection now in config.yaml

See Also

• Configuration Overview
• Project Configuration
• Model Configuration
• Security Best Practices