Blackbox

GitHub - maxjb-xyz/blackbox: The Forensic Journal for your Infrastructure. Written in Go for maximum impact with minimal footprint.GitHub

An intelligent self-hosted forensic event timeline for homelabs and home servers. Know what changed, when it changed, and why things broke.

Blackbox is a lightweight, self-hosted event correlation platform built for homelabbers who want to understand their infrastructure at a glance. It collects events from Docker, config file changes, selected systemd units, uptime monitors, and container update tools, correlates them into a single chronological timeline, and groups likely outages into incidents with scored cause candidates and optional local-AI analysis or AI-enhanced correlation.

When your homelab breaks, Blackbox tells you what happened. You don't need to lift a finger.

Blackbox Server

https://github.com/trentnbauer/HomelabPublic/blob/main/docker-compose/blackbox-server.yml

services:
  server:
    image: ghcr.io/maxjb-xyz/blackbox-server:0.4.1@sha256:efd7869243ea3e6a320c78d820294cf0b607716cf0c3a5e3d36e2e73bf6b5d9a
    restart: unless-stopped
    ports:
      - ${PORT:-8080}:8080
    volumes:
      - blackbox-data:/data
    labels:
      - autoheal=true
      - dfgeneric.enable=${CFTUNNEL:-true}
      - dfgeneric.0.hostname=${CFSUBDOMAIN}${CFDOMAIN}
      - dfgeneric.0.service=http://${HOSTNAME:-localhost}:${PORT:-8080}
      - dfgeneric.0.access.policy=${CFPOLICY:-default_tld}
      - dfgeneric.0.name=Blackbox
      - dfgeneric.0.zonename=${CFDOMAIN}
      - dfgeneric.0.path=${CFURLPATH:-}/
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
    environment:
      - TZ=${TZ:-Australia/Melbourne}
      - JWT_SECRET=${JWT_SECRET}
      - AGENT_TOKENS=${AGENT_TOKENS}
      - WEBHOOK_SECRET=${WEBHOOK_SECRET}

volumes:
  blackbox-data:

Beszel Agent

The agent is deployed as part of the 'All' stack