Skip to main content
This page covers one-time installation steps for a fresh clone. You only need to do these once per machine. For day-to-day build and run commands, see Building.

​
HiroServer (hirocli + hirogateway)

Install uv — the Python package and project manager used by the server. After cloning, run from the repo root: 
cd hiroserver
uv sync
uv tool install --editable hirocli
uv tool install --editable gateway
uv sync installs all workspace dependencies (shared by both hirocli and hirogateway). uv tool install --editable hirocli installs both the hirocli and hiro-channel-devices binaries — the mandatory channel is declared as a script in hirocli’s pyproject.toml, so a single tool install covers both. uv tool install --editable gateway installs the hirogateway binary.

​
Mobile / web app

Install Flutter. The repo pins a specific Flutter version in device_apps/.fvmrc. Install exactly that version — the Flutter releases archive lists all stable builds. The device_apps/flutter_build.sh script checks your installed version before every build and aborts with a clear message if it does not match.

​
Website (optional)

The public website at hiroleague-website/ is a standalone Astro project. See Website for its full setup and build guide. The only prerequisite is Node.js 22.12+, which is documented there.

​
Documentation (optional)

Install the Mintlify CLI to preview the docs site locally and to set up AI tools in Cursor. 
npm i -g mint

​
Diagram generator

The diagram generator scans mintdocs/ for mermaid code blocks and renders each to a PNG in mintdocs/images/diagrams/. Install Node.js, then install the Mermaid CLI globally: 
npm install -g @mermaid-js/mermaid-cli
mmdc --version
See Diagram generator for authoring and workflow details.

​
Troubleshooting

uv was not installed or is not on your PATH. Install it from docs.astral.sh/uv and restart your terminal.
The installed Flutter version does not match the version pinned in device_apps/.fvmrc. Download the exact required version from the Flutter releases archive and point your PATH to it, or run flutter upgrade if the required version is newer than what you have.
Cursor stores the interpreter selection internally by workspace path. Renaming or moving the folder creates a new workspace identity and loses the previous selection.The repo’s .vscode/settings.json already pins the interpreter to ${workspaceFolder}\hiroserver\.venv\Scripts\python.exe, so simply opening the renamed folder in Cursor should pick it up automatically. If the prompt still appears, click Select Interpreter and choose the venv Python at that path, or run Python: Select Interpreter from the command palette and point it to hiroserver\.venv\Scripts\python.exe inside the repo.
uv sync only installs the workspace virtual environment — it does not install tool entry-point scripts. You must also run the tool install steps:
uv tool install --editable hirocli
uv tool install --editable gateway