# Get Started This guide covers the rapid deployment of the Live Video Alert Agent system using Docker. ## Prerequisites - Docker and Docker Compose v2.20.2 or later - Internet connection (for initial VLM model download) ## Initial Setup 1. Clone the suite and navigate to the application directory: ```bash 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 live-video-analysis/live-video-alert-agent cd live-video-analysis/live-video-alert-agent ``` 2. Configure the image registry and tag variables: ```bash export REGISTRY="intel/" export TAG="2026.3.0-rc1" export OVMS_TARGET_DEVICE=GPU export RENDER_DEVICE_GID=$(stat -c "%g" /dev/dri/render*) #run this when deploying for GPU or NPU export HF_TOKEN= ``` You can also use a mixed configuration (for example, GPU for VLM and NPU for LLM): ```bash export VLM_TARGET_DEVICE=GPU export LLM_TARGET_DEVICE=NPU ``` Skip this step if you prefer to build the sample application from source. For detailed instructions, refer to [How to Build from Source](./get-started/build-from-source.md) guide for details. 3. Configure the environment: Optional environment variables: ```bash # Optional: Pre-configure a video stream export RTSP_URL=rtsp://:/stream # VLM model selection export OVMS_SOURCE_MODEL= #Example: Openvino/Phi-3.5-vision-instruct-int4-ov # Log verbosity export LOG_LEVEL=DEBUG ``` > **Model Selection:** Use pre-converted OpenVINO IR models from the > [OpenVINO organization on Hugging Face](https://huggingface.co/OpenVINO) > for best compatibility. These models are optimized for OVMS and require no > additional conversion. Use models optimized for NPU while deploying on NPU. **Agentic dispatch** The `alert-agent-service` microservice handles agentic dispatch automatically. If you want ADK (LLM-reasoned) mode, enable the LLM service: ```bash export COMPOSE_PROFILES=adk-llm export LLM_MODEL=OpenVINO/Phi-4-mini-instruct-int4-ov export AGENT_MODE=true ``` If you want rule-based mode ```bash export AGENT_MODE=false export COMPOSE_PROFILES=[] ``` **Action tools** ```bash # Webhook (receives HMAC-signed POST) export WEBHOOK_URL=https://hooks.example.com/alert export WEBHOOK_SECRET= # optional # MQTT export MQTT_BROKER= export MQTT_PORT=1883 export MQTT_USERNAME= # optional export MQTT_PASSWORD= # optional export MQTT_BASE_TOPIC=alerts/live-video ``` **MCP (Model Context Protocol) — optional external tool servers:** ```bash export MCP_ENABLED=true # default: true export MCP_CONFIG_FILE=resources/mcp_servers.json # path to MCP server config ``` Configure MCP servers in `resources/mcp_servers.json`. See [API Reference](./api-reference.md#mcp) for details. 4. Start the application: Run the following command from the project root: ```bash docker compose -f docker/docker-compose.yml up -d ``` For NPU deployments: ```bash docker compose -f docker/docker-compose.yml -f docker/docker-compose.npu.yml up -d ``` **Note:** - First run downloads the VLM model (~2GB, 5-10 minutes) - An init container runs briefly to set up volume permissions. - Subsequent runs start instantly 5. Verify the deployment: Check that containers are running: ```bash docker ps ``` Confirm that `live-video-alert-agent` and `alert-agent-service` are both running. If you enabled MQTT support, you may also see `alert-mqtt`. View application logs: ```bash docker logs live-video-alert-agent ``` 6. Access the dashboard: Open your browser and navigate to `http://localhost:9000` (Replace `localhost` with your server IP if accessing remotely). ## How To Use the Application ### Add Video Streams 1. In the sidebar under **Stream Configuration**, enter: - **Stream Name**: A descriptive name (e.g., "Lobby Camera") - **RTSP URL**: Your camera's RTSP stream URL (or the sample stream from [Create a Sample RTSP Stream](#create-a-sample-rtsp-stream)) 2. Click **Add New Stream** ## Create a Sample RTSP Stream If you do not have an RTSP camera, you can publish a public sample video from [intel-iot-devkit/sample-videos](https://github.com/intel-iot-devkit/sample-videos) as an RTSP stream. No video is bundled with this application. 1. Download a sample video (for example, `person-bicycle-car-detection.mp4`): ```bash curl -L -o sample.mp4 \ https://github.com/intel-iot-devkit/sample-videos/raw/master/person-bicycle-car-detection.mp4 ``` 2. Start an RTSP server (MediaMTX): ```bash docker run -d --rm --name rtsp-server -p 8554:8554 bluenviron/mediamtx:1.9.3 ``` 3. Publish the video in a loop to the RTSP server (requires `ffmpeg`, install it if necessary): ```bash sudo apt install ffmpeg ``` Then start the video loop with the following command: ```bash ffmpeg -re -stream_loop -1 -i sample.mp4 -c copy -f rtsp -rtsp_transport tcp \ rtsp://localhost:8554/stream ``` Keep this command running in its own terminal. 4. Use the stream URL in the application. The URL must be reachable from the `live-video-alert-agent` container, so use the host IP address rather than `localhost`: ```text rtsp://:8554/stream ``` Set it as `RTSP_URL` before deployment, or enter it as the **RTSP URL** when [adding a stream](#add-video-streams) in the dashboard. 5. When finished, stop the `ffmpeg` command (Ctrl+C) and the server: ```bash docker stop rtsp-server ``` ## Configure Alerts 1. Under **AI Agent Alerts** section: - Click **Create New Alert** - Enter an **Alert Name** (e.g., "Fire Detection") - Write a **Prompt** describing the condition (e.g., "Is there fire or smoke?") - Set the **Tools** to invoke on detection 2. Click **Save** to activate Alternatively, configure alerts via the REST API: ```bash curl -X POST http://localhost:9000/config/alerts \ -H "Content-Type: application/json" \ -d '[ { "name": "Fire Detection", "prompt": "Is there fire or smoke visible?", "enabled": true, "severity": "critical", "tools": ["log_alert", "capture_snapshot"], "escalation": { "threshold_consecutive": 3, "additional_tools": ["trigger_webhook", "publish_mqtt"] } } ]' ``` ### View Results - The dashboard shows the live stream with analysis results below - Use the dropdown to filter alerts: "All Alerts" or individual alert types - Results update automatically via Server-Sent Events (SSE) - The `alert_action` event surface shows which tools were invoked and whether escalation occurred ### Check Health and Metrics ```bash # Liveness curl http://localhost:9000/health # Readiness (non-200 = not ready) curl http://localhost:9000/ready # System + per-stream metrics curl http://localhost:9000/metrics # List configured action tools curl http://localhost:9000/tools ``` ## Manage the Application ### Stop the Services To stop all services: ```bash docker compose -f docker/docker-compose.yml down ``` ### Restart After Changes ```bash # Restart both services docker compose -f docker/docker-compose.yml restart # Restart only the application (VLM service keeps running) docker compose -f docker/docker-compose.yml restart live-video-alert-agent ``` ### View Logs ```bash # VLM service logs docker logs -f ovms-vlm # Alert agent service logs docker logs -f alert-agent-service # Application logs docker logs -f live-video-alert-agent ``` ### Clear Model Cache If you need to re-download the model or switch models: ```bash # Remove everything including model cache docker compose -f docker/docker-compose.yml down -v # Set environment and start fresh export RTSP_URL=rtsp://:/stream docker compose -f docker/docker-compose.yml up -d ``` ## Troubleshooting ### Permission Issues **Problem**: OVMS fails with "permission denied" on `/models`. **Solution**: An init container (`ovms-init`) automatically sets permissions. It will show as `Exited (0)` - this is normal. **Verify**: ```bash docker ps -a --filter "name=ovms-init" # Should show: Exited (0) docker exec ovms-vlm ls -lah /models # Should be owned by ovms ``` ### Other Issues ```bash # Check status docker compose -f docker/docker-compose.yml ps # View logs docker compose -f docker/docker-compose.yml logs -f # Clean restart docker compose -f docker/docker-compose.yml down -v export RTSP_URL= docker compose -f docker/docker-compose.yml logs -f up -d ``` ## Learn More - [Build from Source](./get-started/build-from-source.md) - [Deploy with Helm](./get-started/deploy-with-helm.md) - Deploy the application on Kubernetes with the bundled Helm chart. :::{toctree} :hidden: ./get-started/system-requirements ./get-started/build-from-source ./get-started/deploy-with-helm :::