Configuration Reference

Risoluto’s configuration is layered with this merge order (last wins):

Built-in defaults — sensible out-of-the-box configuration
Persistent overlay — ~/.risoluto/config/overlay.yaml (or $DATA_DIR/config/overlay.yaml)
Environment variables and $SECRET:name resolution at runtime

Managing Configuration

API
Dashboard
YAML File

# View effective (merged) config
curl -s http://127.0.0.1:4000/api/v1/config

# View overlay only
curl -s http://127.0.0.1:4000/api/v1/config/overlay

# Update overlay (deep merge)
curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"model":"gpt-5.4","reasoningEffort":"high"}}'

# Patch a single path
curl -s -X PATCH http://127.0.0.1:4000/api/v1/config/overlay/agent.maxConcurrentAgents \
  -H 'Content-Type: application/json' \
  -d '{"value": 5}'

# Delete an overlay key
curl -s -X DELETE http://127.0.0.1:4000/api/v1/config/overlay/codex.personality

# View config schema (JSON Schema)
curl -s http://127.0.0.1:4000/api/v1/config/schema

Edit the overlay file directly:

# ~/.risoluto/config/overlay.yaml
server:
  port: 4000
codex:
  model: gpt-5.4
  reasoningEffort: high
agent:
  maxConcurrentAgents: 5
workspace:
  strategy: worktree

Overlay changes via the API or dashboard are persisted to disk and survive restarts. You never need to restart Risoluto after a config change — the orchestrator reloads automatically.

Configuration Sections

Server & Polling

Key	Type	Default	Description
`server.port`	number	`4000`	HTTP server port
`polling.intervalMs`	number	`15000`	Tracker polling interval in milliseconds

Tracker

Key	Type	Default	Description
`tracker.kind`	string	`"linear"`	Tracker provider (`"linear"` or `"github"`)
`tracker.apiKey`	string	`""`	Tracker API key (prefer `$SECRET:LINEAR_API_KEY`)
`tracker.endpoint`	string	`"https://api.linear.app/graphql"`	Tracker GraphQL endpoint
`tracker.projectSlug`	string	`null`	Linear project slug to watch
`tracker.owner`	string	`""`	GitHub owner (when `kind: "github"`)
`tracker.repo`	string	`""`	GitHub repo (when `kind: "github"`)
`tracker.activeStates`	string[]	`["Backlog", "Todo", "In Progress"]`	States that trigger agent dispatch
`tracker.terminalStates`	string[]	`["Done", "Canceled"]`	States that mark issues as complete

Agent (Orchestrator)

Key	Type	Default	Description
`agent.maxConcurrentAgents`	number	`10`	Maximum simultaneous agent workers
`agent.maxConcurrentAgentsByState`	object	`{}`	Per-state concurrency limits (e.g. `{"In Progress": 3}`)
`agent.maxTurns`	number	`20`	Max conversation turns per agent run
`agent.maxRetryBackoffMs`	number	`300000`	Maximum retry backoff (5 min)
`agent.maxContinuationAttempts`	number	`5`	Max continuation turns after initial run
`agent.successState`	string	`null`	Linear state to transition to on success
`agent.stallTimeoutMs`	number	`1200000`	Agent stall detection timeout (20 min)
`agent.preflightCommands`	string[]	`[]`	Shell commands to run before each agent turn

Codex (Agent Provider)

Key	Type	Default	Description
`codex.command`	string	`"codex app-server"`	Command to start the Codex agent
`codex.model`	string	`"gpt-5.4"`	Model identifier
`codex.reasoningEffort`	enum	`"high"`	`none`, `minimal`, `low`, `medium`, `high`, `xhigh`
`codex.personality`	string	`"friendly"`	Agent personality/tone
`codex.selfReview`	boolean	`false`	Enable agent self-review before completing
`codex.structuredOutput`	boolean	`false`	Enable structured output mode
`codex.approvalPolicy`	string\|object	reject all	Tool call approval policy
`codex.threadSandbox`	string	`"workspace-write"`	Thread-level sandbox policy
`codex.turnSandboxPolicy`	object	`{type: "workspaceWrite"}`	Per-turn sandbox policy

Timeouts:

Key	Type	Default	Description
`codex.readTimeoutMs`	number	`5000`	JSON-RPC read timeout
`codex.turnTimeoutMs`	number	`3600000`	Max duration per turn (1 hour)
`codex.drainTimeoutMs`	number	`2000`	Drain timeout on shutdown
`codex.startupTimeoutMs`	number	`30000`	Container startup timeout (30s)
`codex.stallTimeoutMs`	number	`300000`	Per-turn stall detection (5 min)

Authentication:

Key	Type	Default	Description
`codex.auth.mode`	enum	`"api_key"`	`api_key` or `openai_login`
`codex.auth.sourceHome`	string	`"~/.codex"`	Path to Codex auth credentials

Sandbox (Container)

