Tutorial 2: Configuration

Learn how to configure thegent for your specific needs.

Overview

Thegent uses a .env file for configuration. You can:

• Use the interactive wizard (thegent config wizard)
• Edit .env directly
• Use environment variables

Configuration Wizard

The easiest way to configure thegent:

thegent config wizard

This interactive wizard guides you through:

1. Basic settings (MCP host, port, directories)
2. Model defaults
3. Performance settings
4. Budget settings
5. Advanced settings

Manual Configuration

Edit .env file directly:

# Basic Configuration
THGENT_MCP_HOST=127.0.0.1
THGENT_MCP_PORT=3847
THGENT_SESSION_DIR=~/.cache/thegent/sessions
THGENT_CACHE_DIR=~/.cache/thegent

# Model Defaults
THGENT_DEFAULT_CURSOR_MODEL=gemini-3-flash
THGENT_DEFAULT_GEMINI_MODEL=gemini-3-flash
THGENT_DEFAULT_COPILOT_MODEL=gpt-5-mini
THGENT_DEFAULT_CLAUDE_MODEL=claude-opus-4.6
THGENT_DEFAULT_CODEX_MODEL=gpt-5.3-codex-spark

# Performance
THGENT_DEFAULT_TIMEOUT=1800
THGENT_MAX_IDLE_SECONDS=180
THGENT_DEFAULT_ROUTING=prefer_direct

# Budget (optional)
THGENT_BUDGET_HOURLY_LIMIT=10.0
THGENT_BUDGET_DAILY_LIMIT=100.0
THGENT_BUDGET_RUN_LIMIT=5.0

Environment Variables

You can also set configuration via environment variables:

export THGENT_MCP_HOST=127.0.0.1
export THGENT_MCP_PORT=3847
thegent run "test"

Environment variables take precedence over .env file.

Validation

Validate your configuration:

thegent config validate

This checks:

• Required settings are present
• Values are within valid ranges
• File paths exist or can be created
• Model names are valid

Configuration Migration

Migrate from old configuration format:

thegent config migrate --source .env.old --target .env.new --dry-run

Review the migration, then apply:

thegent config migrate --source .env.old --target .env.new

Viewing Configuration

Show current configuration:

thegent config show

This displays:

• Current settings
• Source (env file or default)
• Resolved values

Common Settings

MCP Server

THGENT_MCP_HOST=127.0.0.1
THGENT_MCP_PORT=3847

Timeouts

# Default timeout (30 minutes)
THGENT_DEFAULT_TIMEOUT=1800

# Max idle time (3 minutes)
THGENT_MAX_IDLE_SECONDS=180

Routing

# Options: prefer_direct, prefer_proxy, failover
THGENT_DEFAULT_ROUTING=prefer_direct

Budget Limits

THGENT_BUDGET_HOURLY_LIMIT=10.0
THGENT_BUDGET_DAILY_LIMIT=100.0
THGENT_BUDGET_RUN_LIMIT=5.0
THGENT_BUDGET_WARNING_THRESHOLD=0.8

Environment-Specific Configs

Use different configs for different environments:

# Development
thegent config wizard --config .env.development

# Production
thegent config wizard --config .env.production

# Use specific config
THGENT_ENV_FILE=.env.production thegent run "test"

Next Steps

• First Agent Run - Run your first agent
• Performance Optimization - Optimize settings
• Governance & Policies - Set up governance

Troubleshooting

Invalid Configuration

# Validate and see errors
thegent config validate

# Fix issues
thegent config wizard

Configuration Not Loading

# Check file exists
ls -la .env

# Check permissions
chmod 644 .env

# Verify format
cat .env | grep THGENT_