Skip to main content
Documentation
DOCS · CLI REFERENCE

Configuration File

Configure Ralph Workflow with ralph-workflow.toml for agents, fallbacks, and behavior customization.

Configuration File

Ralph Workflow uses TOML configuration files to customize its behavior.

Configuration Locations

Ralph looks for configuration in two places:

  1. Global config: ~/.config/ralph-workflow.toml
  2. Project config: .ralph-workflow.toml in your project root

Project configuration overrides global settings.

Full Example

# ~/.config/ralph-workflow.toml

# Pipeline behavior
max_dev_continuations = 5    # Max development iterations
max_xsd_retries = 3          # Max XML validation retries
idle_timeout_seconds = 300   # Agent timeout (5 minutes)

# Developer agent configuration
[developer]
fallback_chain = ["opencode", "ccs"]

# Reviewer agent configuration
[reviewer]
fallback_chain = ["ccs", "opencode"]

# Backoff configuration for rate limits
[backoff]
initial_delay_ms = 1000
max_delay_ms = 60000
multiplier = 2.0

Configuration Options

Pipeline Settings

Option Type Default Description
max_dev_continuations integer 5 Maximum development iterations
max_xsd_retries integer 3 Maximum XML validation retries
idle_timeout_seconds integer 300 Timeout for agent responses

Iteration Limits

Setting max_dev_continuations too high can lead to long-running workflows. Start with the default and increase if needed.

Agent Fallback Chains

Configure which agents to use and in what order:

[developer]
fallback_chain = ["opencode", "ccs"]

[reviewer]
fallback_chain = ["ccs", "opencode"]

When an agent fails (rate limit, auth error, etc.), Ralph tries the next agent in the chain.

Backoff Settings

Configure retry behavior for transient failures:

[backoff]
initial_delay_ms = 1000   # Start with 1 second delay
max_delay_ms = 60000      # Cap at 60 seconds
multiplier = 2.0          # Double delay each retry

Environment Variables

Some settings can be overridden with environment variables:

Variable Description
RALPH_CONFIG Path to config file
RALPH_LOG_LEVEL Logging verbosity (debug, info, warn, error) 
$ RALPH_LOG_LEVEL=debug ralph

Project-Specific Config

Create .ralph-workflow.toml in your project root for project-specific settings:

# .ralph-workflow.toml

# This project needs more iterations for complex tasks
max_dev_continuations = 10

# Only use opencode for this project
[developer]
fallback_chain = ["opencode"]

Next Steps

Loading…