Quickstart

Install Helios on a CUDA machine, pre-warm the model weights, and open the live feed.

Helios runs as one local process: a FastAPI server that owns the camera, the detector, and the single-page UI.

Prerequisites

A prepared machine with a CUDA-capable NVIDIA GPU and a current NVIDIA driver.
Python ≥ 3.11 — the config loader uses the standard-library tomllib.
A working Anthropic API key.
A camera the OS sees as a webcam: built-in, USB, a phone via a virtual-camera app, or a mirrorless camera through an HDMI-to-USB capture card. See Configuration.

Install the CUDA PyTorch wheel separately and last

requirements.txt deliberately does not list torch / torchvision. A bare torch entry re-resolves against the default PyPI index and installs the CPU-only wheel, which silently breaks GPU inference (torch.cuda.is_available() returns False, and Helios then hard-fails with MODEL_UNAVAILABLE). Install everything else first, then the matched CUDA build, so nothing downgrades it.

1. Create the environment

# Create + activate a Python >=3.11 virtual environment
python -m venv .venv
.venv\Scripts\activate            # Windows
# source .venv/bin/activate       # Linux/macOS

# Install everything EXCEPT torch
pip install -r requirements.txt

2. Install the matched CUDA torch build

Pick the CUDA version your driver supports (cu124 shown). Use --force-reinstall if a CPU build sneaked in through a transitive dependency.

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124

Verify CUDA is actually live before going further:

python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
#   -> True <your NVIDIA GPU name>

If this prints False, the CPU wheel is still installed — reinstall from the CUDA index above.

3. Configure the API key

Claude is a hard dependency for the chat, not an optional enhancer. Copy the example env file and set your key:

copy .env.example .env            # then edit .env and set ANTHROPIC_API_KEY

ANTHROPIC_API_KEY=<your-anthropic-api-key>

A missing or rejected key surfaces as API_KEY_INVALID: the feed still runs on the starter concepts, but chat is blocked. There is no literal-text fallback.

4. Pre-warm the model weights

On first use Ultralytics auto-downloads the detector weights (yoloe-*-seg.pt, tens of MB) and the MobileCLIP text encoder (mobileclip_blt.ts, ~572 MB) that powers open-vocabulary concept embedding — roughly 600 MB in total. On a slow connection this can take a long time, and an interrupted download leaves a corrupt cache (PytorchStreamReader: failed finding central directory on the next start).

Pre-warm the cache on the machine that will run the demo, while you have good bandwidth:

python -m app.vision --selftest     # loads the model + binds concepts, triggering the downloads

If a weight file got corrupted, delete it (yoloe-*-seg.pt, mobileclip_blt.ts in the working directory) and re-run to re-download cleanly. These files are git-ignored.

5. Run

uvicorn app.main:app --host 127.0.0.1 --port 8000

Open http://localhost:8000. Type what you want detected in the chat pane; the live feed updates within about 1–2 s. For a projector, present the browser full-screen.

Helios has no authentication

Anyone who can reach the port can view the feed and change the mode, policy, or zone. Bind to 127.0.0.1 for local use. If you need it reachable from another device on the network (for a projector, say), run it only on a trusted network you control — there is no login, no token, and no authorization layer.

6. Pick a mode

Use the mode switch (Presence / PPE Compliance / Danger Zone) above the feed to choose a demo mode. The active mode is always drawn as a banner on the video frame itself, so it stays unambiguous on a projector even if the browser chrome is off-screen. See Demo modes.

Next steps

Tuning — hit your FPS target with legible, stable boxes.
Configuration — per-machine profiles in helios.toml, camera selection.
Reference — endpoints, error states, and troubleshooting.

Quickstart

On this page