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

# Setup Wizard

> Understand the first-run setup wizard: what each step asks for, what it stores, and how to rerun setup safely later.

Use this page while the setup wizard is on screen at `/setup`, or before you re-run setup from the dashboard.

When Risoluto starts without a master key, it enters setup mode and redirects normal navigation into the wizard until the required first-run steps are complete.

## What you need before you begin

| Item                   | Required | Why it matters                                          |
| ---------------------- | -------- | ------------------------------------------------------- |
| **Linear API key**     | Yes      | Lets Risoluto validate your workspace and list projects |
| **OpenAI auth method** | Yes      | Needed to run Codex-backed agent workers                |
| **GitHub token**       | No       | Enables automatic PR creation after successful runs     |

## Wizard flow

<Steps>
  <Step title="Protect Secrets">
    Generates the master key used to encrypt credentials at rest with AES-256-GCM.

    Under the hood, the wizard calls `POST /api/v1/setup/master-key` and persists the result locally.

    <Warning>
      Back up the master key. If you lose it, previously encrypted secrets cannot be recovered.
    </Warning>
  </Step>

  <Step title="Connect Linear">
    Stores your Linear API key, fetches the list of available projects, and saves the project Risoluto should monitor.

    The wizard uses:

    1. `POST /api/v1/secrets/:key`
    2. `GET /api/v1/setup/linear-projects`
    3. Config overlay updates for the selected project slug

    <Note>
      If Linear returns no projects, the wizard shows guidance before you can continue.
    </Note>
  </Step>

  <Step title="Add OpenAI">
    Choose one authentication path for Codex-backed workers.

    <Tabs>
      <Tab title="API key">
        Paste an `sk-...` key. Risoluto validates it and stores it in the encrypted secret store.

        ```text theme={null}
        POST /api/v1/setup/openai-key
        ```
      </Tab>

      <Tab title="Browser sign-in">
        Start the PKCE flow from the wizard and finish sign-in in your browser.

        ```text theme={null}
        POST /api/v1/setup/pkce-auth/start
        GET /api/v1/setup/pkce-auth/status
        ```

        <Warning>
          The PKCE flow uses localhost port `1455`. If another process is already using that callback port, the sign-in flow cannot complete.
        </Warning>
      </Tab>

      <Tab title="Manual fallback">
        Use this when you are on a headless server or need to prepare auth elsewhere.

        ```bash theme={null}
        codex login
        # or
        codex login --device-auth
        ```

        Then paste the contents of `~/.codex/auth.json` into the wizard.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Add GitHub (optional)">
    Stores a GitHub Personal Access Token so successful runs can open or update pull requests automatically.

    You can skip this step and add the token later from the dashboard.
  </Step>
</Steps>

After the final step, choose **Go to Dashboard** to leave setup mode.

## Re-run setup later

<Steps>
  <Step title="Open Setup">Navigate to **System → Setup** in the dashboard, or go directly to `/setup`.</Step>

  <Step title="Reset API credentials from the done screen">
    Use **Reset & Re-run Setup** on the completed screen to clear the stored Linear, OpenAI, and GitHub credentials. The
    wizard restarts at **Connect Linear** and keeps the current master key.
  </Step>

  <Step title="Regenerate the master key only when you need to">
    Use **Reconfigure** on **Protect Secrets** when you want a new master key. That restarts the wizard from **Protect
    Secrets** and generates a new key. Use **Factory reset** below only when you need a full wipe of the master key,
    encrypted secrets, overlay config, archives, and cached workspaces.
  </Step>
</Steps>

## Accessibility and navigation behavior

* **Clickable stepper** — return to completed steps to review or change entries
* **Keyboard support** — step controls work with `Tab`, `Enter`, and `Space`
* **Reconfigure path** — the first step changes after completion so you can rotate credentials without guessing where to start

<AccordionGroup>
  <Accordion title="Factory reset">
    To start completely fresh, delete the named Docker volumes and boot the stack again:

    ```bash theme={null}
    docker compose down -v
    docker compose up --build -d
    ```

    This removes the master key, encrypted secrets, overlay config, archives, and cached workspaces stored in those volumes.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Follow the recommended first-run path from clone to smoke issue.
  </Card>

  <Card title="Dashboard" icon="chart-mixed" href="/guides/dashboard">
    Learn where to confirm setup, inspect runs, and change configuration.
  </Card>

  <Card title="Configuration" icon="gear" href="/guides/configuration">
    Adjust runtime behavior after setup is complete.
  </Card>

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