Configuration Reference

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

Built-in defaults — from Zod schemas in src/config/schemas/
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

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

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)

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
`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

Get Started

Core Concepts

Guides

Recipes

Operating

Configuration Reference

Managing Configuration

Configuration Sections

Secrets Management

Environment Variables

What’s Next

Dashboard

Security

Get Started

Core Concepts

Guides

Recipes

Operating

​Managing Configuration

​Configuration Sections

​Secrets Management

​Environment Variables

​What’s Next

Dashboard

Security

Managing Configuration

Configuration Sections

Secrets Management

Environment Variables

What’s Next