Configuration Reference

Complete reference for configuring Orchestre projects, models, and environment.

Configuration Overview

Orchestre uses a simple, distributed configuration approach:

1. Environment Variables - API keys and runtime settings in .env files
2. Model Configuration - LLM preferences in models.config.json
3. Template Configuration - Template metadata in template.json
4. Memory System - Project context in CLAUDE.md files

Configuration Files

Project Structure

my-project/
├── .env                    # API keys and settings (git-ignored)
├── CLAUDE.md              # Project memory and context
├── models.config.json     # LLM model configuration (optional)
└── template.json          # Template metadata (if from template)

Quick Start

Minimal Configuration

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

Full Configuration

# .env
# API Keys (at least one required)
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx
GEMINI_API_KEY=AIzaSyxxx

# Optional Settings
ORCHESTRE_DEBUG=false
ORCHESTRE_LOG_LEVEL=info

// models.config.json (optional)
{
  "primary": "claude-3-opus",
  "planning": "gemini-2.0-flash-thinking-exp",
  "review": ["gpt-4o", "claude-3-sonnet"]
}

Configuration Sections

Environment Variables

• API key setup
• Runtime options
• Debug settings
• Provider configuration

Model Configuration

• LLM selection in models.config.json
• Model parameters
• Provider settings
• Cost optimization

Memory System

• Project context in CLAUDE.md
• Distributed documentation
• Knowledge preservation
• Team collaboration

Configuration Precedence

Configuration is resolved in this order (highest to lowest priority):

1. Environment variables
2. Command-line arguments
3. models.config.json
4. Template defaults (template.json)
5. System defaults

Dynamic Configuration

Runtime Settings

Orchestre adapts based on:

1. Environment Variables: Set before running

   export ORCHESTRE_DEBUG=true
   export ORCHESTRE_LOG_LEVEL=debug

2. Project Context: Discovered from CLAUDE.md files

   /discover-context  # Find existing documentation
   /document-feature  # Add new context

3. Template Configuration: Set during initialization

   // template.json
   {
     "name": "makerkit-nextjs",
     "description": "SaaS starter kit",
     "commands": ["add-feature", "setup-stripe", ...]
   }

Best Practices

1. Version Control

Commit documentation, not secrets:

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

# DO commit
CLAUDE.md
models.config.json
template.json

2. Environment Management

Use different .env files for different contexts:

# Development
cp .env.example .env
# Add your personal API keys

# Production (in deployment platform)
# Set environment variables directly

3. Secure Secrets

Always use environment variables for sensitive data:

# ❌ Don't commit API keys
# ✅ Use environment variables
ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx

4. Document Context

Use CLAUDE.md for project knowledge:

# Project Architecture

This SaaS application uses:
- Next.js for the frontend
- PostgreSQL for data storage
- Stripe for payments

## Key Decisions
- Multi-tenant architecture with team workspaces
- JWT-based authentication

Migration

From Earlier Versions

Orchestre 3.x uses a simpler configuration approach:

1. Memory System: Uses distributed CLAUDE.md files throughout your project
2. Configuration: Environment variables instead of complex config files
3. Commands: Natural language prompts instead of rigid automation

# Migrate existing project
/orchestrate "Update this project to use Orchestre's distributed memory system"

Troubleshooting

Common Issues

Configuration not loading?

• Check file location: .orchestre/config.yaml
• Validate YAML syntax
• Ensure correct version

Settings not taking effect?

• Restart Claude Code
• Check precedence order
• Verify environment variables

Template conflicts?

• Review template.json
• Check variant configuration
• Validate dependencies

Examples

SaaS Project Setup

# 1. Initialize with template
/create "saas-platform" using makerkit-nextjs

# 2. Set environment variables
echo "ANTHROPIC_API_KEY=sk-ant-xxx" >> .env
echo "OPENAI_API_KEY=sk-xxx" >> .env

# 3. Document architecture in CLAUDE.md
/document-feature "Multi-tenant SaaS with Stripe billing"

API Service Setup

# 1. Initialize with template
/create "api-service" using cloudflare-hono

# 2. Configure for edge deployment
/orchestrate "Set up this API for global edge deployment"

Mobile App Setup

# 1. Initialize with template
/create "fitness-app" using react-native-expo

# 2. Configure features
/orchestrate "Add offline sync and push notifications"

See Also

• Getting Started
• Project Structure
• Template Guide
• Environment Setup