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

# Flux Quickstart: Run Locally in Under Five Minutes

> Install Flux locally, connect to Azure with PowerShell identity, load demo data, and explore inventory, cost, and opportunities in the React dashboard.

This guide walks you through running Flux on your local machine — either pointed at a real Azure subscription or loaded with demonstration data so you can explore every chart and enrichment state without an Azure connection. By the end you will have the full Flux dashboard running at `http://127.0.0.1:8765`, with inventory, cost, and opportunities populated and ready to explore.

<Note>
  **Prerequisites** before you begin:

  * **Python 3.10+** — used to run the FastAPI backend and DuckDB writer.
  * **Node.js 20+** — used to build the React 19 frontend.
  * **PowerShell 7** (recommended) — required for the `Connect-AzAccount` Azure login and the `start-flux.ps1` convenience launcher.
</Note>

## Local setup

<Steps>
  <Step title="Clone and install dependencies">
    Create a virtual environment, install the Python dependencies, then build the React frontend:

    <CodeGroup>
      ```powershell PowerShell theme={null}
      python -m venv .venv
      .\.venv\Scripts\Activate.ps1
      python -m pip install -r .\requirements.txt

      Set-Location .\frontend
      npm install
      npm run build
      Set-Location ..
      ```
    </CodeGroup>

    The `npm run build` step produces the static assets in `frontend/dist` that FastAPI serves in production mode. You only need to rebuild when frontend source files change.
  </Step>

  <Step title="Connect to Azure">
    Flux uses your active Azure PowerShell session for local development. Sign in before starting the server:

    <CodeGroup>
      ```powershell PowerShell theme={null}
      Connect-AzAccount
      ```
    </CodeGroup>

    The signed-in identity needs read access to Azure Resource Graph and `Microsoft.CostManagement/*/read` on the subscriptions you plan to add. No service principal or client secret is required for local development.
  </Step>

  <Step title="Start Flux">
    Run the application entry point directly, or use the convenience launcher script:

    <CodeGroup>
      ```powershell Direct (python) theme={null}
      python .\app.py
      ```

      ```powershell Launcher script theme={null}
      .\start-flux.ps1
      ```
    </CodeGroup>

    The launcher automatically builds the frontend if `frontend/dist/index.html` is missing, then starts the server. Open [http://127.0.0.1:8765](http://127.0.0.1:8765) — Flux opens with a mock administrator session by default.

    You can pass a custom port to the launcher:

    <CodeGroup>
      ```powershell PowerShell theme={null}
      .\start-flux.ps1 -Port 9000
      ```
    </CodeGroup>
  </Step>

  <Step title="Add subscriptions and synchronize">
    With Flux running:

    1. Open **Administration → Integrations**.
    2. Optionally add your Entra tenant ID for verification.
    3. Add one or more Azure subscription IDs and friendly names, then **Save**.
    4. Select **Synchronize now**.

    Flux runs inventory, Advisor, Flux Intelligence, and cost collection in parallel. The first sync backfills 90 days of daily cost history for each new subscription. Progress is visible per source on the Integrations status page.
  </Step>
</Steps>

## Development mode

When you are actively changing frontend code, run the Vite dev server alongside the API for instant hot-module reload:

<Steps>
  <Step title="Start the API in one terminal">
    <CodeGroup>
      ```powershell PowerShell theme={null}
      python .\app.py
      ```
    </CodeGroup>

    The API binds to `http://127.0.0.1:8765` as normal.
  </Step>

  <Step title="Start the Vite dev server in a second terminal">
    <CodeGroup>
      ```powershell PowerShell theme={null}
      Set-Location .\frontend
      npm run dev
      ```
    </CodeGroup>

    Open [http://localhost:5173](http://localhost:5173). The Vite dev server proxies all `/api` requests to port `8765`, so the backend and frontend stay in sync.
  </Step>
</Steps>

## Demo data

To explore all chart and enrichment states without an Azure subscription, seed the database with demonstration data:

<CodeGroup>
  ```powershell PowerShell theme={null}
  $env:FLUX_DEV_SEED = "true"
  python .\app.py
  ```
</CodeGroup>

Demo rows are inserted **only when the DuckDB snapshot table is empty** and are tagged with demo source lineage so they are distinguishable from real Azure observations. Starting Flux a second time with a non-empty database is safe — the seed step is skipped automatically.

<Note>
  Demo data covers inventory, cost, and opportunity enrichment states. It does not simulate real-time synchronization or the Flux Intelligence assistant, which requires a configured AI provider key.
</Note>

## Verification

Run the Python test suite and frontend lint/build checks to confirm your installation is healthy:

<CodeGroup>
  ```powershell Python tests theme={null}
  python -m unittest discover -s .\tests -v
  ```

  ```powershell Frontend lint and build theme={null}
  Set-Location .\frontend
  npm run lint
  npm run build
  ```
</CodeGroup>

Interactive API documentation is available at [http://127.0.0.1:8765/docs](http://127.0.0.1:8765/docs) once the server is running.