How Argus works
This page follows one camera frame through Argus, from the camera to an answer in the Copilot.
The path of a frame
- Camera. An edge node opens the camera's stream, usually an
rtsp://URL. Each camera runs in its own worker on the edge node it is assigned to. - Detection and tracking. The edge node runs an object detector (YOLO) on the stream and tracks each object from frame to frame (ByteTrack). Each tracked object gets a track ID. By default the edge node publishes detections at most 5 times a second per camera.
- Short video buffer. While it detects, the edge node keeps the last 15 seconds of frames in memory. Nothing is written to disk at this stage.
- Events. The site node stores every detection as an event, with the camera, object class, confidence, position and time.
- Detection profile. The site node checks each detection against the camera's detection profile. The profile decides which object classes count, when (schedule) and under which condition, such as "stayed longer than 3 minutes" or "entered a zone".
- Rules. Detections that pass the profile are checked against your rules, called workflows in the dashboard. A rule can filter by camera, object class, zone and time of day. Schedules use the site's local time (
SITE_TIMEZONE). - Alert and actions. When a rule matches, Argus records a rule event and runs the rule's steps, for example Create Alert, Send Email, Send SMS or Send Webhook. Each rule fires once per tracked object.
- Clip. Argus asks the edge node for a clip of the moment: 5 seconds before to 5 seconds after. The edge node cuts it from its buffer, converts it to H.264 MP4 and uploads it to object storage (SeaweedFS) on the site, through a one-time upload link the site sends with the request. The site checks the clip, moves it to its final place and links it to the event.
- Caption. When the clip is ready, a vision model on the site node writes a one-sentence description of what is visible. It also stores a text embedding of the caption so you can search by description. See Video captions.
- Copilot. When you ask a question, the Copilot looks up events and alerts through a fixed set of read-only tools and answers from what it finds. It uses a local language model served by Ollama on your site; you choose which model.
The vision model only runs on alert clips, never on the live stream. This keeps the heavy model off every frame of every camera.
Components
Argus runs as a set of containers. You deploy them on your own servers. See Install.
| Component | What it does |
|---|---|
caddy | The only service with published ports. Serves the dashboard, API, clips and live streams over HTTPS on port 443; port 80 only redirects. See Install. |
migrate | Runs once at every start. Applies database schema updates, then exits. The other services wait for it. |
edge-node | Reads camera streams, runs detection and tracking, keeps the frame buffer, cuts clips and serves the live view for the Live Wall. Run one per edge server. |
site-consumer | Writes detections, tracks and events to the database. |
site-rule-engine | Applies detection profiles and rules, and runs workflow steps such as creating alerts. |
site-clip-updater | Links each finished clip to its event. |
site-vlm-captioner | Writes a caption and a search embedding for each alert clip. |
site-retention | Deletes old events and clips on a schedule. See Retention. |
site-cloud-sync | Optional. Sends a heartbeat and licence check to your control plane. See Standalone sites. |
site-api | Serves the dashboard, the Copilot and the HTTP API. |
postgres | PostgreSQL with pgvector. Stores cameras, events, alerts, rules, captions, embeddings and users. |
redis | Redis Streams. Carries detections and clip requests between components. |
seaweedfs | SeaweedFS object storage (S3 API). Holds the alert clips. |
ollama | Ollama. Serves the vision, embedding and Copilot models on your hardware. |
Timing
- Edge nodes check for camera changes every 10 seconds. A camera you add, enable, disable or reassign is picked up within that time.
- The rule engine reloads cameras, detection profiles and rules every 30 seconds. A change you save takes effect within that time.
- Captions are written after the clip is ready. A new alert shows Caption pending... until then.
What Argus does not do
- It does not record video continuously. Only alert clips are saved.
- It does not identify people by name or face.
- It does not read number plates or text.
- The Copilot does not change anything. It only reads events, alerts and the camera list.
Was this page helpful?