Configuration Guide¶

Ralph Orchestrator provides extensive configuration options to control execution, manage costs, and ensure safe operation. This guide covers all configuration parameters and best practices.

Configuration Methods¶

1. Command Line Arguments¶

The primary way to configure Ralph Orchestrator is through command-line arguments:

python ralph_orchestrator.py --agent claude --max-iterations 50 --max-cost 25.0

2. Environment Variables¶

Some settings can be configured via environment variables:

export RALPH_AGENT=claude
export RALPH_MAX_COST=25.0
python ralph_orchestrator.py

3. Configuration File (Future)¶

Configuration file support is planned for future releases.

Core Configuration Options¶

Agent Selection¶

Parameter	Default	Description
`--agent`	`auto`	AI agent to use: `claude`, `q`, `gemini`, `acp`, or `auto`
`--agent-args`	None	Additional arguments to pass to the agent
`--acp-agent`	`gemini`	ACP agent command (for `-a acp`)
`--acp-permission-mode`	`auto_approve`	Permission handling: `auto_approve`, `deny_all`, `allowlist`, `interactive`

Example:

# Use Claude specifically
python ralph_orchestrator.py --agent claude

# Auto-detect available agent
python ralph_orchestrator.py --agent auto

# Pass additional arguments to agent
python ralph_orchestrator.py --agent claude --agent-args "--model claude-3-sonnet"

# Use ACP-compliant agent
python ralph_orchestrator.py --agent acp --acp-agent gemini

# Use ACP with specific permission mode
python ralph_orchestrator.py --agent acp --acp-agent gemini --acp-permission-mode deny_all

Prompt Configuration¶

Parameter	Default	Description
`--prompt`	`PROMPT.md`	Path to the prompt file
`--max-prompt-size`	10MB	Maximum allowed prompt file size

Example:

# Use custom prompt file
python ralph_orchestrator.py --prompt tasks/my-task.md

# Set maximum prompt size (in bytes)
python ralph_orchestrator.py --max-prompt-size 5242880  # 5MB

Execution Limits¶

Iteration and Runtime¶

Parameter	Default	Description
`--max-iterations`	100	Maximum number of iterations
`--max-runtime`	14400	Maximum runtime in seconds (4 hours)

Example:

# Quick task with few iterations
python ralph_orchestrator.py --max-iterations 10 --max-runtime 600

# Long-running task
python ralph_orchestrator.py --max-iterations 500 --max-runtime 86400  # 24 hours

Token and Cost Management¶

Parameter	Default	Description
`--max-tokens`	1,000,000	Maximum total tokens to use
`--max-cost`	50.0	Maximum cost in USD
`--context-window`	200,000	Context window size in tokens
`--context-threshold`	0.8	Trigger summarization at this % of context

Example:

# Budget-conscious configuration
python ralph_orchestrator.py \
  --max-tokens 100000 \
  --max-cost 5.0 \
  --context-window 100000

# High-capacity configuration
python ralph_orchestrator.py \
  --max-tokens 5000000 \
  --max-cost 200.0 \
  --context-window 500000

Checkpointing and Recovery¶

Parameter	Default	Description
`--checkpoint-interval`	5	Iterations between checkpoints
`--no-git`	False	Disable git checkpointing
`--no-archive`	False	Disable prompt archiving

Example:

# Frequent checkpoints for critical tasks
python ralph_orchestrator.py --checkpoint-interval 1

# Disable git operations (for non-git directories)
python ralph_orchestrator.py --no-git

# Minimal persistence
python ralph_orchestrator.py --no-git --no-archive

Monitoring and Debugging¶

Parameter	Default	Description
`--metrics-interval`	10	Iterations between metrics logs
`--no-metrics`	False	Disable metrics collection
`--verbose`	False	Enable verbose logging
`--dry-run`	False	Test configuration without execution

Example:

# Verbose monitoring
python ralph_orchestrator.py --verbose --metrics-interval 1

# Test configuration
python ralph_orchestrator.py --dry-run --verbose

# Minimal logging
python ralph_orchestrator.py --no-metrics

Security Options¶

Parameter	Default	Description
`--allow-unsafe-paths`	False	Allow potentially unsafe file paths

Example:

# Standard security (recommended)
python ralph_orchestrator.py

# Allow unsafe paths (use with caution)
python ralph_orchestrator.py --allow-unsafe-paths

Retry and Recovery¶

Parameter	Default	Description
`--retry-delay`	2	Delay between retries in seconds

Example:

# Slower retry for rate-limited APIs
python ralph_orchestrator.py --retry-delay 10

# Fast retry for local agents
python ralph_orchestrator.py --retry-delay 1

ACP (Agent Client Protocol) Configuration¶

ACP Options¶

Parameter	Default	Description
`--acp-agent`	`gemini`	Command to run the ACP-compliant agent
`--acp-permission-mode`	`auto_approve`	Permission handling mode

Permission Modes¶

