How I Install & Use Agent DVR on a Raspberry Pi 5 + Docker —Turning a Raspberry Pi Into a Smart Security Camera Hub

Have an unused Raspberry Pi at home? You can turn it into a smart security hub.

In this tutorial, I’ll show you how to install iSpy Agent DVR on a Raspberry Pi. Tired of managing multiple budget security cameras, each with its own app and cloud storage subscription? With iSpy Agent DVR and a Raspberry Pi, you can build your own self-hosted surveillance system that supports hundreds of IP camera models without relying on paid cloud storage.

I’ve rewritten this guide to use Docker instead of the native installer.

Quick Answer: How to Run Agent DVR

To run Agent DVR (iSpy) on a Raspberry Pi, install Docker on a 64-bit version of Raspberry Pi OS, then deploy the official ispysoftware/agentdvr image using Docker Compose. You’ll find a tested Docker Compose file in the following sections.

Use host networking to allow Agent DVR to automatically discover cameras on your network. Set TZ to your local time zone and make sure PUID and PGID match your user account. You can check these values by running the id command.

Start Agent DVR with:

docker compose up -d

Once the container is running, open http://<raspberry-pi-ip>:8090 in your browser. Create an administrator account and add your camera.

Getting to Know iSpy and Agent DVR

iSpy is a video surveillance application for Windows that was first released in 2007. Its modern successor, Agent DVR, was rebuilt from the ground up and released in 2022. Unlike the original iSpy software, Agent DVR supports Windows, macOS, Linux, Docker, and Raspberry Pi. It also features a web-based interface that you can access from any browser.

Since iSpy is no longer actively developed and all new features are being added to Agent DVR, this tutorial focuses on installing Agent DVR.

If you plan to install Agent DVR on Windows, I have made a guide on how to install Agent DVR on Windows.

Is Agent DVR Free?

Agent DVR is free to download and use locally for personal use. However, features such as remote access through the Agent DVR platform, mobile app access, cloud storage, and business use require a subscription.

In my tests, the free version also limited local access to a single user, as indicated on the settings screen.

Is Agent DVR Open Source?

Not as far as I could verify.

The older iSpy for Windows is described as open-source software, but Agent DVR is offered as free software for personal, local use. I couldn’t find an official source code repository or download page for Agent DVR’s source code.

Can Agent DVR Be Used on Self-Hosted Infrastructure?

Yes, you can run Agent DVR on your own server.

This allows your cameras to connect directly to your server without relying on the camera manufacturer’s cloud servers. It also gives you greater control over your footage and privacy.

Device Benchmarks

In general, Agent DVR supports devices with the following specifications:

• Disk Space: Approximately 1.2 GB for the Docker image and container.
• RAM: Around 170 MB when idle, increasing to 390–440 MB when streaming one camera.
• CPU: Approximately 30% of one CPU core when using the camera’s 640×352 substream, and around 50% when using the 1920×1080 main stream.
• License: The free version is limited to personal, local use and supports only one user account.

Benchmarks: Agent DVR on a Raspberry Pi 5 (2 GB)

These figures are based on measurements from my own setup.

You can find the hardware details and software versions in the badge at the beginning of this post. For testing, I used Raspberry Pi OS Lite (64-bit) and an ONVIF-compatible IP camera with two available streams: 640×352 and 1920×1080.

I kept the live view open in a web browser throughout the camera tests.

Storage Requirements and Startup Time

• Docker image for AgentDVR: 1.8 GB
• Image download: 43.7 s
• Container start: 6.2 s
• Total for docker compose up -d: 50 s

Here is the output when I run the docker image ls command after downloading the Agent DVR image:

IMAGE                                                   ID             DISK USAGE   CONTENT SIZE
ispysoftware/agentdvr:latest   df02347cb25a       1.18GB          273MB

Download time depends on your internet connection. Recorded footage is stored separately in the directory you map to the recordings folder.

CPU and RAM

In Docker, 100% CPU usage represents one fully utilized CPU core. Since the Raspberry Pi 5 has four cores, 50% means half of one core, or approximately 12.5% of the total CPU capacity.

For the camera tests, I collected 12 samples at 5-second intervals.

What I Learned

