> ## Documentation Index
> Fetch the complete documentation index at: https://docs.risolu.to/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Short answers to the questions operators usually ask first: setup path, privacy, Docker, models, cost, monitoring, and failure handling.

# Frequently asked questions

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="What is the recommended way to start?">
    Use the [Quickstart](/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.
  </Accordion>

  <Accordion title="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](/concepts/trust-model) for the full boundary breakdown.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.

    ```bash theme={null}
    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"}'
    ```
  </Accordion>

  <Accordion title="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](/concepts/how-it-works) for the architecture behind tracker adapters.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/guides/dashboard) and [Observability](/operating/observability).
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/recipes/custom-sandbox) walks through the pattern.
  </Accordion>

  <Accordion title="Is there a hosted version?">
    Not today. The default operating model is self-hosted and local-first.
  </Accordion>

  <Accordion title="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      |
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Start with the recommended first-run path.
  </Card>

  <Card title="Setup Wizard" icon="wand-magic-sparkles" href="/guides/setup-wizard">
    See exactly what the wizard stores and validates.
  </Card>

  <Card title="Trust Model" icon="shield-halved" href="/concepts/trust-model">
    Review the security posture and trust boundaries.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/operating/troubleshooting">
    Diagnose setup and runtime failures.
  </Card>
</CardGroup>