Get Started#
The Virtual Security Guard Agent (VSG) Agent console runs in a single container and proxies requests to two upstreams: the Hermes API server and the Video Search and Summarization (VSS) gateway. Argus, the VSG agent, runs on the Hermes agent server. The console has no backend or database of its own.
Prerequisites#
A host that meets the System Requirements, with Docker Engine (Compose and Buildx plugins) and GNU Make tool (
sudo apt-get install -y make).VSS in search mode and a Hermes agent server with the VSG agent, set up as described in Set Up the Prerequisite Stack.
Run the Application#
1. Get the Source#
If you have set up the prerequisite stack on this host, you have already cloned the
source for step 1.
Go to the cloned source directory and run cd metro-ai-suite/virtual-security-guard-agent.
Otherwise, clone it:
git clone --filter=blob:none --sparse --branch release-2026.3.0 https://github.com/open-edge-platform/metro-ai-suite.git
cd metro-ai-suite
git sparse-checkout set virtual-security-guard-agent
cd virtual-security-guard-agent
The guide assumes the following commands run from this directory.
2. Create deploy/.env#
Set the Hermes API server URL, its key from
Enable the API server,
and the VSS gateway URL. The make env command copies deploy/.env.example to
deploy/.env with these values. If deploy/.env already exists, the command
updates these three values and keeps the rest:
make env HERMES_BASE_URL=http://<hermes-host-ip>:8642 \
HERMES_API_KEY=<key> \
VSS_BASE_URL=http://<vss-host>:12345
To change other settings, edit deploy/.env:
Variable |
Default |
Purpose |
|---|---|---|
|
|
Hermes API server, |
|
(required) |
Hermes |
|
|
The NGINX gateway address configured by |
|
|
Default floorplan: |
|
|
Set |
|
|
Console port. |
|
|
VSG UI image tag. |
REGISTRY and TAG select the image. With make, pass them as arguments (see
Build from Source). If deploy/.env
already exists, update its TAG to 2026.3.0-rc1; make env preserves it.
Important
deploy/.env holds the Hermes API key. Never commit it.
If your network uses a proxy, add the Hermes and VSS hosts to no_proxy.
3. Start#
make up
make up runs the image set by REGISTRY and TAG in deploy/.env. It uses
the local image if available. Otherwise, it pulls the image or builds it from
source if the pull fails. See logs with make logs.
4. Check the Connections#
for u in /healthz /hermes/health /vss/manager/health; do
printf '%-22s %s\n' "$u" "$(curl -s -o /dev/null -w '%{http_code}' http://localhost:12346$u)"
done
All three must return 200. The sidebar footer also shows Hermes and VSS
as Reachable.
5. Run a Search#
Open the console’s Argus page at http://<HOST_IP>:12346/argus, then:
Describe the person, attach a photo, or both. Optionally, name cameras or a time range in the text.
Select Send. The VSG agent replies with a grid of potential matches.
Play a clip, Confirm the sightings that show the subject, and send the review.
Continue from the chat: crop and re-search, start a live camera search, or generate a report. The route appears on the Floorplan page.
See Investigate a Person for the full walkthrough.
6. Stop#
make down