Skip to main content

​
Frequently Asked Questions

Risoluto is a local orchestration engine that connects your issue tracker to AI coding agents. It watches Linear (or GitHub Issues) for actionable work, dispatches sandboxed AI agents inside Docker containers, and delivers pull requests — all running on your own machine.
Linear issue → Risoluto picks it up → AI agent writes code → PR lands on GitHub
No prompts to write, no tabs to babysit. You triage issues; Risoluto does the rest.
No. Risoluto runs entirely on your local machine or a VDS you control. There is no Risoluto cloud service, SaaS backend, or telemetry.The only outbound calls are to services you configure:
ServicePurpose
Linear APIPolling issues and transitioning states
OpenAI APIModel inference (or your custom provider)
GitHub APIPR creation (optional)
Slack APINotifications (optional)
Your source code stays on your disk. The AI agent sees only the workspace for the issue it is working on.
Risoluto uses the Codex CLI as its agent runtime. The default model is gpt-5.4, but any OpenAI-compatible model works.Override the model globally or per-issue:
# Per-issue override
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"}'

# Global override via config
curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"provider":{"model":"gpt-5"}}}'
You can also point at non-OpenAI providers via an OpenAI-compatible proxy (LiteLLM, OpenRouter) by setting codex.provider.base_url.
Yes. Every AI agent runs inside an isolated Docker container with --cap-drop=ALL, resource limits, and an optional gVisor runtime. Docker provides the security boundary between the agent and your host system.Minimum requirement: Docker Engine 24+ (or Docker Desktop).
# Verify Docker is available
docker info
TrackerStatus
LinearPrimary adapter — full support for polling, transitions, labels, and webhooks
GitHub IssuesAdapter available — maps issues to the same pipeline
JiraOn the roadmap — the TrackerAdapter interface is designed for extensibility
See How It Works for details on the adapter architecture.
Risoluto applies exponential backoff retries up to agent.maxContinuationAttempts (default: 5). Specific failure modes:
FailureDetectionResponse
Agent errorNon-zero exit codeRetry with backoff
Container OOMExit code 137 / OOMKilledSurface as container_oom, retry with increased memory hint
Stalled agentNo events for agent.stallTimeoutMsKill container, retry
Exhausted retriesMax attempts reachedMark issue as failed, notify via Slack
All failures are logged to the attempt timeline and visible in the dashboard.
Yes. Build a custom Docker image extending risoluto-codex:latest, then point Risoluto at it:
curl -s -X PUT http://127.0.0.1:4000/api/v1/config/overlay \
  -H 'Content-Type: application/json' \
  -d '{"codex":{"sandbox":{"image":"my-custom-image:latest"}}}'
See the Custom Sandbox recipe for a full walkthrough including Dockerfile examples, dependency pre-installation, and gVisor setup.
No. Risoluto is local-only by design. Your code, credentials, and agent activity stay on hardware you control. There are no plans for a hosted offering — the local-first model is a core design decision, not a temporary limitation.
Three levels of visibility:
ChannelWhat you get
DashboardReal-time Kanban board at http://127.0.0.1:4000 with issue inspector, live event stream, and cost tracking
PrometheusGET /metrics exposes HTTP, poll, and agent-run counters for Grafana dashboards and alerting
SlackConfigurable notifications for agent start, completion, failure, and PR delivery
See Observability for setup details and Monitoring Stack for a Prometheus + Grafana recipe.
Risoluto itself is open source and free. You pay only for your own AI API usage (OpenAI, or whichever provider you configure). Typical costs depend on:
  • Model choice — gpt-5.4 vs smaller/cheaper models
  • Issue complexity — simple issues use fewer tokens than large refactors
  • Retry count — failed attempts consume additional tokens
The dashboard tracks per-issue and aggregate token costs in real time.
Yes. Configure agent.maxConcurrentAgents (default: 10) for a global limit, and agent.maxConcurrentAgentsByState for per-state limits. Each agent runs in its own Docker container with its own workspace.
ComponentMinimumRecommended
Node.jsv22+Latest LTS
DockerEngine 24+Latest stable
RAM4 GB + 4 GB per agent16 GB+
Disk10 GB50 GB+ (repo clones)
CPU2 cores + 2 per agent8+ cores

​
What’s Next

Quickstart

Get Risoluto running in under 10 minutes.

Trust Model

Understand the security boundaries and isolation layers.

Configuration

Customize models, timeouts, retries, and workspace strategies.

Troubleshooting

Diagnose common issues and recovery procedures.
Last modified on March 31, 2026