Key	Type	Default	Description
`codex.sandbox.image`	string	`"risoluto-codex:latest"`	Docker image for worker containers
`codex.sandbox.network`	string	`""`	Docker network name
`codex.sandbox.extraMounts`	string[]	`[]`	Extra bind mounts
`codex.sandbox.envPassthrough`	string[]	`[]`	Env vars forwarded to containers
`codex.sandbox.egressAllowlist`	string[]	`[]`	Allowed egress domains

Resources:

Key	Type	Default	Description
`codex.sandbox.resources.memory`	string	`"4g"`	Memory limit
`codex.sandbox.resources.memoryReservation`	string	`"1g"`	Guaranteed memory
`codex.sandbox.resources.memorySwap`	string	`"4g"`	Swap limit
`codex.sandbox.resources.cpus`	string	`"2.0"`	CPU limit
`codex.sandbox.resources.tmpfsSize`	string	`"512m"`	tmpfs mount size

Security:

Key	Type	Default	Description
`codex.sandbox.security.noNewPrivileges`	boolean	`true`	`--security-opt=no-new-privileges`
`codex.sandbox.security.dropCapabilities`	boolean	`true`	Drop all Linux capabilities
`codex.sandbox.security.gvisor`	boolean	`false`	Enable gVisor runtime
`codex.sandbox.security.seccompProfile`	string	`""`	Custom seccomp profile path

Logging:

Key	Type	Default	Description
`codex.sandbox.logs.driver`	string	`"json-file"`	Docker log driver
`codex.sandbox.logs.maxSize`	string	`"50m"`	Max log file size
`codex.sandbox.logs.maxFile`	number	`3`	Max number of log files

Workspace

Key	Type	Default	Description
`workspace.root`	string	`"../risoluto-workspaces"`	Root directory for issue workspaces
`workspace.strategy`	enum	`"directory"`	Isolation strategy: `directory` (clone) or `worktree` (git worktree)
`workspace.branchPrefix`	string	`"risoluto/"`	Branch name prefix for agent branches

Hooks:

Key	Type	Default	Description
`workspace.hooks.afterCreate`	string	`null`	Shell command after workspace creation
`workspace.hooks.beforeRun`	string	`null`	Shell command before each agent run
`workspace.hooks.afterRun`	string	`null`	Shell command after each agent run
`workspace.hooks.beforeRemove`	string	`null`	Shell command before workspace removal
`workspace.hooks.timeoutMs`	number	`60000`	Hook execution timeout (1 min)

Notifications

Risoluto supports two notification config shapes. The single-Slack shape is the legacy path; the channels array is the current multi-channel path and is what you should use for anything beyond a single Slack webhook.Legacy single-Slack:

Key	Type	Default	Description
`notifications.slack.webhookUrl`	string	—	Slack incoming webhook URL
`notifications.slack.verbosity`	enum	`"critical"`	`off`, `critical`, `verbose`

Multi-channel array:

Key	Type	Default	Description
`notifications.channels[]`	array	`[]`	Delivery channels, evaluated in order
`notifications.channels[].name`	string	—	Unique channel label used in notification metadata
`notifications.channels[].enabled`	boolean	`true`	Disable without removing the entry
`notifications.channels[].minSeverity`	enum	`"info"`	`info`, `warning`, `critical` — only notifications at or above this severity are delivered
`notifications.channels[].type`	enum	—	`slack`, `webhook`, or `desktop`

Slack channel (type: slack):

Key	Type	Default	Description
`webhookUrl`	string	—	Slack incoming webhook URL (prefer `$SECRET:SLACK_WEBHOOK_URL`)
`verbosity`	enum	`"critical"`	`off`, `critical`, `verbose`

Webhook channel (type: webhook):

Key	Type	Default	Description
`url`	string	—	HTTPS endpoint to POST notification payloads to
`headers`	object	`{}`	Extra HTTP headers (e.g. `Authorization: Bearer ...`)

Desktop channel (type: desktop): no extra fields — surfaces notifications in the dashboard notification tray only.

notifications:
  channels:
    - name: ops-slack
      type: slack
      minSeverity: warning
      webhookUrl: $SECRET:SLACK_WEBHOOK_URL
    - name: oncall-pager
      type: webhook
      minSeverity: critical
      url: https://events.example.com/risoluto
      headers:
        Authorization: Bearer $SECRET:PAGER_TOKEN
    - name: dashboard-only
      type: desktop

See the Notifications guide for event types and severity levels.

Webhook (Linear Inbound)

Key	Type	Default	Description
`webhook.webhookUrl`	string	—	HTTPS-only webhook URL (enables webhook mode)
`webhook.webhookSecret`	string	—	HMAC signing secret for verification
`webhook.pollingBaseMs`	number	`15000`	Polling interval when webhook is healthy
`webhook.pollingStretchMs`	number	`120000`	Polling interval stretched when webhook active
`webhook.healthCheckIntervalMs`	number	`300000`	Health check interval (5 min)

