FAQ

What is Risoluto?

Risoluto is a local orchestration engine that watches your tracker for eligible issues, launches sandboxed AI coding agents in Docker, and reports the result through pull requests, dashboard state, and API events.

What is the recommended way to start?

Use the Quickstart: run docker compose up --build, open http://127.0.0.1:4000, and complete the setup wizard.That path keeps the onboarding surface small and matches the default deployment model.

Does my code leave my machine?

Your repository data stays in workspaces you control. Risoluto still makes outbound calls to the services you configure, such as:

Service	Purpose
Linear API	Read issues and update issue state
OpenAI-compatible provider	Model inference for the agent runtime
GitHub API	Pull requests and repository actions
Slack API	Optional notifications

See the Trust Model for the full boundary breakdown.

Do I need Docker?

Yes. Agent work runs inside Docker sandboxes, and the recommended quickstart also runs the orchestrator in Docker.If you run the orchestrator on the host for development, Docker is still required for worker isolation.

Which models and providers are supported?

Risoluto uses the Codex runtime and defaults to gpt-5.4. You can change the model globally or per issue, and you can point the provider at an OpenAI-compatible endpoint.

curl -s -X POST http://127.0.0.1:4000/api/v1/MT-42/model \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-5","reasoning_effort":"medium"}'

Which issue trackers are supported?

Tracker	Status
Linear	Primary adapter with polling, transitions, labels, and webhooks
GitHub Issues	Supported adapter using the same orchestration pipeline

See How It Works for the architecture behind tracker adapters.

How does Risoluto handle failures?

Risoluto retries with exponential backoff until it reaches agent.maxContinuationAttempts.

Failure	Detection	Response
Agent error	Non-zero exit code	Retry with backoff
Container OOM	Exit code 137 / `OOMKilled`	Surface as `container_oom`, then retry
Stalled turn	No events for `codex.stallTimeoutMs`	Kill the turn, then retry
Stalled agent	No events for `agent.stallTimeoutMs`	Kill the worker, then retry
Retries exhausted	Max attempts reached	Mark the issue as failed

Attempt history stays visible in the dashboard and API.

How do I monitor what is happening?

You have three main surfaces:

Surface	What it gives you
Dashboard	Live board, issue detail, attempts, logs, and settings
API + SSE	Scriptable state snapshots and live event streams
Prometheus	Service and runtime metrics at `GET /metrics`

Start with the Dashboard guide and Observability.

Can multiple agents run at the same time?

Yes. Use agent.maxConcurrentAgents for a global cap and agent.maxConcurrentAgentsByState for per-state limits. Each agent gets its own Docker container and workspace.

What does Risoluto cost?

Risoluto itself is open source. Your direct cost comes from the model provider you configure and the amount of work each run consumes.The dashboard tracks issue-level and aggregate usage so you can see where spend is coming from.

Can I use my own sandbox image?

Yes. Build a custom image and point codex.sandbox.image at it through the config overlay API or dashboard.The Custom Sandbox recipe walks through the pattern.

Is there a hosted version?

Not today. The default operating model is self-hosted and local-first.

What are the system requirements?

Component	Minimum	Recommended
Node.js	v22+	Latest LTS
Docker	Engine 24+	Latest stable
RAM	4 GB + 4 GB per active agent	16 GB+
Disk	10 GB	50 GB+
CPU	2 cores + 2 per active agent	8+ cores

Quickstart

Start with the recommended first-run path.

Setup Wizard

See exactly what the wizard stores and validates.

Trust Model

Review the security posture and trust boundaries.

Troubleshooting

Diagnose setup and runtime failures.

Get Started

Core Concepts

Guides

Recipes

Operating

Frequently asked questions

What’s next

Quickstart

Setup Wizard

Trust Model

Troubleshooting

​Frequently asked questions

​What’s next

Quickstart

Setup Wizard

Trust Model

Troubleshooting

Frequently asked questions

What’s next