Getting Started

Getting Started

Overseer runs two ways: as a packaged desktop app (recommended for most users), or from source (recommended for development). Both run fully on your machine.

Option A: Desktop app (Windows / macOS / Linux)

1. Go to the latest release.
2. Download the installer for your platform:
   • Windows: Overseer-<version>-Setup.exe
   • macOS (Apple Silicon): Overseer-<version>-arm64.dmg
   • macOS (Intel): Overseer-<version>-x64.dmg
   • Linux: Overseer-<version>.AppImage or Overseer-<version>.deb
3. Install and launch. On first launch the app fetches the vision models it needs (see Models). If a fetch is skipped or fails, the app still runs at reduced accuracy and says so on each result.

A GPU is optional. With an NVIDIA GPU (CUDA), detection, depth and super-resolution run in half precision and are much faster. Without one, everything falls back to CPU.

Option B: From source

Prerequisites

• Python 3.12 (the project pins >=3.12,<3.13).
• uv for dependency management.
• Node.js (for the frontend / Electron shell).
• Optional: an NVIDIA GPU with CUDA 12.4 drivers. The torch wheels are pinned to the cu124 index.

Backend

# clone
git clone https://github.com/emreyvz/overseer
cd overseer

# install Python deps (creates .venv)
uv sync
# optional extras (EasyOCR / ANPR):
uv sync --extra ai-extras

# pre-fetch the vision models (optional; they also lazy-download on first use)
uv run python -m match.tools.export_models

Frontend

cd web
npm install
npm run build      # production build into web/dist
# during development:
npm run dev        # Vite dev server
npm run desktop    # build + launch the Electron shell

Run it

The convenience launchers start the backend and open the app:

• Windows: overseer.cmd
• macOS / Linux: ./overseer.sh

The backend serves the API and the built frontend; the Electron shell (or your browser) connects over WebSocket for the live stream.

First run

1. Add a camera. Overseer seeds one public demo camera so the map is not empty. Add your own RTSP / HTTP / device sources, or paste a YouTube URL (it is downloaded once and looped like a live camera).
2. Watch it analyse. The active camera streams detections, tracks, attributes and metrics in real time.
3. Open the AI Operator (press I) and type or speak a command, for example: "how many people are on the street camera" or "go to the store camera and add the person in red to the watchlist".
4. Configure an LLM (optional). The AI Operator's planner and vision Q&A use a language model. Add a provider in Settings to unlock free-form commands and on-screen visual questions. Without one, a deterministic command router still handles the common actions.

See Configuration for every setting, and Troubleshooting & FAQ if something does not light up.

Keyboard shortcuts (POV)

Key	Action
I	Open / close the AI Operator
N	Toggle live narration
F	Follow the selected subject (digital PTZ)
E	Enhance (box-select a region for a photographic close-up)
S	Social X-ray (attention cones + who is interacting)
Esc	Close the top-most panel (enhance, then operator, then back to the map)

Letters do not trigger shortcuts while the operator input is focused.