> ## 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.

# Quickstart

> Use the recommended Docker + setup wizard path to get Risoluto running and confirm your first automated issue flow.

Get Risoluto running, finish the setup wizard, and confirm the pipeline with one test issue.

<Check>
  **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.
</Check>

## Before you start

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

## Recommended path: Docker + setup wizard

<Steps>
  <Step title="Clone the repo and start the stack" icon="docker">
    ```bash theme={null}
    git clone https://github.com/OmerFarukOruc/risoluto.git
    cd risoluto
    docker compose up --build
    ```

    <Tip>
      This path does **not** require a `.env` file up front. The setup wizard stores configuration after the service starts.
    </Tip>
  </Step>

  <Step title="Open the local dashboard" icon="browser">
    Visit `http://localhost:4000` in your browser. On first boot, Risoluto redirects you straight into the setup wizard.
  </Step>

  <Step title="Finish the setup wizard" icon="wand-magic-sparkles">
    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](/guides/setup-wizard).
  </Step>

  <Step title="Run one smoke issue" icon="flask">
    Create a Linear issue with this title:

    ```text theme={null}
    SMOKE: create workspace proof file
    ```

    Use this description:

    ```markdown theme={null}
    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**.
  </Step>

  <Step title="Confirm the run" icon="badge-check">
    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:

    ```bash theme={null}
    curl -s http://localhost:4000/api/v1/state | jq
    ```
  </Step>
</Steps>

## Check the result

<CardGroup cols={2}>
  <Card title="Dashboard" icon="chart-mixed" href="/guides/dashboard">
    Use the board and issue detail views to confirm the run, inspect live progress, and review the outcome.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    If you prefer to verify from scripts or curl, start with the API overview and then drill into the exact endpoint you
    need.
  </Card>
</CardGroup>

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?

<AccordionGroup>
  <Accordion title="Run the orchestrator on the host while keeping agent sandboxes in Docker">
    Use this only if you need a direct host process for development or local debugging.

    **Additional requirements:** Node.js 22+ and `pnpm`.

    ```bash theme={null}
    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.

    <Tip>
      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.
    </Tip>
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="How It Works" icon="diagram-project" href="/concepts/how-it-works">
    Understand what happens after an issue becomes eligible.
  </Card>

  <Card title="Docker Deployment" icon="docker" href="/guides/docker">
    Move from a first run to a persistent service layout.
  </Card>

  <Card title="Configuration" icon="gear" href="/guides/configuration">
    Tune models, concurrency, workspace strategy, and sandbox behavior.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/operating/troubleshooting">
    Work through the most common setup and runtime failures.
  </Card>
</CardGroup>