DocsGetting StartedConfiguration

Configuration

Ryvos uses a single TOML file. It looks for config in this order:

  1. ryvos.toml in the current directory
  2. ~/.ryvos/config.toml
  3. Path set by RYVOS_CONFIG environment variable

Run ryvos config to print the fully resolved configuration.

Minimal Config

[model]
provider = "anthropic"
model_id = "claude-sonnet-4-20250514"
api_key = "${ANTHROPIC_API_KEY}"

That's it. Everything else has sensible defaults.

Model

[model]
provider = "anthropic"          # anthropic, openai, ollama, or any OpenAI-compatible
model_id = "claude-sonnet-4-20250514"
api_key = "${ANTHROPIC_API_KEY}" # Env var expansion with ${VAR}
base_url = ""                    # Override for Ollama/vLLM/Groq etc.
max_tokens = 8192
temperature = 0.0
thinking = "off"                 # off, low, medium, high
 
[model.retry]
max_retries = 3
initial_backoff_ms = 1000
max_backoff_ms = 30000

Provider examples:

# Ollama (local)
[model]
provider = "ollama"
model_id = "llama3.1:8b"
base_url = "http://localhost:11434/v1"
 
# OpenAI
[model]
provider = "openai"
model_id = "gpt-4o"
api_key = "${OPENAI_API_KEY}"
 
# Groq (OpenAI-compatible)
[model]
provider = "openai"
model_id = "llama-3.1-70b-versatile"
base_url = "https://api.groq.com/openai/v1"
api_key = "${GROQ_API_KEY}"

Agent

[agent]
max_turns = 25                 # Max conversation turns per run
max_duration_secs = 600        # Hard timeout
workspace = "~/.ryvos"         # Working directory
system_prompt = ""             # Path to custom system prompt file
max_context_tokens = 80000     # Context window limit
max_tool_output_tokens = 4000  # Truncate long tool outputs
reflexion_failure_threshold = 3 # Failures before self-healing kicks in
parallel_tools = true          # Run independent tools concurrently
enable_summarization = true    # Compress old messages to save context
enable_self_eval = false       # LLM-as-judge response scoring

Security

[security]
auto_approve_up_to = "t1"      # T0-T1 run without asking
deny_above = null               # Set to "t3" to block T4+ entirely
approval_timeout_secs = 60
 
# Custom dangerous patterns (added to built-in 9)
dangerous_patterns = [
    { pattern = "rm -rf", label = "delete" }
]
 
[security.sub_agent_policy]
auto_approve_up_to = "t0"      # Spawned agents are more restricted
deny_above = "t2"

Sandbox

[agent.sandbox]
enabled = false                 # Enable Docker sandboxing
mode = "docker"
image = "ubuntu:24.04"
memory_mb = 512
timeout_secs = 120
mount_workspace = true

Guardian (Watchdog)

[agent.guardian]
enabled = true
doom_loop_threshold = 3         # Repeated identical tool calls
stall_timeout_secs = 120        # No progress timeout
token_budget = 0                # 0 = unlimited
token_warn_pct = 80             # Soft warning percentage

Channels

[channels.telegram]
bot_token = "${TELEGRAM_BOT_TOKEN}"
allowed_users = [123456789]
dm_policy = "allowlist"         # allowlist, open, disabled
 
[channels.discord]
bot_token = "${DISCORD_BOT_TOKEN}"
dm_policy = "allowlist"
allowed_users = [123456789012345678]
 
[channels.slack]
bot_token = "${SLACK_BOT_TOKEN}"
app_token = "${SLACK_APP_TOKEN}"
dm_policy = "allowlist"
allowed_users = ["U01234ABC"]

Gateway (Web UI)

[gateway]
bind = "127.0.0.1:18789"
 
[[gateway.api_keys]]
name = "web-ui"
key = "rk_abc123"
role = "operator"               # viewer, operator, admin

Hooks

[hooks]
on_start = ["notify-send 'Ryvos started'"]
on_message = []
on_tool_call = []
on_response = []
on_turn_complete = []
on_tool_error = []
on_session_start = []
on_session_end = []

Cron Jobs

[[cron.jobs]]
name = "daily_report"
schedule = "0 9 * * *"
prompt = "Generate a daily summary of my git activity"
channel = "telegram"

Environment Variables

All string config values support ${VAR} expansion. The variable is resolved at config load time. If the variable is not set, the literal ${VAR} string is kept.

Next Steps