kerberos-io/agent: Open-Source Video Surveillance for Edge & Cloud

kerberos-io/agent: Open-Source Video Surveillance for Edge & Cloud

Managing video surveillance infrastructure has traditionally meant wrestling with proprietary hardware, expensive licenses, and vendor lock-in. Developers and DevOps^{↗ Bright Coding Blog} teams need a surveillance stack that deploys like any other modern application—containerized, infrastructure-as-code friendly, and extensible without legal friction. kerberos-io/agent is an open-source, MIT-licensed video management agent built in Go that processes single-camera feeds with motion detection, live streaming, and cloud integration. Designed for ARMv6 through AMD64 architectures, it runs on Raspberry Pi devices at the edge or scales into Kubernetes clusters in the cloud. With 1,073 GitHub stars and active development through July 2026, it represents a mature alternative to closed-source surveillance platforms.

What is kerberos-io/agent?

kerberos-io/agent is the core component of the broader Kerberos.io ecosystem, maintained by the Kerberos.io project team. Written primarily in Go with a React^{↗ Bright Coding Blog}-based web interface, it functions as an isolated, single-camera video surveillance agent. Each instance handles one camera feed—whether from an IP camera via RTSP, a USB camera, or a Raspberry Pi camera module—processing that stream for live viewing, motion-triggered or continuous recording, and optional cloud upload.

The project sits at the intersection of IoT edge computing and video analytics infrastructure. Unlike monolithic NVR (Network Video Recorder) software that centralizes multiple cameras on one server, Kerberos Agent follows a distributed agent model: one container or binary per camera. This architecture simplifies horizontal scaling, fault isolation, and deployment automation through standard DevOps tooling.

The MIT license is strategically significant. Version 2 of Kerberos.io restricted commercial usage; version 3 (this codebase) removes that limitation entirely. Organizations can modify, redistribute, and embed the agent without license fees or source disclosure requirements. The project maintains CI/CD through CircleCI and GitHub Actions (Go, React, and CodeQL workflows), with published Go package documentation and coverage reporting via Codecov.

The broader Kerberos.io stack includes Kerberos Factory for orchestration, Kerberos Vault for storage abstraction, and Kerberos Hub for centralized management—allowing users to build everything from personal home monitoring to enterprise multi-site deployments.

Key Features

Multi-Architecture & Deployment Flexibility

The agent compiles for ARMv6, ARMv7, ARM64, and AMD64 targets. This covers Raspberry Pi Zero through Pi 4/5, NVIDIA Jetson boards, Intel NUCs, virtual machines, and full Kubernetes clusters. Deployment options span Docker^{↗ Bright Coding Blog}, Docker Compose, Kubernetes, Red Hat OpenShift with Ansible, Terraform, Salt, Balena Cloud, and Snap packages.

Codec-Aware Processing

The agent supports both H.264 and H.265 (HEVC) streams, with intelligent multi-stream handling: record in H.265 for storage efficiency while live-streaming in H.264 for browser compatibility. The README explicitly notes WebRTC requires H.264/PCM, while H.265 offers ~50% file size reduction but with licensing considerations and motion artifact trade-offs.

Motion & Conditional Recording

Recording triggers include continuous capture, motion detection with configurable pixel-change thresholds, region polygons, time-based scheduling, and webhook-driven conditions. Pre-recording (default 10s) and post-recording (default 20s) buffers ensure complete event capture. Maximum recording length and fragmented MP4 output for HLS streaming are configurable.

Encryption & Security

End-to-end encryption uses RSA and AES for MQTT communications between agents and hub services. Recordings support AES-256-CBC encryption at rest with user-provided keys. RSA signing validates recording provenance. The default credentials (root/root) are explicitly flagged for immediate change in production.

Integration Ecosystem

Outputs include webhooks, MQTT topics, and script execution on motion or recording events. Cloud storage targets encompass Kerberos Hub (S3-backed SaaS), Kerberos Vault (self-hosted storage abstraction), and Dropbox—with MinIO, Storj, Google Drive, and FTP marked as work-in-progress. A documented REST API with Swagger enables programmatic control.

Low Resource Footprint

The Go-based machinery component emphasizes minimal CPU and memory usage, critical for edge deployments on constrained hardware. The React UI provides browser-based configuration, live viewing, and recording playback without requiring desktop client installation.

Use Cases

Home & Small Business Surveillance

A single Raspberry Pi 4 with USB camera (via RTSP proxy sidecar) runs the agent in Docker with host networking. Local recordings persist on attached storage, with optional Dropbox upload for off-site backup. The low power draw and silent operation suit residential environments where traditional NVR hardware would be excessive.

Distributed Retail or Branch Monitoring

Each store location deploys one agent per camera via Balena Cloud, enabling centralized fleet management, over-the-air updates, and encrypted HTTPS endpoints without manual VPN configuration. Recordings upload to Kerberos Vault with on-premise MinIO backend, maintaining data sovereignty while providing corporate visibility.

