Kerberos Agent

Docker Hub | Documentation | Website | View Demo

Before you continue, this repository discusses one of the components of the Kerberos.io stack, the Kerberos Agent, in depth. If you are looking for an end-to-end deployment guide have a look here.

Kerberos Agent is an isolated and scalable video (surveillance) management agent made available as Open Source under the MIT License. This means that all the source code is available for you or your company, and you can use, transform and distribute the source code; as long you keep a reference of the original license. Kerberos Agent can be used for commercial usage (which was not the case for v2). Read more about the license here.

:thinking: Prerequisites

• An IP camera which supports a RTSP H264 or H265 encoded stream,
  • (or) a USB camera, Raspberry Pi camera or other camera, that you can transform to a valid RTSP H264 or H265 stream.
• Any hardware (ARMv6, ARMv7, ARM64, AMD64) that can run a binary or container, for example: a Raspberry Pi, NVidia Jetson, Intel NUC, a VM, Bare metal machine or a full blown Kubernetes cluster.

:video_camera: Is my camera working?

There are a myriad of cameras out there (USB, IP and other cameras), and it might be daunting to know if Kerberos Agent will work for your camera. Therefore we are listing all the camera models that are acknowlegded by the community. Feel free to add your camera to the list as well!

:books: Overview

Up and running in no time

1. Quickstart - Docker
2. Quickstart - Balena
3. Quickstart - Snap

Introduction

1. A world of Kerberos Agents

Running and automation

1. How to run and deploy a Kerberos Agent
2. Access the Kerberos Agent
3. Configure and persist with volume mounts
4. Configure with environment variables

Insights

1. Encryption
2. H264 vs H265

Contributing

1. Security vulnerability reporting
2. Contribute with Codespaces
3. Develop and build
4. Building from source
5. Building for Docker

Varia

1. Support our project
2. What is new?
3. Contributors

Direct S3 recording layout

Direct S3 uploads store recordings as <s3.username>/yyyy/mm/dd/<timestamp>-<deviceKey>.mp4. The timestamp is the recording's Unix timestamp in milliseconds, and the date is its UTC date, not the upload date. Timestamp and device key come from the recording's .metadata upload checkpoint, which stores the timestamp in milliseconds. The uploader also preserves checkpoint duration, FPS (when available), and encryption status as S3 object metadata. The device key must be non-empty and contain no path separators. Retried uploads use the same object key, even after midnight. Millisecond precision keeps recordings starting within the same second distinct.

This replaces the previous <s3.username>/<filename>.mp4 layout for new uploads. Existing objects are not moved; consumers of direct S3 uploads must support both layouts when reading historical recordings. Updated Kerberos Vault deployments use the same filename and dated layout under the authenticated account directory for both direct Vault uploads and Hub-proxied uploads.

Only historical recordings with missing, empty, or FPS-only queue markers fall back to the legacy filename format and configured Agent key. A structured checkpoint takes precedence over both the filename and current configured key; an invalid or unreadable checkpoint is reported as an upload error, not silently replaced with filename-derived values. For older structured checkpoints, missing camera name, region, and change count are recovered from a validated legacy filename. Populated checkpoint fields take precedence, and the checkpoint timestamp and device key remain authoritative.

The shorter filename cannot be decoded by legacy filename-only consumers. Integrations must preserve structured recording metadata, including the device key (productid) and recording timestamp (event-timestamp), as well as the full object key.

Local recording layout

New local recordings are stored under data/recordings/yyyy/mm/dd/<timestamp>-<deviceKey>.mp4, using the recording's UTC start date and Unix-millisecond timestamp. For example: data/recordings/2026/01/02/1767355200123-device-key.mp4. The filename no longer embeds the camera name, region, change count, or duration, and it does not change when the recording is finalized. Those attributes, together with FPS and encryption status, are captured in the .metadata upload checkpoint and sent as structured HTTP/tus metadata.

