ispysoftware/agentdvr repository overview

⁠iSpy Agent DVR multi-arch image

Official Agent DVR image. Website: https://www.ispyconnect.com⁠

This official image is based on the community image originally created by MD. Mekayel Anik⁠.

⁠Supported architectures

Every tag is a multi-arch manifest: pull ispysoftware/agentdvr:latest (or any other tag) and Docker selects the right image for the host automatically. There are no separate per-architecture tags.

⁠Announcements

• Directory structure: the application directory has reverted to /AgentDVR (previously /home/agentdvr/AgentDVR). Make sure your volume mappings reflect this, particularly in unRAID, Synology and other GUI-based container managers.
• Base image: the image is now based on Debian Trixie.
• Image compression: images use ZSTD compression to reduce size and bandwidth. Version 6.5.7.0 and later require Docker Engine 23.0+ (or Podman Machine v5.1+).
• FFmpeg: the image bundles an LGPL FFmpeg build. The optional GPL build (x264/x265 software encoders) can be enabled in Server Settings inside the app; it is downloaded to the config volume so it survives container recreation.
• GPU acceleration: hardware-accelerated encode/decode requires version 5.3.5.0 or newer.
• Beta images are for testing only and should not be used in production environments.
• Review the release history⁠ before pinning older tags.

Pinned version tags are published from 7.9.4.0 onward (older releases are not built for this image). Each build also gets a dated tag, e.g. 7.9.5.0-beta-21082026, so a specific build can be pinned.

⁠Quick install

Interactive installers that check Docker, create the data folders, generate a docker-compose.yml and start the container:

Linux / macOS

curl -sL "https://www.ispyconnect.com/docker/linux/install-agentdvr.sh" -o docker_agent.sh && bash docker_agent.sh; rm docker_agent.sh

Windows (Docker Desktop): download and run agentdvr-docker-installer.ps1⁠ (signed; it requests elevation and can start Docker Desktop for you).

Both installers offer the beta channel when a newer beta is available and otherwise use latest.

⁠Running the image

⁠docker-compose (recommended, docs⁠)

---
services:
  ispyagentdvr:
    image: ispysoftware/agentdvr:latest
    container_name: ispyagentdvr
    environment:
      - PUID=1000
      - PGID=1000
      - AGENTDVR_WEBUI_PORT=8090
      - TZ=Europe/London
    volumes:
      - /path/to/config:/AgentDVR/Media/XML
      - /path/to/recordings:/AgentDVR/Media/WebServerRoot/Media
      - /path/to/models:/AgentDVR/Media/Models
      - /path/to/commands:/AgentDVR/Commands
    ports:
      - 8090:8090
      - 3478:3478/udp
      - 50000-50100:50000-50100/udp
    restart: unless-stopped

Note: on Raspberry Pi and other low-power ARM boards, allow around 30 seconds after deployment before opening the web UI, then refresh if needed. With many cameras configured, startup can take longer.

⁠docker cli ( docs⁠)

docker run -d \
  --name=ispyagentdvr \
  -e PUID=1000 \
  -e PGID=1000 \
  -e AGENTDVR_WEBUI_PORT=8090 \
  -e TZ=Europe/London \
  -p 8090:8090 \
  -p 3478:3478/udp \
  -p 50000-50100:50000-50100/udp \
  -v /path/to/config:/AgentDVR/Media/XML \
  -v /path/to/recordings:/AgentDVR/Media/WebServerRoot/Media \
  -v /path/to/models:/AgentDVR/Media/Models \
  -v /path/to/commands:/AgentDVR/Commands \
  --restart unless-stopped \
  ispysoftware/agentdvr:latest

⁠Dedicated local IP using MACVLAN ( docs⁠)

---
services:
  ispyagentdvr:
    image: ghcr.io/ispysoftware/agentdvr:latest
    container_name: ispyagentdvr
    environment:
      - PUID=1000
      - PGID=1000
      - AGENTDVR_WEBUI_PORT=8090
      - TZ=Europe/London
    volumes:
      - /path/to/config:/AgentDVR/Media/XML
      - /path/to/recordings:/AgentDVR/Media/WebServerRoot/Media
      - /path/to/models:/AgentDVR/Media/Models
      - /path/to/commands:/AgentDVR/Commands
    ports:
      - 8090:8090
      - 3478:3478/udp
      - 50000-50100:50000-50100/udp
    restart: unless-stopped
    hostname: ispyagentdvr
    domainname: local
    mac_address: AB-BC-C0-D1-E2-EF
    networks:
      macvlan-1:
        ipv4_address: 192.168.2.12
networks:
  macvlan-1:
    name: macvlan-1
    external: True

To use MACVLAN, set valid values for mac_address, ipv4_address, subnet, ip_range and gateway. Access the web UI at http://ipv4_address:8090.