GitHub Integration

Key	Type	Default	Description
`github.token`	string	—	GitHub Personal Access Token
`github.apiBaseUrl`	string	`"https://api.github.com"`	GitHub API endpoint (for GHES)

Multi-repo routing

Route issues to different repositories based on tracker metadata. Each entry in repos is a destination that the orchestrator matches against the incoming issue before launching a worker. See the Multi-repo recipe for a worked example.

Key	Type	Default	Description
`repos[]`	array	`[]`	Repository routing entries
`repos[].repoUrl`	string	—	Git URL used to clone or fetch the workspace
`repos[].defaultBranch`	string	`"main"`	Branch agents branch from
`repos[].identifierPrefix`	string \| null	`null`	Match issues whose identifier starts with this prefix (e.g. `"ENG-"`)
`repos[].label`	string \| null	`null`	Match issues that carry this label
`repos[].githubOwner`	string \| null	`null`	GitHub owner used when the orchestrator opens the PR
`repos[].githubRepo`	string \| null	`null`	GitHub repo name used for the PR
`repos[].githubTokenEnv`	string \| null	`null`	Name of the env var holding the PR-creation token for this repo

Merge policy

Controls the opt-in auto-merge engine. Defaults to disabled, so no PR is auto-merged until you turn enabled on.

Key	Type	Default	Description
`mergePolicy.enabled`	boolean	`false`	Master switch. When `false`, Risoluto never requests an auto-merge
`mergePolicy.allowedPaths`	string[]	`[]`	Path prefixes; when non-empty, every changed file in the PR must match at least one entry
`mergePolicy.maxChangedFiles`	number \| null	`null`	Maximum number of changed files. `null` disables the cap
`mergePolicy.maxDiffLines`	number \| null	`null`	Maximum combined additions + deletions. `null` disables the cap
`mergePolicy.requireLabels`	string[]	`[]`	Labels that must all be present on the PR before auto-merge is attempted
`mergePolicy.excludeLabels`	string[]	`[]`	Labels that block auto-merge when any are present

State machine (custom stages)

Override the default issue lifecycle stages and transitions. Only needed if your tracker uses non-standard states or you want to gate specific transitions.

Key	Type	Default	Description
`stateMachine.stages[]`	array	`[]`	Ordered stage list
`stateMachine.stages[].name`	string	—	Stage label that must match a tracker state name
`stateMachine.stages[].kind`	enum	—	One of `backlog`, `todo`, `active`, `gate`, `terminal`
`stateMachine.transitions`	object	`{}`	Map of stage name to an array of allowed next stage names

stateMachine:
  stages:
    - { name: Backlog, kind: backlog }
    - { name: Ready, kind: todo }
    - { name: In Progress, kind: active }
    - { name: Review, kind: gate }
    - { name: Done, kind: terminal }
  transitions:
    Ready: [In Progress]
    In Progress: [Review, Ready]
    Review: [Done, In Progress]

Secrets Management

Secrets are stored in an AES-256-GCM encrypted store, separate from config:

curl -s -X POST http://127.0.0.1:4000/api/v1/secrets/SLACK_WEBHOOK_URL \
  -H 'Content-Type: application/json' \
  -d '{"value":"https://hooks.slack.com/services/..."}'

Keep secrets out of committed files. Use $SECRET:name references in config or environment variable expansion like $LINEAR_API_KEY.

Environment Variables

Variable	Required	Default	Description
`LINEAR_API_KEY`	Yes	—	Linear API key
`LINEAR_PROJECT_SLUG`	Yes	—	Linear project to watch
`MASTER_KEY`	Yes	—	Encryption key for secrets store
`OPENAI_API_KEY`	No	—	OpenAI API key (alternative to Codex auth)
`GITHUB_TOKEN`	No	—	GitHub PAT for PR creation
`DATA_DIR`	No	`~/.risoluto`	Root directory for archives and config
`RISOLUTO_BIND`	No	`127.0.0.1`	HTTP bind address
`RISOLUTO_WRITE_TOKEN`	No	—	Bearer token for remote API writes
`RISOLUTO_READ_TOKEN`	No	—	Bearer token required for remote reads when `RISOLUTO_BIND` is non-loopback. Unset when binding to `127.0.0.1`/`::1`
`LOG_LEVEL`	No	`info`	Log verbosity
`DISPATCH_MODE`	No	`local`	`local` or `remote` dispatch mode
`DISPATCH_URL`	No	—	Data plane URL (when `DISPATCH_MODE=remote`)
`DISPATCH_SHARED_SECRET`	No	—	Shared secret for control/data plane auth

Documentation Index

​Managing Configuration

​Configuration Sections

​Secrets Management

​Environment Variables

​What’s Next

Dashboard

Security

Managing Configuration

Configuration Sections

Secrets Management

Environment Variables

What’s Next