Existing flat recordings and dated recordings with older long filenames remain supported without a migration. Recording lists, day filters, playback, uploaders, and automatic cleanup handle both filename formats and layouts. Upload queue checkpoints remain flat in data/cloud/. Successful-upload removal also resolves both local layouts. Deploy the updated Vault alongside Agent for canonical <account-directory>/yyyy/mm/dd/<timestamp>-<deviceKey>.mp4 storage keys and metadata-driven Hub integration events. Directory decryption also processes dated subdirectories and writes each output to a sibling decrypted/ directory; those outputs are excluded from recording lists and automatic cleanup.

Quickstart - Docker

The easiest way to get your Kerberos Agent up and running is to use our public image on Docker hub. Once you have selected a specific tag, run docker command below, which will open the web interface of your Kerberos agent on port 80, and off you go. For a more configurable and persistent deployment have a look at Running and automating a Kerberos Agent.

docker run -p 80:80 --name mycamera -d --restart=always kerberos/agent:latest

If you want to connect to a USB or Raspberry Pi camera, you'll need to run our side car container which proxies the camera to an RTSP stream. In that case you'll want to configure the Kerberos Agent container to run in the host network, so it can connect directly to the RTSP sidecar.

docker run --network=host --name mycamera -d --restart=always kerberos/agent:latest

Quickstart - Balena

Run Kerberos Agent with Balena Cloud super powers. Monitor your Kerberos Agent with seamless remote access, over the air updates, an encrypted public https endpoint and much more. Checkout our application video-surveillance on Balena Hub, and create your first or fleet of Kerberos Agent(s).

Quickstart - Snap

Run Kerberos Agent with our Snapcraft package.

 snap install kerberosio

Once installed you can find your Kerberos Agent configration at /var/snap/kerberosio/common. Run the Kerberos Agent as following

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

A world of Kerberos Agents

The Kerberos Agent is an isolated and scalable video (surveillance) management agent with a strong focus on user experience, scalability, resilience, extension and integration. Next to the Kerberos Agent, Kerberos.io provides many other tools such as Kerberos Factory, Kerberos Vault, and Kerberos Hub to provide additional capabilities: bring your own cloud, bring your own storage, central overview, live streaming, machine learning, etc.

As mentioned above Kerberos.io applies the concept of agents. An agent is running next to (or on) your camera, and is processing a single camera feed. It applies motion based or continuous recording and makes those recordings available through a user friendly web interface. A Kerberos Agent allows you to connect to other cloud services or integrate with custom applications. Kerberos Agent is used for personal applications and scales to enterprise production level deployments. Learn more about the deployment strategies here.

This repository contains everything you'll need to know about our core product, Kerberos Agent. Below you'll find a brief list of features and functions.

• Low memory and CPU usage.
• Simplified and modern user interface.
• Multi architecture (ARMv6, ARMv7, ARM64, AMD64)
• Multi stream, for example recording in H265, live streaming and motion detection in H264.
• Multi camera support: IP Cameras (H264 and H265), USB cameras and Raspberry Pi Cameras through a RTSP proxy.
• Single camera per instance (e.g. one container per camera).
• Low resolution streaming through MQTT and high resolution streaming through WebRTC (only supports H264/PCM).
• Backchannel audio from Kerberos Hub to IP camera (requires PCM ULAW codec)
• Audio (AAC) and video (H264/H265) recording in MP4 container.
• End-to-end encryption through MQTT using RSA and AES (livestreaming, ONVIF, remote configuration, etc)
• Conditional recording: offline mode, motion region, time table, continuous recording, webhook condition etc.
• Post- and pre-recording for motion detection.
• Encryption at rest using AES-256-CBC.
• Ability to create fragmented recordings, and streaming through HLS fMP4.
• Deploy where you want with the tools you use: docker, docker compose, ansible, terraform, kubernetes, etc.
• Cloud storage/persistance: Kerberos Hub, Kerberos Vault and Dropbox. (WIP: Minio, Storj, Google Drive, FTP etc.)
• Outputs: trigger an integration (Webhooks, MQTT, Script, etc) when a specific event (motion detection or start recording ) occurs
• REST API access and documentation through Swagger (trigger recording, update configuration, etc).
• MIT License