• Use the substream for live viewing. Setting the Live URL to the 640×352 substream reduced CPU usage by approximately 20 percentage points compared to the 1920×1080 main stream. When I left this field empty, CPU usage remained close to the HD stream results, suggesting that Agent DVR was using the main stream by default.
• Lower resolution didn’t significantly reduce RAM usage. In my tests, memory usage remained between approximately 390 and 440 MiB with one camera connected, regardless of the stream resolution.
• No hardware video encoding available. Agent DVR couldn’t detect a hardware video encoder on my system, so it fell back to software encoding.

Limitations of These Tests

I tested only one camera on a single Raspberry Pi board.

RAM usage increased slightly between successive tests. I didn’t test video recording, motion detection, AI features, or multiple cameras. The measurement method I used for each test is explained at the end of this post.

What You’ll Need

I recommend adding all the hardware you need to your favorite online shopping cart first. This way, you can estimate the total cost of the project before deciding whether to proceed or remove the items from your cart.

For this project, you’ll only need the following hardware:

• Raspberry Pi Single-Board Computer, along with a suitable power supply. You can also use a compatible smartphone charger with a micro-USB connector rated for at least 3A. According to the Agent DVR FAQ, Raspberry Pi 4 and newer models are supported.
• High-Speed microSD Card. I recommend choosing a high-capacity card because you’ll need enough storage for your video recordings. With a Raspberry Pi 5, you can also use a faster NVMe SSD with an M.2 HAT. An SSD is generally better suited to frequent write operations than a microSD card.
• ONVIF-Compatible IP Camera. I strongly recommend choosing a camera that supports ONVIF to make it easier to connect to Agent DVR.

How I Installed Agent DVR on a Raspberry Pi 5 — Here Are the Steps

1. Set Up Raspberry Pi OS

The first step is installing the Raspberry PI OS Lite (we need the 64-bit version) to get a fast and light operating system (headless).

This is the best solution for this project, as the missing desktop environment means that more resources will be focused on running your programs. If you need a desktop environment, you can also use the Raspberry PI OS Desktop, in which case working from its terminal app. 

Make sure your operating system is up to date by running the following command in the terminal:

sudo apt update -y && sudo apt upgrade -y

Next, check whether your system is 64-bit by running the following command in the terminal:

uname -m

You should see the following output:

aarch64

2. Install Docker on Raspberry Pi 5

The recommended way to install Docker is by using its official convenience script. This simple Bash script automates the installation process by adding the required package repositories, installing dependencies, and setting up the latest Docker Engine.

To install Docker, run the following commands in the terminal:

curl -fsSL https://get.docker.com -o get-docker.sh

The second command may take a few minutes to complete as it downloads the required packages for your Raspberry Pi’s architecture and installs them.

sudo sh get-docker.sh

To verify that Docker was installed successfully, run the following command:

sudo docker version
docker compose version

This command displays key information about your Docker installation, including the system architecture shown in the Arch field. The output should look similar to this:

pi@raspberrypi:~ $ sudo docker version
Client: Docker Engine - Community
 Version:           26.1.4
 API version:       1.45
 Go version:        go1.21.11
 Git commit:        5650f9b
 Built:             Wed Jun  5 11:29:12 2024
 OS/Arch:           linux/arm64
 Context:           default

Server: Docker Engine - Community
 Engine:
  Version:          26.1.4
  API version:      1.45 (minimum version 1.24)
  Go version:       go1.21.11
  Git commit:       de5c9cf
  Built:            Wed Jun  5 11:29:12 2024
  OS/Arch:          linux/arm64
  Experimental:     false
 containerd:
  Version:          1.6.33
  GitCommit:        d2d58213f83a351ca8f528a95fbd145f5654e957
 runc:
  Version:          1.1.12
  GitCommit:        v1.1.12-0-g51d5e94
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

If you want to run Docker commands without using sudo, you can add your user account to the docker group.

For the default pi user, run the following command:

sudo usermod -aG docker pi

You’ll need to reboot your Raspberry Pi, or at least log out and log back in, for the changes to take effect.

sudo reboot

Once your Raspberry Pi has rebooted, you’re ready to test the basic Docker commands covered in the following sections.

3. Install Agent DVR Using Docker Compose

Create a project directory along with the subfolders Agent DVR will need:

mkdir -p ~/agentdvr/{config,recordings,models,commands}
cd ~/agentdvr

Next, run this command to edit the file:

nano docker-compose.yml

Paste the following content into the docker-compose.yml file:

services:
  ispyagentdvr:
    image: ispysoftware/agentdvr:latest
    container_name: ispyagentdvr
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - AGENTDVR_WEBUI_PORT=8090
      - TZ=Asia/Jakarta
    volumes:
      - ./config:/AgentDVR/Media/XML
      - ./recordings:/AgentDVR/Media/WebServerRoot/Media
      - ./models:/AgentDVR/Media/Models
      - ./commands:/AgentDVR/Commands
    restart: unless-stopped

Press Ctrl + X, then press Y to save the file.

What each part does:

• image: Specifies the official Agent DVR Docker image from Docker Hub.
• network_mode: host: Allows the container to share the Raspberry Pi’s network, making it easier for Agent DVR to discover cameras on your local network.
• PUID and PGID: Specify the user and group IDs that own the files. The default first user on Raspberry Pi OS usually has an ID of 1000. Run the id command to check your actual IDs.
• AGENTDVR_WEBUI_PORT: Sets the web interface port to 8090.
• TZ: Sets your time zone. Make sure to change it to your local time zone; otherwise, recording timestamps may be incorrect.
• volumes: Stores your configuration (config), recordings (recordings), AI models (models), and custom commands (commands) outside the container. This ensures your data remains intact when you update or recreate the container.

Start the container by running the following command:

docker compose up -d

Once the command finishes, wait about 30 seconds. On its first startup, Agent DVR needs some time to create its folders and initialize the databases. The startup log also indicates that this process may take a little while.

Next, verify that Agent DVR is running:

docker compose ps

The container status should show Up, followed by healthy after a short time. You can also check the logs to confirm that the web interface is ready and listening on port 8090:

pi@raspberrypi:~/agentdvr $ docker compose logs -f | grep "Accepting http connections"
ispyagentdvr  | Listen: Accepting http connections at http://*:8090/

Why I Chose Host Networking?

With Docker’s default bridge network mode, the container operates on a separate network. In my tests, Agent DVR couldn’t automatically discover my camera. The detected devices list remained empty, and the logs reported that no network devices were found.

After switching to network_mode: host, Agent DVR immediately displayed a “New Devices Found” message when I opened the web interface. My camera also appeared in the detected devices list.

Host networking comes with a security trade-off: the container’s ports are directly exposed on your Raspberry Pi. For this reason, keep Agent DVR accessible only within your home network and don’t forward these ports through your router.

Agent DVR uses the following ports:

• 8090 (TCP): Web interface.
• 3478: TURN server.
• 50000–50100 (UDP): TURN server port range.

If you prefer Docker’s default bridge network mode, replace network_mode: host with the following lines in your Docker Compose file. You’ll also need to add your camera manually.

ports:
- 8090:8090
- 3478:3478/udp
- 50000-50100:50000-50100/udp

Where to Store Your Recordings?

By default, Agent DVR stores recordings in the recordings folder on your microSD card. However, for continuous recording, I recommend using an external USB drive or NVMe SSD instead.

First Access to the DVR Agent on Raspberry Pi

From another computer on your network, open http://<raspberry-pi-ip>:8090 in a web browser. The first screen will prompt you to select your preferred language.

Next, you’ll see a Welcome to Agent DVR window with fields for the server name and a Tuning setting. In my case, the default tuning option was Balanced. However, some documentation recommends Capacity for Raspberry Pi models with 2 GB of RAM. I kept the default setting, but you can change it later in the server settings.

Enter a recognizable name for your server, click OK, and then close the Help window.

Next, Agent DVR will display a list of useful links. Click OK to continue.

After that, the Agent DVR dashboard will appear with an empty grid. This is normal on the first launch. Once you add your first camera, its live stream will appear here.

Setting Up Agent DVR on Raspberry Pi

Agent DVR starts without a password, so the first thing you should do is create an administrator account. This step is optional, but I recommend setting a password to improve security.

Click the Server Menu icon in the top-right corner. It’s the first of the four icons.

Under the Configuration column, select Settings.