Mode	Description	Use Case
`auto_approve`	Approve all tool requests automatically	Trusted environments, CI/CD
`deny_all`	Deny all tool requests	Testing, sandboxed execution
`allowlist`	Only approve matching patterns	Production with specific tools
`interactive`	Prompt user for each request	Development, manual oversight

Configuration File (ralph.yml)¶

adapters:
  acp:
    enabled: true
    timeout: 300
    tool_permissions:
      agent_command: gemini        # ACP agent CLI command
      agent_args: []               # Additional CLI arguments
      permission_mode: auto_approve
      permission_allowlist:        # For allowlist mode
        - "fs/read_text_file:*.py"
        - "fs/write_text_file:src/*"
        - "terminal/create:pytest*"

Environment Variables¶

Variable	Description
`RALPH_ACP_AGENT`	Override `agent_command`
`RALPH_ACP_PERMISSION_MODE`	Override `permission_mode`
`RALPH_ACP_TIMEOUT`	Override `timeout` (integer)

Example:

# Using environment variables
export RALPH_ACP_AGENT=gemini
export RALPH_ACP_PERMISSION_MODE=deny_all
python ralph_orchestrator.py --agent acp

ACP Profile¶

For ACP-compliant agents:

python ralph_orchestrator.py \
  --agent acp \
  --acp-agent gemini \
  --acp-permission-mode auto_approve \
  --max-iterations 100 \
  --max-runtime 14400

Configuration Profiles¶

Development Profile¶

For local development and testing:

python ralph_orchestrator.py \
  --agent q \
  --max-iterations 10 \
  --max-cost 1.0 \
  --verbose \
  --checkpoint-interval 1 \
  --metrics-interval 1

Production Profile¶

For production workloads:

python ralph_orchestrator.py \
  --agent claude \
  --max-iterations 100 \
  --max-runtime 14400 \
  --max-tokens 1000000 \
  --max-cost 50.0 \
  --checkpoint-interval 5 \
  --metrics-interval 10

Budget Profile¶

For cost-sensitive operations:

python ralph_orchestrator.py \
  --agent q \
  --max-tokens 50000 \
  --max-cost 2.0 \
  --context-window 50000 \
  --context-threshold 0.7

High-Performance Profile¶

For complex, resource-intensive tasks:

python ralph_orchestrator.py \
  --agent claude \
  --max-iterations 500 \
  --max-runtime 86400 \
  --max-tokens 5000000 \
  --max-cost 500.0 \
  --context-window 500000 \
  --checkpoint-interval 10

Configuration Best Practices¶

1. Start Conservative¶

Begin with lower limits and increase as needed:

# Start small
python ralph_orchestrator.py --max-iterations 5 --max-cost 1.0

# Increase if needed
python ralph_orchestrator.py --max-iterations 50 --max-cost 10.0

2. Use Dry Run¶

Always test configuration before production:

python ralph_orchestrator.py --dry-run --verbose

3. Monitor Metrics¶

Enable metrics for production workloads:

python ralph_orchestrator.py --metrics-interval 5 --verbose

4. Set Appropriate Limits¶

Choose limits based on task complexity:

Simple tasks: 10-20 iterations, $1-5 cost
Medium tasks: 50-100 iterations, $10-25 cost
Complex tasks: 100-500 iterations, $50-200 cost

5. Checkpoint Frequently¶

For long-running tasks, checkpoint often:

python ralph_orchestrator.py --checkpoint-interval 3

Environment-Specific Configuration¶

CI/CD Pipelines¶

python ralph_orchestrator.py \
  --agent auto \
  --max-iterations 50 \
  --max-runtime 3600 \
  --no-git \
  --metrics-interval 10

Docker Containers¶

ENV RALPH_AGENT=claude
ENV RALPH_MAX_COST=25.0
CMD ["python", "ralph_orchestrator.py", "--no-git", "--max-runtime", "7200"]

Kubernetes¶

apiVersion: v1
kind: ConfigMap
metadata:
  name: ralph-config
data:
  RALPH_AGENT: "claude"
  RALPH_MAX_COST: "50.0"
  RALPH_MAX_ITERATIONS: "100"

Troubleshooting Configuration¶

Common Issues¶

Agent not found
Solution: Check agent installation with --agent auto
Exceeding cost limits
Solution: Increase --max-cost or use cheaper agent
Context overflow
Solution: Decrease --context-threshold or increase --context-window
Slow performance
Solution: Increase --checkpoint-interval and --metrics-interval

Debug Commands¶

# Check configuration
python ralph_orchestrator.py --dry-run --verbose

# List available agents
python ralph_orchestrator.py --agent auto --dry-run

# Test with minimal configuration
python ralph_orchestrator.py --max-iterations 1 --verbose

Configuration Reference¶

For a complete list of all configuration options, run:

python ralph_orchestrator.py --help

Next Steps¶

Learn about AI Agents and their capabilities
Understand Prompt Engineering for better results
Explore Cost Management strategies
Set up Checkpointing for recovery