How to run and deploy a Kerberos Agent

A Kerberos Agent, as previously mentioned, is a container. You can deploy it using various methods and automation tools, including docker, docker compose, kubernetes and more. To streamline your Kerberos.io experience, we provide concrete deployment examples to speed up your Kerberos.io journey”

We have documented the different deployment models in the deployments directory of this repository. There you'll learn and find how to deploy using:

• Static binary
• Docker
• Docker Compose
• Kubernetes
• Red Hat OpenShift with Ansible
• Terraform
• Salt
• Balena
• Snap

By default, your Kerberos Agents store all configuration and recordings within the container. To help you automate and have a more consistent data governance, you can attach volumes to configure and persist data of your Kerberos Agents and/or configure each Kerberos Agent through environment variables.

Access the Kerberos Agent

Once you have deployed the Kerberos Agent, using one of the deployment models described above, you will be able to access the Kerberos Agent user interface. A login page is presented asking for some credentials.

The default username and password for the Kerberos Agent is:

• Username: root
• Password: root

Please note that you change the username and password for a final installation, see Configure with environment variables below.

Configure and persist with volume mounts

An example of how to mount a host directory is shown below using docker, but is applicable for all of the deployment models and tools described above.

You attach a volume to your container by leveraging the -v option. To mount your own configuration file and recordings folder, run the following commands:

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

More examples for each deployment and automation tool can be found in the deployment section. Be sure to verify the permissions of the directory/volume you are attaching. More information in this issue.

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

Configure with environment variables

Next to attaching the configuration file, it is also possible to override the configuration with environment variables. This makes deploying with docker compose or kubernetes much easier and more scalable. Using this approach, we simplify automation through ansible and terraform.

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

Set AGENT_PORT to change the Agent's internal HTTP port. The environment variable takes precedence over -port. When using Docker, publish the same container port:

docker run -p 8082:8082 \
  -e AGENT_PORT=8082 \
  --name mycamera \
  -d --restart=always kerberos/agent:latest

Health checks and API responses

GET /health is an unauthenticated liveness and diagnostics endpoint for container orchestrators and external monitors. healthy means that the Agent HTTP process can serve requests. Camera streams and Hub connectivity are reported independently in the response, so an external camera or Hub outage does not make Docker restart an otherwise functioning Agent process. Successful probes return 200 OK and are logged at debug level to avoid periodic health checks filling production logs.

curl http://localhost:8082/health

{
  "httpStatusCode": 200,
  "applicationStatusCode": "get_success",
  "entityStatusCode": "healthy",
  "message": "Healthy",
  "metadata": {
    "applicationName": "agent",
    "applicationVersion": "0.0.0",
    "timestamp": 1788710400,
    "path": "/health"
  },
  "data": {
    "health": {
      "description": "Agent HTTP service is healthy",
      "cameraConnected": true,
      "mainStream": {
        "configured": true,
        "connected": true,
        "packagesProcessed": 183421,
        "fps": 29.97,
        "resolution": {
          "width": 1920,
          "height": 1080
        },
        "lastPacketAt": 1788710399
      },
      "subStream": {
        "configured": true,
        "connected": true,
        "packagesProcessed": 91710,
        "fps": 15,
        "resolution": {
          "width": 640,
          "height": 360
        },
        "lastPacketAt": 1788710399
      },
      "hub": {
        "configured": true,
        "connected": true,
        "lastHeartbeatAttemptAt": 1788710398,
        "lastSuccessfulHeartbeatAt": 1788710398
      }
    }
  }
}

Stream packagesProcessed counts complete encoded video access units processed since the Agent process started; it does not count individual fragmented RTP packets. fps is the latest PTS-derived frame-rate estimate. Resolution is the most recently observed encoded width and height. lastPacketAt, Hub heartbeat timestamps, and response metadata timestamps are Unix seconds; 0 means that no value has been observed yet. A stream can be configured but temporarily disconnected.

