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

# Quickstart

> From `docker compose up` to a working scan in under 10 minutes.

This walks you through getting BreachLens running on your own machine, connecting your first GitHub repository, and seeing scan findings show up in the dashboard.

<Tip>
  Want to see it in action before installing? [Ask us for a demo](mailto:sales@breachlens.app?subject=BreachLens%20demo) — we'll walk you through a real scan: findings, attack paths, and a proof-of-exploit replay. The docs also ship an interactive [API playground](/api) you can point at your own deployment once you're running.
</Tip>

## Prerequisites

Before you begin, you must have:

* **Docker** 24.0+ and **Docker Compose** v2
* **8 GB RAM** minimum (16 GB recommended for the pentest scanner tier)
* **30 GB** free disk space
* Ports **5173** (web) and **3000** (api) free on your host
* A **license JWT** from [sales@breachlens.app](mailto:sales@breachlens.app?subject=BreachLens%20license%20request) (free for 30-day trial)

## Install

<Steps>
  <Step title="Get your license">
    Email [sales@breachlens.app](mailto:sales@breachlens.app?subject=BreachLens%20license%20request) with your company name and intended deployment. You'll receive a license JWT and the signed EULA within one business day.
  </Step>

  <Step title="Pull the install bundle">
    BreachLens ships as a single tarball with `docker-compose.yml` + scanner images. Download from the link in your license email.

    ```bash theme={null}
    tar xzf breachlens-2026.06.tar.gz
    cd breachlens
    ```
  </Step>

  <Step title="Set your license">
    Paste the license JWT into `.env`:

    ```bash theme={null}
    cp .env.example .env
    echo "LICENSE_KEY=eyJhbGciOiJFZERTQSIs..." >> .env
    ```

    <Note>
      The license is verified at api startup — locally, with no phone-home. Without a valid license the platform still boots and core scanning stays available; the premium features are disabled (they return HTTP 402) until you apply one. See [Licensing](/deployment/self-hosting#licensing) for the details.
    </Note>
  </Step>

  <Step title="Bring up the stack">
    ```bash theme={null}
    docker compose up -d
    ```

    First boot takes \~3 minutes (image pulls + database migrations + scanner warm-up). Watch the logs until the api healthcheck flips to `healthy`:

    ```bash theme={null}
    docker compose logs -f api
    ```
  </Step>

  <Step title="Create your owner account">
    On first boot — when no account exists yet — the api prints a **one-time setup token** to its logs. Grab it:

    ```bash theme={null}
    docker compose logs api | grep -A1 blnx_setup_
    ```

    You'll see a banner like:

    ```
    BreachLens · first-boot setup
    Open the web UI, visit /setup, and paste this token:

      blnx_setup_9f2c…

    Expires: 2026-07-09T12:00:00.000Z
    ```

    Open [https://localhost:5173/setup](https://localhost:5173/setup), paste the token, and fill in your name, work email, a strong password, your **organization name**, and your **primary email domain** (e.g. `acme.com`). Submitting creates the first **owner** account — a break-glass admin on a fresh team workspace.

    <Note>
      **Accept the certificate on both ports.** With the default self-signed cert, your browser has to trust **both** `https://localhost:5173` (web) **and** `https://localhost:3000/health` (api) — the setup form posts to the api on port `3000`, and an untrusted cert there makes the submit fail silently. Open each URL once, accept the warning, then return to `/setup`.
    </Note>

    <Note>
      The setup token works **once** and expires after **24 hours**. To print a fresh one, restart the api: `docker compose restart api`. Once the first account exists, `/setup` closes permanently — there's no second break-glass admin by design.
    </Note>
  </Step>

  <Step title="Enroll multi-factor authentication">
    Immediately after setup, BreachLens requires the owner to enroll MFA — an authenticator app (TOTP) or a passkey. Complete the prompt and you'll land on the dashboard.

    From here on you sign in with the email + password you just set (plus MFA). You can add SSO and invite teammates later from **Settings → Authentication**.
  </Step>
</Steps>

## Run your first scan

<Steps>
  <Step title="Install the BreachLens GitHub App">
    From the dashboard, open **Repositories → Add repository** and choose **From GitHub**. You'll be prompted to install the BreachLens GitHub App on the org or account that owns the repos you want to scan. It requests **read-only** access to repository contents and metadata, plus write access to checks and pull requests (for PR gating and auto-fix PRs).

    When GitHub asks which repositories to grant, you choose the scope:

    <CardGroup cols={2}>
      <Card title="All repositories" icon="circle-check">
        Simplest. New repos appear in BreachLens automatically — connect once, never return to GitHub. Recommended for demos and most teams.
      </Card>

      <Card title="Only select repositories" icon="lock">
        Least privilege. You hand-pick which repos the App can see. To scan a new one later, add it to the installation on GitHub first — one click from the **Manage on GitHub** link in the Add-repository modal.
      </Card>
    </CardGroup>

    <Note>
      Granting access is **not** the same as scanning. The scope you choose only controls which repos appear in the picker — nothing is scanned until you add a repo in BreachLens and run a scan. "All repositories" is read-only and safe; scanning stays opt-in, one repo at a time.
    </Note>
  </Step>

  <Step title="Trigger a scan">
    Back in the BreachLens dashboard, navigate to **Repositories**, pick a connected repo, and click **Run scan** in the top-right.

    The default scan tier runs **SAST + SCA + Secrets + IaC** in parallel. For a typical small-to-medium repo, findings land in **under a minute** — roughly 15–45 seconds in our testing. Large monorepos take proportionally longer.

    <Tip>
      For the full walkthrough — every way to add a repo, the complete GitHub App permission matrix, PR gating, and how to also audit your account's [GitHub posture](/scanning/github-posture) — see [Scan a repository](/scanning/repositories).
    </Tip>
  </Step>

  <Step title="Triage findings">
    Navigate to **Findings**. Filter by **Severity: Critical, High** and **Has attack path: yes** to see what actually matters.

    Click any finding row to open the detail drawer — you'll see the AI-suggested fix, reachability tier, attack-path context, and a one-click **Generate auto-fix PR** button.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Add a domain target" icon="globe" href="/scanning/domains">
    Run DAST + autonomous pentest against a live web app. Capture proof-of-exploit videos.
  </Card>

  <Card title="Configure SSO" icon="key" href="/auth">
    Wire Microsoft Entra ID, Okta, Auth0, Google Workspace, or Keycloak. Multi-IdP per org supported.
  </Card>

  <Card title="Bring your own AI" icon="sparkles" href="/ai-providers">
    Plug Anthropic, OpenAI, Gemini, or Ollama for auto-fix and finding summarization.
  </Card>

  <Card title="Air-gap installation" icon="shield-halved" href="/deployment/self-hosting#air-gapped-install">
    Deploy in a disconnected network. Your code, findings, and AI inference stay in your network; provision offline mirrors for the scanner rules and vulnerability data.
  </Card>
</CardGroup>

<Tip>
  Stuck? Reach out at [sales@breachlens.app](mailto:sales@breachlens.app) — every license customer gets a dedicated Slack channel during onboarding.
</Tip>