Industrial Edge Analytics

On factory floors, agents on NVIDIA Jetson devices process H.265 streams from IP cameras for high-quality archival recording, while publishing motion events via MQTT to plant SCADA systems. The real-time keyframe processing option feeds downstream ML inference pipelines for defect detection or safety compliance.

Kubernetes-Native Security Operations

Security teams deploy agents as StatefulSets with persistent volume claims for configuration and recordings, integrating with existing Prometheus/Grafana monitoring and GitOps workflows via Terraform or Ansible. The environment-variable-driven configuration supports secret management through Kubernetes native mechanisms or external tools like Vault.

Temporary or Event-Based Deployment

For construction sites, festivals, or emergency response, agents deploy on battery-powered edge devices with 4G/5G backhaul. Fragmented MP4 recording enables near-real-time HLS streaming to incident command, while local encryption protects footage integrity if hardware is compromised.

Installation & Setup

The fastest path to running kerberos-io/agent uses the published Docker image. Ensure your camera provides an RTSP H.264 or H.265 stream, or deploy the camera-to-rtsp sidecar for USB/Raspberry Pi cameras.

Basic Docker Deployment (IP Camera):

# Expose agent web UI on host port 80, auto-restart on failure
docker run -p 80:80 --name mycamera -d --restart=always kerberos/agent:latest

The -p 80:80 flag maps container port 80 to host port 80 for web access. --restart=always ensures the agent recovers from crashes or host reboots.

Host Network Mode (USB/Raspberry Pi Camera with RTSP Sidecar):

# Required when connecting to local RTSP proxy on same host
docker run --network=host --name mycamera -d --restart=always kerberos/agent:latest

Host networking eliminates NAT complications when the agent connects to a localhost RTSP stream from the sidecar container.

Persistent Configuration and Recordings:

# Mount host directories for config and recordings
docker run -p 80:80 --name mycamera \
  -v $(pwd)/agent/config:/home/agent/data/config \
  -v $(pwd)/agent/recordings:/home/agent/data/recordings \
  -d --restart=always kerberos/agent:latest

Set appropriate permissions before mounting:

chmod -R 755 kerberos-agent/
chown 100:101 kerberos-agent/ -R

The UID/GID 100:101 corresponds to the agent's internal user. Permission mismatches cause write failures for recordings and configuration updates.

Environment-Variable Configuration:

docker run -p 80:80 --name mycamera \
  -e AGENT_NAME=mycamera \
  -e AGENT_TIMEZONE=Europe/Brussels \
  -e AGENT_CAPTURE_IPCAMERA_RTSP=rtsp://fake.kerberos.io/stream \
  -e AGENT_CAPTURE_CONTINUOUS=true \
  -d --restart=always kerberos/agent:latest

Environment variables override file-based configuration, enabling GitOps workflows and secret injection without rebuilding images.

Snap Installation (Ubuntu/Debian systems):

sudo snap install kerberosio
sudo kerberosio.agent -action=run -port=80

Snap configuration resides at /var/snap/kerberosio/common.

Balena Cloud Deployment:

Click the deploy button on Balena Hub or use the repository's deploy-with-balena link for fleet management with automatic HTTPS endpoints and remote SSH access.

Real Code Examples

The README provides explicit commands and configuration patterns. Below are reproduced examples with contextual explanation.

Example 1: Decrypting AES-256-CBC Encrypted Recordings

When encryption is enabled, recordings require decryption with the symmetric key:

# Decrypt single recording with OpenSSL
openssl aes-256-cbc -d -md md5 \
  -in encrypted.mp4 -out decrypted.mp4 \
  -k your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8

The -md md5 specifies message digest for key derivation. For batch operations, use the agent binary directly:

# Decrypt entire directory of recordings
go run main.go -action decrypt ./data/recordings your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8

# Decrypt single file
go run main.go -action decrypt ./data/recordings/video.mp4 your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8

This demonstrates the agent's dual nature as both runtime service and administrative tool. The same binary that serves the web API handles cryptographic operations, reducing deployment complexity.

Example 2: Development Environment Setup (Codespaces)

For contributors, GitHub Codespaces provides preconfigured environments:

# Terminal A: Start Go machinery backend
cd machinery/
go run main.go -action run -port 80

# Terminal B: Start React development server
cd ui/
yarn start

The machinery serves API and static assets on port 80; the React dev server runs on port 3000 with hot reloading. Codespace port forwarding requires setting port 80 visibility to public to avoid CORS errors when the UI communicates with the machinery API.

Example 3: Production Build Pipeline

# Build optimized React assets
cd ui
yarn build
# build directory automatically moves to machinery/

# Compile single static binary
cd machinery
go build

The yarn build command generates minified assets and moves them to machinery/build. The Go binary embeds these assets, serving the complete application from a single executable—ideal for edge deployment where container runtimes may be unavailable.

Example 4: Docker Image Build