Hub configured means heartbeat delivery is enabled and has the required URI and key. Hub connected means the most recent heartbeat succeeded and the last success is no more than three minutes old. A failed heartbeat marks it disconnected immediately while retaining the last-success timestamp for diagnosis.

New JSON endpoints should use this Hub-compatible response envelope rather than adding unrelated top-level response shapes. HTTP status describes the transport result, applicationStatusCode describes the operation, entityStatusCode and message describe the domain outcome, metadata carries request/application context, and endpoint-specific content belongs in a typed data object. Client responses must contain safe messages only; detailed internal errors belong in structured logs. Existing endpoints retain their legacy response shapes until they are migrated deliberately.

Secure camera streams (RTSPS)

The Agent accepts rtsps:// camera URLs. Do not use srtsp://; RTSPS is RTSP over TLS. For a Bosch FLEXIDOME micro 3100i, enable Secure RTSP under Network > Network Services and use port 9554:

AGENT_CAPTURE_IPCAMERA_RTSP='rtsps://username:[email protected]:9554/?inst=1'
AGENT_CAPTURE_IPCAMERA_SUB_RTSP='rtsps://username:[email protected]:9554/?inst=2'

Certificate verification is enabled by default. The URL hostname or IP address must match the camera certificate SAN. On this Bosch firmware, RTSPS presents the certificate assigned to HTTPS; there is no separate SRTSP certificate usage. Leave CBS client assigned to the Bosch device certificate.

For a private CA, mount a PEM trust bundle containing every CA certificate needed to build the camera certificate chain and set AGENT_CAPTURE_IPCAMERA_RTSPS_CA_FILE to its path inside the Agent. The bundle is appended to the system roots for camera RTSPS connections only. This Bosch firmware presents only its leaf certificate, so include both the issuing intermediate and root certificates in the bundle. As a temporary fallback, AGENT_CAPTURE_IPCAMERA_RTSPS_INSECURE=true disables certificate verification for camera streams only.

See RTSPS and TLS certificates for the complete Bosch UI, private-CA, deployment, validation, and troubleshooting procedure.

Name	Description	Default Value
LOG_LEVEL	Level for logging, could be "info", "warning", "debug", "error" or "fatal".	"info"
LOG_OUTPUT	Logging output format "json" or "text".	"text"
AGENT_PORT	HTTP web server port. Overrides the -port command-line value and must be between 1 and 65535.	"80"
AGENT_MODE	You can choose to run this in 'release' for production, and or 'demo' for showcasing.	"release"
AGENT_TLS_INSECURE	Specify if you want to use InsecureSkipVerify for the internal HTTP client.	"false"
AGENT_USERNAME	The username used to authenticate against the Kerberos Agent login page.	"root"
AGENT_PASSWORD	The password used to authenticate against the Kerberos Agent login page.	"root"
AGENT_KEY	A unique identifier for your Kerberos Agent, this is auto-generated but can be overriden.	""
AGENT_NAME	The agent friendly-name.	"agent"
AGENT_TIMEZONE	Timezone which is used for converting time.	"Africa/Ceuta"
AGENT_REMOVE_AFTER_UPLOAD	When enabled, recordings uploaded successfully to a storage will be removed from disk.	"true"
AGENT_OFFLINE	Makes sure no external connection is made.	"false"
AGENT_AUTO_CLEAN	Cleans up the recordings directory.	"true"
AGENT_AUTO_CLEAN_MAX_SIZE	If AUTO_CLEAN enabled, cap the recordings directory at this size (in MB). When unset/0, recordings may use the whole disk instead (see AGENT_AUTO_CLEAN_MIN_FREE_SPACE).	"100"
AGENT_AUTO_CLEAN_MIN_FREE_SPACE	When AUTO_CLEAN is enabled and no MAX_SIZE is set, keep at least this much free space (in MB) on the recordings disk before deleting the oldest (already-uploaded first) recordings. Defaults to 5% of the disk.

