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

# Get started with dotbot in five steps

> Install dotbot, set the active runtime, initialize a project, launch the web dashboard, and run your first workflow in five steps.

dotbot wraps AI coding in a managed, auditable workflow engine. This guide takes you from a fresh install to running your first AI-assisted pipeline — no npm, pip, or Docker required.

<Steps>
  <Step title="Install dotbot">
    Use a package manager. Each installs a self-contained copy and puts `dotbot` on your PATH:

    <CodeGroup>
      ```powershell Windows (Scoop) theme={null}
      scoop bucket add dotbot https://github.com/andresharpe/scoop-dotbot
      scoop install dotbot
      ```

      ```bash macOS / Linux (Homebrew) theme={null}
      brew install andresharpe/dotbot/dotbot
      ```
    </CodeGroup>

    Or install from a source checkout. Clone the repository and run the bootstrap script:

    ```powershell theme={null}
    git clone https://github.com/andresharpe/dotbot ~/dotbot
    pwsh ~/dotbot/bootstrap.ps1
    ```

    `bootstrap.ps1` drops a small PATH shim into `~/.local/bin` (Linux/macOS) or `%LOCALAPPDATA%\Microsoft\WindowsApps` (Windows). The shim contains no framework code; it routes to a dotbot checkout or to a project-local runtime. After installing, restart your terminal so the `dotbot` command is on your PATH.

    <Note>
      On Windows, if PowerShell blocks the script due to your execution policy, run this first:

      ```powershell theme={null}
      Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
      ```
    </Note>
  </Step>

  <Step title="Set the active runtime">
    Package-managed installs resolve the framework from their own location, so you can skip this step. Source-checkout shims need `DOTBOT_HOME` to point at the checkout:

    <CodeGroup>
      ```powershell PowerShell theme={null}
      $env:DOTBOT_HOME = "$HOME/dotbot"
      ```

      ```bash bash / zsh theme={null}
      export DOTBOT_HOME="$HOME/dotbot"
      ```
    </CodeGroup>

    Persist it in your shell profile, or with `setx DOTBOT_HOME <path>` on Windows. Confirm the active install:

    ```powershell theme={null}
    dotbot status
    ```
  </Step>

  <Step title="Add dotbot to your project">
    Navigate to your project directory and initialize dotbot:

    ```powershell theme={null}
    dotbot init
    ```

    This creates a `.bot/` directory with two children: a tracked `workspace/` tree (task queue, plans, decisions, sessions, product docs) and a `.gitignore` for machine-local paths. Framework code is not copied; the runtime resolves it from your active install. Workflow and stack selection is recorded in `.bot/.control/settings.json`.

    To initialize with a specific workflow or stack, pass flags:

    <CodeGroup>
      ```powershell With a workflow theme={null}
      dotbot init -Workflow start-from-jira
      ```

      ```powershell With a stack theme={null}
      dotbot init -Stack dotnet-blazor,dotnet-ef
      ```

      ```powershell With both theme={null}
      dotbot init -Workflow start-from-jira -Stack dotnet
      ```
    </CodeGroup>

    <Tip>
      To vendor a per-project copy of the runtime so the project runs without a machine-level `DOTBOT_HOME`, use `dotbot init --copy-runtime`, or `dotbot install runtime` for a project that is already initialized. This copies the runtime into `.bot/runtime`.
    </Tip>
  </Step>

  <Step title="Start the web dashboard">
    Launch the runtime and built-in web dashboard:

    ```powershell theme={null}
    dotbot go
    ```

    The dashboard opens at `http://localhost:8686` by default. If that port is busy, dotbot scans for the next available port. Pass `--open` to open the dashboard in your default browser.

    The dashboard gives you seven tabs: **Overview**, **Product**, **Roadmap**, **Processes**, **Decisions**, **Workflow**, and **Settings**.
  </Step>

  <Step title="Run a workflow">
    Start the default workflow for a new project:

    ```powershell theme={null}
    dotbot run start-from-prompt
    ```

    To see all available workflows and stacks installed in your project, run:

    ```powershell theme={null}
    dotbot list
    ```

    <Tip>
      Run `dotbot doctor` at any time to scan for stale locks, orphaned worktrees, settings issues, and task queue health problems.
    </Tip>
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Core concepts" icon="book" href="/concepts/workflows-and-stacks">
    Understand workflows, stacks, task types, and how settings compose.
  </Card>

  <Card title="Configure providers" icon="sliders" href="/guides/configuring-providers">
    Switch between Claude, Codex, and Antigravity. Set models per task.
  </Card>

  <Card title="MCP server" icon="server" href="/mcp/overview">
    Explore the 31 built-in MCP tools for task and session management.
  </Card>

  <Card title="Command reference" icon="terminal" href="/reference/commands">
    Full reference for every dotbot CLI command and flag.
  </Card>
</CardGroup>