⁠GPU hardware acceleration (5.3.5.0 and newer)

Hardware-accelerated encode/decode requires image version 5.3.5.0 or newer, and the GPU render devices must be passed through to the container as shown below. If you run into problems, please open an issue on this image's GitHub repository (linked at the bottom of this page).

⁠docker-compose (recommended, docs⁠)

---
services:
  ispyagentdvr:
    image: ghcr.io/ispysoftware/agentdvr:latest
    container_name: ispyagentdvr
    environment:
      - PUID=1000
      - PGID=1000
      - AGENTDVR_WEBUI_PORT=8090
      - TZ=Europe/London
    volumes:
      - /path/to/config:/AgentDVR/Media/XML
      - /path/to/recordings:/AgentDVR/Media/WebServerRoot/Media
      - /path/to/models:/AgentDVR/Media/Models
      - /path/to/commands:/AgentDVR/Commands
    ports:
      - 8090:8090
      - 3478:3478/udp
      - 50000-50100:50000-50100/udp
    restart: unless-stopped

⁠docker cli ( docs⁠)

docker run -d \
  --name=ispyagentdvr \
  -e PUID=1000 \
  -e PGID=1000 \
  -e AGENTDVR_WEBUI_PORT=8090 \
  -e TZ=Europe/London \
  -p 8090:8090 \
  -p 3478:3478/udp \
  -p 50000-50100:50000-50100/udp \
  -v /path/to/config:/AgentDVR/Media/XML \
  -v /path/to/recordings:/AgentDVR/Media/WebServerRoot/Media \
  -v /path/to/models:/AgentDVR/Media/Models \
  -v /path/to/commands:/AgentDVR/Commands \
  --restart unless-stopped \
  ispysoftware/agentdvr:latest

⁠Nvidia GPUs

Install the latest Nvidia drivers and the Nvidia Container Toolkit⁠ on the host. The image already sets the environment variables needed to expose the GPU's capabilities.

With the toolkit installed, recreate the container with the Nvidia runtime (--runtime=nvidia) and add -e NVIDIA_VISIBLE_DEVICES=all. This can also be set to a specific GPU's UUID, which you can find with nvidia-smi --query-gpu=gpu_name,gpu_uuid --format=csv. The Nvidia runtime mounts the GPU and drivers from the host into the container automatically.

CUDA AI object detection: the image ships video hardware acceleration only. For GPU object detection (CUDA + cuDNN), build a small overlay image — see CUDA-ACCELERATION.md⁠.

⁠AMD GPUs and iGPUs

Add the following to your Compose file or CLI command respectively:

docker compose

devices:
    - /dev/dri/renderD128:/dev/dri/renderD128
    - /dev/dri/card0:/dev/dri/card0
    - /dev/kfd:/dev/kfd

docker cli

--device /dev/dri/renderD128:/dev/dri/renderD128 --device /dev/dri/card0:/dev/dri/card0 --device /dev/kfd:/dev/kfd

⁠Intel GPUs and iGPUs

Add the following to your Compose file or CLI command respectively:

docker compose

devices:
    - /dev/dri/renderD128:/dev/dri/renderD128
    - /dev/dri/card0:/dev/dri/card0

docker cli

--device /dev/dri/renderD128:/dev/dri/renderD128 --device /dev/dri/card0:/dev/dri/card0

⁠Rockchip integrated VPUs

docker run -d \
  --name=ispyagentdvr \
  -e PUID=1000 \
  -e PGID=1000 \
  -e AGENTDVR_WEBUI_PORT=8090 \
  -e TZ=Europe/London \
  -p 8090:8090 \
  -p 3478:3478/udp \
  -p 50000-50100:50000-50100/udp \
  -v /path/to/config:/AgentDVR/Media/XML \
  -v /path/to/recordings:/AgentDVR/Media/WebServerRoot/Media \
  -v /path/to/models:/AgentDVR/Media/Models \
  -v /path/to/commands:/AgentDVR/Commands \
  --restart unless-stopped \
`for dev in dri dma_heap mali0 rga mpp_service \
   iep mpp-service vpu_service vpu-service \
   hevc_service hevc-service rkvdec rkvenc vepu h265e ; do \
  [ -e "/dev/$dev" ] && echo " --device /dev/$dev"; \
 done` 
  ispysoftware/agentdvr:latest

⁠Parameters

Parameters are separated by a colon and indicate <external>:<internal>. For example, -p 8091:8090 exposes port 8090 inside the container on host port 8091.

⁠User / Group Identifiers

When using volumes (-v flags), permission issues can arise between the host and the container. To avoid this, specify the user and group the container should run as with PUID and PGID, and make sure any volume directories on the host are owned by that user.

In the examples above PUID=1000 and PGID=1000. To find yours, run id username:

$ id username
uid=1000(docker user) gid=1000(docker group) groups=1000(docker group)

⁠Documentation

The Agent DVR user guide is available at https://www.ispyconnect.com/docs/agent/about⁠.

⁠Non-host networking

When not using host networking, the UDP ports listed in the examples must be published for remote viewing to work.

The web UI is available at http://<container ip>:8090 (or http://ipv4_address:8090 with MACVLAN).

⁠Updating

⁠Via Docker Compose (recommended)

• Update all images: docker compose pull
  • or update a single image: docker compose pull ispyagentdvr
• Let compose update all containers as necessary: docker compose up -d
  • or update a single container (recommended): docker compose up -d ispyagentdvr
• Remove old unused images: docker image prune

⁠Via Docker Run

• Update the image: docker pull ispysoftware/agentdvr:latest
• Stop the running container: docker stop ispyagentdvr
• Delete the container: docker rm ispyagentdvr
• Recreate the container with the same docker run parameters as before (if /AgentDVR/Media/XML is mapped to a host folder, your settings are preserved)
• Remove old unused images: docker image prune

⁠Via Watchtower⁠ (use only if you no longer have the original run parameters)

• Pull the latest image and recreate the container with the same environment variables in one run:

  docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower\
  --run-once ispyagentdvr

  Copy

• Remove old unused images: docker image prune

⁠Update notifications

• Diun⁠ can notify you when a new image is available. Tools that update containers unattended are not recommended for a surveillance system.

⁠Migration notes

If you used the old separate audio and video volumes, move their contents into the new media folder before starting the container again:

mkdir -p /ispyagentdvr/media/old && \
mv /path/to/recordings/audio /ispyagentdvr/media/old && \
mv /path/to/recordings/video /ispyagentdvr/media/old

⁠Notes

Audio playback on Linux hosts: if action sounds do not play through the host's speakers (Debian/Ubuntu etc.), add the following to your Compose file:

    group_add:
        - audio
    devices:
        - /dev/snd:/dev/snd

ARM boards: Raspberry Pi 4 and newer may support limited hardware acceleration with the right host setup. Performance varies; if you find a reliable VAAPI/VPU configuration, share it on GitHub and it can be documented with credit.

Before submitting an issue:

• Update Docker Engine to the latest available version, especially on macOS, and check whether the issue persists.
• Check <agent-ip>:<port>/logs.html for errors.
• On Raspberry Pi 5, use Ubuntu or Ubuntu Server as the host OS. A Debian bug currently breaks Agent DVR (and other .NET applications) on the Pi 5; other Raspberry Pi models are not affected at the time of writing.
• Include your Compose file or docker run command and the relevant logs.html output in the report.

Version history

• 7.9.4.0: First version published as the official ispysoftware/agentdvr image. FFmpeg 9 is bundled (LGPL build); the GPL build is an optional in-app download
• 7.2.0.0: Breaking: a new volume mapping is required for persistent AI model storage: /AgentDVR/Media/Models
• 6.6.2.0: Breaking: directory structure reverted to /AgentDVR from /home/agentdvr/AgentDVR. Take particular care to apply this change in unRAID, Synology and other GUI-based container managers
• 6.6.2.0: Base image changed to Debian Trixie from Bookworm
• 6.6.2.0: Updated Intel driver to 25.31.34666.3 and AMD Mesa driver to 25.2.2-1
• 6.6.2.0: armhf builds switched to FFmpeg from Debian SID after Jellyfin dropped armhf support
• 6.5.7.0: Breaking: ZSTD compression applied to reduce image size and bandwidth. Requires Docker Engine 23.0+ (or Podman Machine v5.1+)
• 6.3.4.0: Updated Intel GPU driver to Compute Runtime 25.18.33578.6, AMD Mesa driver to 25.0.7-1 and jellyfin-ffmpeg to 7.1.1-6
• 6.0.9.0: Updated Intel GPU driver and jellyfin-ffmpeg to 7.0.2-9
• 6.0.1.0: Added driver support for Intel Battlemage GPUs
• 5.8.4.0: Breaking: configuration file format changed from XML to JSON
• 5.8.1.0: FFmpeg updated from 6.0.1 to 7.0.2
• 5.8.1.0: The image became fully backwards compatible with the older doitandbedone/ispyagentdvr image; no directory mapping changes are needed when switching, except in unRAID/Synology and other GUI-based container managers, where the documented mappings must be applied

⁠Issues & Requests

For issues or requests specific to this Docker image, use the image's GitHub repository: https://www.github.com/ispysoftware/agentdvr-docker⁠

For Agent DVR issues and requests, visit: https://www.reddit.com/r/ispyconnect/⁠

For details of the custom base image this container builds on, see: https://github.com/ispysoftware/ispyagentdvr-base-image⁠