Argus

Getting started

Docker quickstart

The primary way to run Argus. Requires Docker Desktop.

1. Clone

git clone https://github.com/MichaelYagi/argus.git
cd argus

No .env file needed — SECRET_KEY is auto-generated on first startup and persisted automatically. See .env.example if you want to override it or set other options.

2. Build and start

docker compose up --build

The first build downloads PyTorch, InsightFace, Ultralytics, and their dependencies — expect several GB and 5–15 minutes depending on your connection. Subsequent starts are fast:

docker compose up      # foreground
docker compose up -d   # background

3. Open the app

http://localhost:8100

Port 8100 — Argus had 100 eyes.

First run

Visit http://localhost:8100 — you're redirected to sign up
Create an account — the first user is automatically the admin
Subsequent sign-ups require admin approval from the Account page
Go to Models and download a face model (buffalo_l is recommended), then Activate it
Go to Enroll and enroll a face with a name — or skip this and label faces directly on the Detect page
Go to Detect and drop in a photo — Argus will detect and match faces

For object detection: download and activate a YOLO model from the Models page. yolov8s is a good starting point. For open-vocabulary detection, see YOLO-World in the Concepts guide.

Native run (no Docker)

Requires Python 3.11+.

cd argus
python3 -m venv .venv
source .venv/bin/activate      # Linux/macOS
.venv\Scripts\activate         # Windows PowerShell
pip install -r requirements.txt

python -m app

Binds to http://localhost:8100 by default. Pass --host and --port to override:

python -m app --host 0.0.0.0 --port 9000

Data is stored in ./data/ and model weights in ./models/ relative to the working directory. To use a different data location, set DATA_PATH:

DATA_PATH="/Volumes/MyDrive/argus-data" python3 -m app --host 0.0.0.0 --port 8100

GPU (native run): install requirements.txt and ensure NVIDIA drivers are installed. Argus auto-detects the GPU and pre-loads the required CUDA libraries at startup — no manual configuration needed for most setups. See Troubleshooting if GPU isn't detected.

Docker reference

Command	What it does
`docker compose up --build`	Build image and start (required after code changes)
`docker compose up`	Start using existing image
`docker compose up -d`	Start in background
`docker compose down`	Stop and remove containers
`docker compose logs -f`	Stream logs

Data persists — ./data (database, crops, source images) and ./models (downloaded weights) are bind-mounted from your host, so they survive container rebuilds.

GPU support (Docker)

Uncomment the deploy block in docker-compose.yml under the argus-inference service. That's where the model weights load, so that's where the GPU reservation belongs. Requires the NVIDIA Container Toolkit installed on the host and Docker Desktop using the WSL2 backend. GPU availability is auto-detected at runtime — no rebuild needed.

A GPU materially speeds up both engines:

Face engine (InsightFace/onnxruntime) — moderate speedup; CPU is usable for casual use
Object engine (YOLO/torch) — significant speedup under sustained load

The active provider is visible in GET /api/health — confirm GPU is working there before running heavy workloads.

ARM / Apple Silicon (M1/M2/M3)

Works natively. The image builds for ARM64 and onnxruntime (CPU) is installed automatically — onnxruntime-gpu has no ARM64 wheels. Everything runs correctly on CPU; Apple's Neural Engine is not used. See the macOS segfault note if you run natively (not Docker).