# Build from repository root using prebuilt base image
docker build -t kerberos/agent .

The kerberos/base:xxx base image includes Golang, FFmpeg, and OpenCV, accelerating compilation by avoiding repeated dependency installation.

Advanced Usage & Best Practices

Codec Selection Strategy

The README's H.264 versus H.265 analysis deserves serious attention. For environments requiring browser-based playback without transcoding infrastructure, H.264 remains the pragmatic choice despite larger files. H.265 suits archival-heavy scenarios with dedicated playback clients or where storage costs dominate bandwidth concerns. The agent's multi-stream capability—H.265 recording with H.264 live view—offers a balanced approach when camera hardware supports dual streams.

Security Hardening

Beyond changing default credentials, enable MQTT encryption with organization-managed RSA keypairs. The AGENT_ENCRYPTION_FINGERPRINT variable ensures key rotation traceability. For air-gapped deployments, AGENT_OFFLINE=true prevents any external connection attempts, eliminating data exfiltration vectors through misconfigured cloud settings.

Storage Lifecycle Management

The auto-cleanup parameters (AGENT_AUTO_CLEAN_MAX_SIZE, AGENT_AUTO_CLEAN_MIN_FREE_SPACE) prevent disk exhaustion on long-running edge devices. Setting AGENT_REMOVE_AFTER_UPLOAD=true with dual Vault targets (primary and secondary) creates resilient archival without local retention burden—though verify upload success before enabling deletion in critical applications.

WebRTC Traversal

For remote live streaming behind NAT, the default STUN/TURN configuration uses Kerberos.io's hosted infrastructure. Enterprise deployments should substitute internal TURN servers (AGENT_TURN_URI, AGENT_TURN_USERNAME, AGENT_TURN_PASSWORD) to maintain traffic control and avoid dependency on external services.

Monitoring Integration

While not explicitly documented, the MQTT output topics and REST API enable integration with existing observability stacks. Motion events can feed into Prometheus via custom exporters, or trigger PagerDuty incidents through webhook configurations.

Comparison with Alternatives

ZoneMinder offers mature centralized management for large camera counts on single servers but carries GPL licensing implications and less container-native tooling. Frigate excels at on-device ML inference with Coral TPUs but orients toward Home Assistant ecosystems rather than multi-cloud enterprise deployments. kerberos-io/agent occupies a middle ground: simpler per-camera scaling, explicit commercial licensing, and infrastructure-as-code deployment patterns that appeal to DevOps-oriented organizations.

FAQ

Q: Can one agent instance handle multiple cameras? A: No. Each agent processes exactly one camera feed. Scale horizontally with multiple containers or binaries.

Q: What cameras are compatible? A: Any camera providing RTSP H.264 or H.265, including IP cameras, USB cameras, and Raspberry Pi cameras via the RTSP proxy sidecar. Community-verified models are tracked in GitHub issue #59.

Q: Is the MIT license truly unrestricted for commercial use? A: Yes. Version 3 explicitly permits commercial usage, modification, and redistribution with license attribution. Version 2 had commercial restrictions; do not confuse the two.

Q: How do I access the web interface after deployment? A: Navigate to the host IP on port 80 (or mapped port). Default credentials are username root, password root—change immediately via environment variables or configuration file.

Q: Can recordings be encrypted without using Kerberos Hub? A: Yes. Enable AGENT_ENCRYPTION_RECORDINGS=true with AGENT_ENCRYPTION_SYMMETRIC_KEY for AES-256-CBC encryption, decryptable with OpenSSL or the agent binary.

Q: What happened to version 2? A: Version 3 is a complete technology switch (Go/React versus previous stack) with architectural changes. The v2 repositories are succeeded by this unified agent repository.

Q: Is there a hosted/SaaS option? A: Kerberos Hub provides SaaS functionality, but the agent itself is self-hosted. The agent can upload to Hub, Vault, or third-party storage without requiring Hub subscription.

Conclusion

kerberos-io/agent delivers a genuinely open, infrastructure-native approach to video surveillance that respects developer workflows. The MIT license removes legal barriers that constrain competing projects; the per-agent architecture aligns with modern microservices and IoT deployment patterns; and the multi-arch builds ensure viability from hobbyist Raspberry Pi projects to enterprise Kubernetes fleets.

The project is not without gaps—ML inference requires external integration, the WebRTC stack demands H.264, and some cloud storage targets remain work-in-progress. But for organizations prioritizing operational simplicity, license clarity, and DevOps-compatible deployment, these trade-offs are acceptable.

The codebase shows healthy maintenance with commits through mid-2026, active CI/CD, and responsive documentation. Whether you're replacing a proprietary NVR, building edge analytics infrastructure, or simply need reliable motion-triggered recording without subscription fees, kerberos-io/agent warrants evaluation.

Clone the repository, run the Docker quickstart, and verify compatibility with your camera hardware: https://github.com/kerberos-io/agent