Open the drop-down menu at the top, which currently displays General, and select Users under General Settings.

On the new page, click the + button to add your first user.

Enter a username, password, and password confirmation. Enable the “Is Admin” option to make this account an administrator. Agent DVR will display a warning if you try to create the first account without administrator privileges.

Click OK to save the account, then click OK again in the Users window.

The login screen won’t appear automatically, so refresh the page and sign in with your new account. The free version allows only one user account, so choose a strong, unique password. This helps protect access to your cameras and recorded footage.

Adding an IP Camera to Agent DVR on Raspberry Pi

With host networking enabled, Agent DVR can automatically discover cameras on your local network. After you log in, a New Devices Found message should appear.

Click Manage to continue.

Select your camera (mine appears as an ONVIF device), then click OK.

Agent DVR will then prompt you for your Camera Login. Enter your camera’s username and password. These are separate from your Agent DVR account credentials. For many cameras, you can find or set them in the manufacturer’s app.

Agent DVR saves these credentials as the default login for cameras you add later. You can change them in the settings, but using the same username and password across your cameras makes setup easier.

Click Add to add the camera. Its live feed will then appear on the dashboard.

Back Up and Remove Agent DVR From Your Raspberry Pi

Backup

Stop the container, then create an archive of the project folders:

cd ~/agentdvr
docker compose stop
tar czf ~/agentdvr-backup.tar.gz config commands models docker-compose.yml
docker compose start

I excluded the recordings because they can take up a lot of storage space. If you want to keep them, copy the recordings folder separately. You can also find a Backup/Restore option in the Configuration column of the Server Menu.

Remove

Run the following commands in the terminal to remove Agent DVR from your Raspberry Pi:

cd ~/agentdvr
docker compose down
docker image rm ispysoftware/agentdvr:latest

If you also delete the ~/agentdvr folder, you’ll permanently remove your recordings and configuration files.

Installation Troubleshooting

I Can’t Access the Web Interface (Connection Refused)

Check whether the container is running:

docker compose ps

Then check the logs for errors:

docker compose logs --tail 40

On the first startup, Agent DVR may take about 30 seconds to initialize, so give it some time.

Also, make sure you’re using your Raspberry Pi’s correct IP address, port 8090, and a 64-bit operating system. I tested this setup on the 64-bit version of Raspberry Pi OS.

Agent DVR Shows Port 80 Instead of 8090

This is only a cosmetic issue with the startup banner.

In my tests, the actual web interface port matched the value set in AGENTDVR_WEBUI_PORT (8090), even though the banner displayed port 80.

Agent DVR Can’t Find My Camera

Use:

network_mode: host.

With Docker’s default bridge network, the camera discovery list remained empty in my tests. If you add the camera manually, enter its IP address and ONVIF service port (8080 in my case). Also, check that the camera’s username and password are correct.

Finally, assign your camera a static IP address or create a DHCP reservation on your router. If its IP address changes, Agent DVR may lose the connection.

The Login Screen Doesn’t Appear After Creating a User

Refresh the browser page to display the login screen.

Frequently Asked Questions (FAQs)

Is Agent DVR free?

Agent DVR is free to download and use locally for personal use. However, remote access, mobile app access, cloud storage, and business use require a subscription. In my tests, I didn’t need to enter a license key to use it locally.

Is Agent DVR open source?

Not as far as I could verify. See the section about iSpy and Agent DVR for more details.

What’s the difference between iSpy and Agent DVR?

iSpy is the original Windows-only desktop application, released in 2007. Agent DVR is its cross-platform, browser-based successor, released in 2022.

Can I run Agent DVR on a Raspberry Pi 3?

According to the official FAQ, Agent DVR supports Raspberry Pi 4 and newer models.

Does Agent DVR work without an internet connection?

Yes. Agent DVR supports offline local use, including video recording and motion detection.

Does Agent DVR support ONVIF cameras?

Yes. It supports ONVIF cameras and automatic device discovery. In my tests, discovery worked when I used Docker’s host networking mode.

How many cameras can a Raspberry Pi 5 with 2 GB of RAM handle?

I tested only one camera, so I can’t give a reliable maximum. With one camera connected, the container used approximately 400 MiB of RAM and between 30% and 50% of one CPU core, depending on the stream resolution.