phirumseng/knetrahub-agent repository overview

⁠KNetraHub Agent

Lightweight per-node metrics collector for KNetraHub⁠.

The KNetraHub app only has direct Docker API access to the node it runs on. This agent closes that gap: deployed as a global swarm service (one task per node, managers included), it reports each node's live CPU, memory, disk, and per-container usage back to the app over HTTP — so the dashboard sees the whole cluster without exposing the Docker API over TCP.

📖 Documentation: https://sengphirum.github.io/KNetraHub/documentation⁠

⁠Highlights

• Tiny footprint — runs comfortably within 0.1 CPU / 64 MB per node.
• Distroless image — no shell, no package manager, minimal attack surface.
• Read-only — mounts the Docker socket :ro and only ever POSTs reports outward.
• Token-authenticated — every report is validated by the app against a shared secret.
• Store-agnostic — the app fans each report out to Redis (the live state every replica shares) and VictoriaMetrics (history); the agent itself needs no access to any store and no change when the app's storage changes.
• Multi-mode — the same image also ships the Monitoring module's server, network, and asset collectors, selected per deployment with KNETRAHUB_AGENT_MODE.

⁠Supported tags

• latest — most recent release
• x.y.z (e.g. 0.1.11) — immutable release versions; keep the tag in sync with your phirumseng/knetrahub-app version

⁠Quick start

Add the agent to the same stack as the KNetraHub app (excerpt):

services:
  agent:
    image: phirumseng/knetrahub-agent:latest
    environment:
      KNETRAHUB_AGENT_URL: "http://knetrahub_app:3000/api/agent/report"
      # Must equal the app service's NUXT_AGENT_TOKEN
      KNETRAHUB_AGENT_TOKEN: "change-me-to-a-long-random-string"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    deploy:
      mode: global          # one task on every node
      resources:
        limits:
          cpus: "0.10"
          memory: 64M

For production, use a Docker secret instead of a plaintext token:

    secrets:
      - knetrahub_agent_token
    environment:
      KNETRAHUB_AGENT_TOKEN_FILE: "/run/secrets/knetrahub_agent_token"

(The image is distroless; _FILE resolution happens inside the process, so file-based secrets work without a shell entrypoint.)

⁠Configuration

⁠Collector modes

⁠License

Proprietary — © Seng Phirum. All rights reserved.