Remote console access is disabled unless AGENT_REMOTE_ACCESS_ENABLED=true. The Agent also rejects remote session messages unless Hub encryption or end-to-end MQTT encryption is configured and used. A remote shell runs inside the Agent process environment as the Agent operating-system user; it is not an SSH server and does not expose a new network port. Keep the feature disabled on deployments where Hub owners should not have operating-system access.

Resumable upload chunk size

Hub and Vault resumable uploads use AGENT_TUS_CHUNK_SIZE_BYTES as the maximum body size of each tus PATCH request. The value is a number of bytes, not a number of chunks. If the variable is unset or invalid, the Agent uses 8 MiB:

# 8 MiB (default)
AGENT_TUS_CHUNK_SIZE_BYTES=8388608

# 4 MiB: more frequent checkpoints on unstable connections
AGENT_TUS_CHUNK_SIZE_BYTES=4194304

# Disable chunking and send all remaining bytes in one PATCH
AGENT_TUS_CHUNK_SIZE_BYTES=0

Smaller chunks provide more frequent resumable checkpoints but create more HTTP requests. Larger chunks reduce request overhead but require more data to be retransmitted when a request fails.

An HTTP 500 during resumable creation is a server/provider failure, not proof that the recording filename is invalid. Creation errors include up to 4 KiB of the server response, and the final retry error retains the latest failure cause. Created upload sessions remain usable if only the optional creation response body is interrupted; the successful response's Location is retained. Check the corresponding Hub/Vault logs and storage-provider configuration. As a temporary diagnostic workaround, set AGENT_DISABLE_RESUMABLE_UPLOAD=true and restart Agent to use ordinary uploads. This does not change the recording filename or remove its structured metadata, but interrupted uploads restart from the beginning. Remove the override after fixing the provider issue.

Custom metadata headers for Kerberos Vault

Use AGENT_KERBEROSVAULT_CUSTOM_HEADERS to attach your own metadata (for example a site, line, or equipment identifier) to every recording uploaded to Kerberos Vault. The value is a JSON object whose keys are header names and whose values are strings. The Agent sends these as HTTP headers on every upload, and Vault adds them to the metadata object of its integration messages (Kafka, MQTT, SQS, RabbitMQ, etc.):

{
  "timestamp": "2026-09-24T15:06:45Z",
  "key": "agent1/1790262405_3-425_agent1_0-0-0-0_-1_10000.mp4",
  "device": "agent1",
  "metadata": {
    "site_id": "site-1",
    "line_id": "line-2",
    "equipment_id": "equipment-3"
  }
}

The value must be valid JSON on a single line, so wrap it in single quotes in a shell:

docker run -p 80:80 --name mycamera \
  -e AGENT_CLOUD=kstorage \
  -e AGENT_KERBEROSVAULT_URI=https://vault.domain.com/api \
  -e AGENT_KERBEROSVAULT_ACCESS_KEY=xxx \
  -e AGENT_KERBEROSVAULT_SECRET_KEY=xxx \
  -e AGENT_KERBEROSVAULT_DIRECTORY=agent1 \
  -e AGENT_KERBEROSVAULT_CUSTOM_HEADERS='{"site_id":"site-1","line_id":"line-2","equipment_id":"equipment-3"}' \
  -d --restart=always kerberos/agent:latest

In docker compose or an .env file:

services:
  agent:
    image: kerberos/agent:latest
    environment:
      AGENT_CLOUD: kstorage
      AGENT_KERBEROSVAULT_CUSTOM_HEADERS: '{"site_id":"site-1","line_id":"line-2","equipment_id":"equipment-3"}'

AGENT_KERBEROSVAULT_CUSTOM_HEADERS={"site_id":"site-1","line_id":"line-2","equipment_id":"equipment-3"}

