Skip to main content

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.

Get Risoluto running, finish the setup wizard, and confirm the pipeline with one test issue.
Recommended path: use Docker Compose and complete the setup wizard in the browser. Only use the host install path if you have a specific reason not to run the orchestrator in Docker.

​
Before you start

RequirementWhy you need it
DockerRisoluto runs agent work inside Docker sandboxes, and the recommended quickstart runs the orchestrator in Docker too.
Linear projectRisoluto needs a project to watch for actionable issues.
OpenAI authUse either an API key or browser sign-in during the setup wizard.
GitHub token (optional)Enables automatic PR creation after a successful run.

Clone the repo and start the stack

git clone https://github.com/OmerFarukOruc/risoluto.git
cd risoluto
docker compose up --build
This path does not require a .env file up front. The setup wizard stores configuration after the service starts.

Open the local dashboard

Visit http://localhost:4000 in your browser. On first boot, Risoluto redirects you straight into the setup wizard.

Finish the setup wizard

Work through the four first-run steps:
  1. Protect secrets — generate the master key used for encrypted local secret storage.
  2. Connect Linear — paste your API key and choose the project Risoluto should watch.
  3. Add OpenAI — use an API key or browser sign-in.
  4. Add GitHub (optional) — store a token for automatic PR creation.
If you want a step-by-step breakdown before you begin, read the Setup Wizard guide.

Run one smoke issue

Create a Linear issue with this title:
SMOKE: create workspace proof file
Use this description:
Create `RISOLUTO_SMOKE_RESULT.md` in the workspace with:
- the issue identifier
- the current UTC timestamp
- the output of `pwd` and `ls -la`
- whether the workspace looks empty or repo-backed
Move the issue into an active state such as In Progress.

Confirm the run

Watch the issue appear in the dashboard. If webhooks are configured, Risoluto reacts immediately. Otherwise it picks the issue up on the next poll cycle.You can also confirm from the API:
curl -s http://localhost:4000/api/v1/state | jq

​
Check the result

Dashboard

Use the board and issue detail views to confirm the run, inspect live progress, and review the outcome.

API Reference

If you prefer to verify from scripts or curl, start with the API overview and then drill into the exact endpoint you need.
If the run succeeds, inspect the generated proof file in your workspace root. For example, if your workspace root is ../risoluto-workspaces, check ../risoluto-workspaces/<ISSUE_IDENTIFIER>/RISOLUTO_SMOKE_RESULT.md. If you set RISOLUTO_HOST_WORKSPACE_ROOT, use that directory instead.

​
Prefer a host install instead?

Use this only if you need a direct host process for development or local debugging.Additional requirements: Node.js 22+ and pnpm.
git clone https://github.com/OmerFarukOruc/risoluto.git
cd risoluto
pnpm install
pnpm run build
bash bin/build-sandbox.sh
node dist/cli/index.js --port 4000
Then open http://127.0.0.1:4000 and complete the same setup wizard.
Use --data-dir /path/to/data to override the default data directory (~/.risoluto). You can also set the DATA_DIR environment variable — the CLI flag wins when both are provided.

​
What’s next

How It Works

Understand what happens after an issue becomes eligible.

Docker Deployment

Move from a first run to a persistent service layout.

Configuration

Tune models, concurrency, workspace strategy, and sandbox behavior.

Troubleshooting

Work through the most common setup and runtime failures.
Last modified on April 10, 2026