luminmonitor/lumin-agent repository overview

⁠lumin-agent

The agent for Lumin⁠, docker compose monitoring for small teams. One container next to your services collects:

• Host metrics — CPU, memory, disk, and network, read from /proc and /sys.
• Container metrics — per-container CPU, memory, and network, read through the Docker API.
• Container logs — stdout and stderr of any container you label, shipped line by line.
• Prometheus metrics — scraped from any container that exposes a /metrics endpoint.

The image is a single static Go binary on gcr.io/distroless/static-debian12. No shell, no package manager, runs as uid 65532.

⁠Supported tags

Platforms: linux/amd64, linux/arm64.

⁠Quick start

You need a lmn_priv_… API key from Settings → API keys in the Lumin app.

services:
  lumin-docker-proxy:
    image: tecnativa/docker-socket-proxy:v0.5.0
    restart: unless-stopped
    environment:
      CONTAINERS: 1        # /containers/{json, */stats, */logs}
      INFO: 1              # /info, /version
      PING: 1              # /_ping
      # Everything else stays default-deny.
      POST: 0
      EXEC: 0
      BUILD: 0
      IMAGES: 0
      VOLUMES: 0
      NETWORKS: 0
      SECRETS: 0
      EVENTS: 0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    read_only: true
    tmpfs: [/tmp, /run]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    healthcheck:
      test: ["CMD", "wget", "-q", "-T", "2", "-O", "/dev/null", "http://127.0.0.1:2375/_ping"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 5s

  lumin-agent:
    image: luminmonitor/lumin-agent:latest
    restart: unless-stopped
    environment:
      LUMIN_API_KEY: ${LUMIN_AGENT_API_KEY}
      LUMIN_ENDPOINT: https://api.getlumin.dev
      LUMIN_HOSTNAME: ${HOSTNAME:-prod-1}
      LUMIN_INTERVAL: 15s
      DOCKER_HOST: tcp://lumin-docker-proxy:2375
      HOST_PROC: /host/proc
      HOST_SYS: /host/sys
    volumes:
      - /proc:/host/proc:ro
      - /sys:/host/sys:ro
    read_only: true
    tmpfs: [/tmp]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
    mem_limit: 256m
    pids_limit: 256
    cpus: "0.5"
    healthcheck:
      test: ["CMD", "/usr/local/bin/lumin-agent", "--healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 30s
    depends_on:
      lumin-docker-proxy:
        condition: service_healthy

Then label the containers you want covered:

services:
  api:
    image: my-api:latest
    labels:
      lumin.logs: "true"
      lumin.service: "api"
      lumin.metrics: "true"
      lumin.metrics.port: "8080"
      lumin.metrics.framework: "gin"

⁠Environment variables

⁠The Docker socket proxy is not optional

The agent reaches the Docker API only through whatever DOCKER_HOST names, and the supported setup points it at the proxy sidecar, never at /var/run/docker.sock. The proxy holds the only bind-mount of the socket and forwards an allowlisted subset of the Docker API: list containers, read their stats, read their logs.

With DOCKER_HOST unset the agent does not reach Docker at all. It ships host metrics only, and skips container metrics, log tailing, and scraping. If you point DOCKER_HOST at a socket yourself, the agent starts and logs a warning.

A read-only bind-mount of the socket does not make the Docker API read-only. Any client that can reach the daemon can create a privileged container that mounts the host root, which is a one-call escape to root on the host. The proxy bounds the agent to the calls it actually makes.

⁠Docker CVEs in a scan of this image

A scan reports five advisories against github.com/docker/docker (GO-2026-4887⁠, GO-2026-4883⁠, GO-2026-5746⁠, GO-2026-5668⁠, GO-2026-5617⁠), each with Fixed in: N/A.

All five are bugs in the Docker daemon — plugin privilege handling, the AuthZ layer, and the docker cp archive path. This image contains a Docker client. It links only api/types, client, and pkg/stdcopy; no daemon package is in the binary. There is no version to upgrade to, because the fix ships in the daemon you already run. Any image vendoring the Docker client reports the same five.

Advisories that do have a fix get upgraded — the OpenTelemetry one (GO-2026-5158⁠) did, and no longer appears.

Full reasoning⁠.

⁠Documentation

• Install the agent⁠ — full reference, docker run equivalent, Swarm and Coolify notes.
• Agent security⁠ — the threat model behind the proxy.
• Quickstart⁠ — from signup to the first chart.

Licensed under Apache 2.0.