In Kubernetes, quote the value so YAML keeps it as a string:

env:
  - name: AGENT_KERBEROSVAULT_CUSTOM_HEADERS
    value: '{"site_id":"site-1","line_id":"line-2","equipment_id":"equipment-3"}'

Use AGENT_KERBEROSVAULT_SECONDARY_CUSTOM_HEADERS for the secondary Vault. In ConfigMap deployments you can set shared defaults with the GLOBAL_ prefix (for example GLOBAL_AGENT_KERBEROSVAULT_CUSTOM_HEADERS) and override them per agent with AGENT_KERBEROSVAULT_CUSTOM_HEADERS. You can also set the same JSON under Settings → Persistence → Custom upload headers in the Agent UI, which stores it as kstorage.custom_headers in config.json.

The rules for this value are:

• It must be a JSON object with string values. Numbers, null, arrays, and nested objects are rejected.
• It can contain up to 32 headers, with names up to 128 characters and values up to 4096 bytes.
• Header names must be valid HTTP tokens (letters, digits, and !#$%&'*+-.^_`|~). Keys are matched case-insensitively, so site_id and SITE_ID cannot both be used.
• Reserved names are rejected: anything starting with X-Kerberos-, Authorization, Cookie, Host, Content-Type, Content-Length, Trace-Id, tus protocol headers (Tus-Resumable, Upload-*), and hop-by-hop headers.
• Values cannot contain line breaks, tabs, or other control characters.

If the value is invalid, the Agent logs an error and does not upload to that Vault until the configuration is fixed. The recording stays queued, so it will upload once the value is corrected. Header names reach Vault unchanged, but proxies may normalise their casing. If Vault redirects an upload to another host, the Agent removes the custom headers and Vault credentials before following the redirect.

Encryption

You can encrypt your recordings and outgoing MQTT messages with your own AES and RSA keys by enabling the encryption settings. Once enabled, all your recordings will be encrypted using AES-256-CBC and your symmetric key. You can use the default openssl toolchain to decrypt the recordings with your AES key, as following:

openssl aes-256-cbc -d -md md5 -in encrypted.mp4 -out decrypted.mp4 -k your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8

Or you can decrypt a folder of recordings, using the Kerberos Agent binary as following:

go run main.go -action decrypt ./data/recordings your-key-96ab185xxxxxxxcxxxxxxxx6a59c62e8

Or for a single file:

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

H264 vs H265

If we talk about video encoders and decoders (codecs) there are 2 major video codecs on the market: H264 and H265. Taking into account your use case, you might use one over the other. We will provide an (not complete) overview of the advantages and disadvantages of each codec in the field of video surveillance and video analytics. If you would like to know more, you should look for additional resources on the internet (or if you like to read physical items, books still exists nowadays).

• H264 (also known as AVC or MPEG-4 Part 10)

  • Is the most common one and most widely supported for IP cameras.
  • Supported in the majority of browsers, operating system, and third-party applications.
  • Can be embedded in commercial and 3rd party applications.
  • Different levels of compression (high, medium, low, ..)
  • Better quality / compression ratio, shows less artifacts at medium compression ratios.
  • Does support technologies such as WebRTC

• H265 (also known as HEVC)

  • Is not supported on legacy cameras, though becoming rapidly available on "newer" IP cameras.
  • Might not always be supported due to licensing. For example not supported in browers on a Linux distro.
  • Requires licensing when embedding in a commercial product (be careful).
  • Higher levels of compression (50% more than H264).
  • H265 shows artifacts in motion based environments (which is less with H264).
  • Recording the same video (resolution, duration and FPS) in H264 and H265 will result in approx 50% the file size.
  • Not supported in technologies such as WebRTC

Conclusion: depending on the use case you might choose one over the other, and you can use both at the same time. For example you can use H264 (main stream) for livestreaming, and H265 (sub stream) for recording. If you wish to play recordings in a cross-platform and cross-browser environment, you might opt for H264 for better support.

Security vulnerability reporting

If you found a potential security vulnerability, please use the private channels described in SECURITY.md. Avoid opening public GitHub issues for sensitive findings.

Contribute with Codespaces

One of the major blockers for letting you contribute to an Open Source project is to set up your local development machine. Why? Because you might already have some tools and libraries installed that are used for other projects, and the libraries you would need for Kerberos Agent, for example FFmpeg, might require a different version. Welcome to dependency hell...

By leveraging codespaces, which the Kerberos Agent repo supports, you will be able to set up the required development environment in a few minutes. By opening the <> Code tab on the top of the page, you will be able to create a codespace, using the Kerberos Devcontainer base image. This image requires all the relevant dependencies: FFmpeg, OpenCV, Golang, Node, Yarn, etc.

After a few minutes, you will see a beautiful Visual Studio Code shown in your browser, and you are ready to code!

On opening of the GitHub Codespace, some dependencies will be installed. Once this is done go ahead to the ui/src/config.json file, and (un)comment following section. Make sure to replace the externalHost variable with the DNS name you will retrieve from the next step.

// Uncomment this when using codespaces or other special DNS names (which you can't control)
// replace this with the DNS name of the kerberos agent server (the codespace url)
const externalHost = 'cedricve-automatic-computing-machine-v647rxvj4whx9qp-80.preview.app.github.dev';

const dev = {
  ENV: 'dev',
  HOSTNAME: externalHost,
  //API_URL: `${protocol}//${hostname}:80/api`,
  //URL: `${protocol}//${hostname}:80`,
  //WS_URL: `${websocketprotocol}//${hostname}:80/ws`,

  // Uncomment, and comment the above lines, when using codespaces or other special DNS names (which you can't control)
  API_URL: `${protocol}//${externalHost}/api`,
  URL: `${protocol}//${externalHost}`,
  WS_URL: `${websocketprotocol}//${externalHost}/ws`,
};

Go and open two terminals: one for the ui project and one for the machinery project.

1. Terminal A:

   cd machinery/
   go run main.go -action run -port 80
   

2. Terminal B:

   cd ui/
   yarn start
   

Once executed, a popup will show up mentioning portforwarding. You should see two ports being opened, one for the ui 3000 and one for the machinery 80. Right-click on the port 80 and change visibility from private to public, this is required to avoid CORS errors.

As mentioned above, copy the hostname of the machinery DNS name, and paste it in the ui/src/config.json file. Once done, reload the ui page in your browser, and you should be able to access the login page with the default credentials root and root.

Develop and build

The Kerberos Agent is divided in two parts: a machinery and web part. Both parts live in this repository in their relative folders. For development or running the application on your local machine, you have to run both the machinery and the web as described below. When running in production everything is shipped as only one artifact, read more about this at Building for production.

UI

The web is a React project which is the main entry point for an end user to view recordings, a livestream, and modify the configuration of the machinery.

git clone https://github.com/kerberos-io/agent
cd ui
yarn start

This starts the web app on port 3000. In development, the UI connects to the Agent API on port 8082. Override that port when needed:

REACT_APP_AGENT_API_PORT=9090 yarn start

Once signed in you'll see the dashboard page. After successfull configuration of your agent, you'll should see a live view and possible events recorded to disk.

Machinery

The machinery is a Golang project which delivers two functions: it acts as the Kerberos Agent which is doing all the heavy lifting with camera processing and other kinds of logic and on the other hand it acts as a webserver (Rest API) that allows communication from the web (React) or any other custom application. The API is documented using swagger.

You can simply run the machinery using following commands.

git clone https://github.com/kerberos-io/agent
cd machinery
go run main.go -action run -port 8082

This will launch the Kerberos Agent and run a webserver on port 8082, matching the UI development default. You can change the port together with REACT_APP_AGENT_API_PORT. We strongly support the usage of Goland or Visual Studio Code, as it comes with all the debugging and linting features built in.

Building from source

Running Kerberos Agent in production only requires a single binary to run. Nevertheless, we have two parts: the machinery and the web, we merge them during build time. So this is what happens.

UI

To build the Kerberos Agent web app, you simply have to run the build command of yarn. This will create a build directory inside the web directory, which contains a minified version of the React application. Other than that, we also move this build directory to the machinery directory.

cd ui
yarn build

Machinery

Building the machinery is also super easy 🚀, by using go build you can create a single binary which ships it all; thank you Golang. After building you will end up with a binary called main, this is what contains everything you need to run Kerberos Agent.

Remember the build step of the web part, during build time we move the build directory to the machinery directory. Inside the machinery web server we reference the build directory. This makes it possible to just a have single web server that runs it all.

cd machinery
go build

Building for Docker

Inside the root of this agent repository, you will find a Dockerfile. This file contains the instructions for building and shipping a Kerberos Agent. It uses Debian Trixie to support the native dependencies used by the Agent, including Media over QUIC.

By running the docker build command, you will create the Kerberos Agent Docker image. After building you can simply run the image as a Docker container.

docker build -t kerberos/agent .

Media over QUIC

The standard AMD64 and ARM64 images include the optional MoQ publisher. Its Rust FFI archive requires CGO and glibc 2.38 or newer, which is why the standard image uses Debian Trixie. The publisher is disabled unless explicitly enabled at runtime:

docker run --rm -p 80:80 \
  -e AGENT_LIVE_MOQ_ENABLED=true \
  -e AGENT_LIVE_MOQ_URL=https://relay.uug.ai/anon \
  kerberos/agent

AGENT_LIVE_MOQ_BROADCAST_PREFIX defaults to devices. MoQ viewers subscribe to a relay and never negotiate with the Agent, so every quality tier is published as its own broadcast and switching quality is simply a resubscribe:

Tier	Broadcast	Source
high	devices/<agent-key>/live.hang	highest-resolution camera stream
low	devices/<agent-key>/live-low.hang	sub stream (main stream when none is set)

Each tier uploads every frame while it has subscribers. While idle, it continues to upload fresh keyframes only. This keeps the relay's latest cached GOP current, so a new viewer does not initially render the final frame from the previous viewer session, while avoiding the bandwidth cost of continuously sending every delta frame. AGENT_LIVE_MOQ_QUALITY accepts high or low to pin the Agent to a single tier; viewers requesting the other tier then find no broadcast. Any other value (including the default) publishes both. The initial implementation publishes H.264 video only.

Two bounded duration settings tune recovery for unusual network conditions:

Variable	Default	Allowed range
AGENT_LIVE_MOQ_MAX_PACKET_AGE	1.5s	250ms to 30s
AGENT_LIVE_MOQ_WRITE_TIMEOUT	5s	1s to 1m

Values use Go duration syntax and are clamped to the documented range. The dashboard API's recovery object reports per-tier reconnects, last successful frame/write timing, native write timeouts, watchdog restarts/cooldown, dropped run-channel events, and run-worker shutdown timeouts.

The /anon relay route is intended for interoperability testing. Production deployments must set AGENT_LIVE_MOQ_URL to a short-lived, device-scoped publisher URL issued by Hub API.

To verify the native SDK in a development container, rebuild the Agent or shared monorepo devcontainer so it uses the Trixie base, then run the VS Code task agent: moq verify. The same check is available from a terminal:

cd machinery
bash ./verify-moq-devcontainer.sh

The check requires glibc 2.38 or newer, runs the tagged package and in-process native QUIC lifecycle tests, links the complete Agent with -tags moq, and executes the resulting binary's version command. Both devcontainers also run this check during their post-create setup.

What is new?

This repository contains the next generation of Kerberos.io, Kerberos Agent (v3), and is the successor of the machinery and web repositories. A switch in technologies and architecture has been made. This version is still under active development and can be followed on the develop branch and project overview.

Read more about this at the FAQ below.

Contributors

This project exists thanks to all the people who contribute. Bravo!