keldron-agent

keldron-agent

Vendor-neutral GPU monitoring agent with risk intelligence.

One binary. Every GPU. Real risk scores — not just dashboards.

• Apple Silicon (M1–M5) — zero sudo, IOKit native
• NVIDIA consumer (RTX 3090/4090/5090) — nvidia-smi
• NVIDIA datacenter (H100/B200) — DCGM
• AMD (MI300X, RX 7900 XTX) — ROCm SMI
• Any Linux machine — hwmon/thermal sysfs

Device Health Dashboard:

Fleet View for Mobile:

The left image shows a computer at an idle state, and the right image shows a computer running an inference job with ollama

Quick Start (30 seconds)

Mac (Apple Silicon)

# Download the latest release
curl -sfL https://github.com/keldron-ai/keldron-agent/releases/latest/download/keldron-agent-darwin-arm64 -o keldron-agent
chmod +x keldron-agent
./keldron-agent --local
# → Dashboard at http://localhost:9200
# → Prometheus metrics at http://localhost:9100/metrics

Or build from source (needs Node.js / npm or pnpm for the full dashboard):

git clone https://github.com/keldron-ai/keldron-agent.git
cd keldron-agent
make build
./keldron-agent --local

For production use, prefer a GitHub release binary. make build from a clone produces the full dashboard.

Linux

# AMD64
curl -sfL https://github.com/keldron-ai/keldron-agent/releases/latest/download/keldron-agent-linux-amd64 -o keldron-agent
chmod +x keldron-agent
./keldron-agent --local

# Or ARM64 (e.g. Graviton)
curl -sfL https://github.com/keldron-ai/keldron-agent/releases/latest/download/keldron-agent-linux-arm64 -o keldron-agent
chmod +x keldron-agent
./keldron-agent --local

Or with Docker (build the image locally, or use the registry image when published):

make docker-build
make docker-run

Pre-built image (when available on GHCR):

docker run --rm \
  -p 9100:9100 -p 9200:9200 -p 8081:8081 \
  -e KELDRON_OUTPUT_PROMETHEUS_HOST=0.0.0.0 \
  -e KELDRON_API_HOST=0.0.0.0 \
  -e KELDRON_HEALTH_BIND=0.0.0.0:8081 \
  ghcr.io/keldron-ai/keldron-agent:latest

With a config file:

docker run --rm \
  -p 9100:9100 -p 9200:9200 -p 8081:8081 \
  -e KELDRON_OUTPUT_PROMETHEUS_HOST=0.0.0.0 \
  -e KELDRON_API_HOST=0.0.0.0 \
  -e KELDRON_HEALTH_BIND=0.0.0.0:8081 \
  -v $(pwd)/configs/keldron-agent.example.yaml:/etc/keldron/keldron-agent.yaml:ro \
  ghcr.io/keldron-ai/keldron-agent:latest

Verify

curl localhost:9100/metrics | grep keldron_gpu_temperature
# keldron_gpu_temperature_celsius{device_model="M4-Pro",device_vendor="apple",...} 52.3

Connect to Keldron Cloud

Stream telemetry to the cloud for 180-day history, fleet analytics, and device health tracking.

Use the keldron-agent binary from releases or make build.

Option 1: Interactive login

keldron-agent login

Option 2: Non-interactive login with an API key

export KELDRON_CLOUD_API_KEY=kldn_live_your_key_here
keldron-agent login

Or pipe the key: printf '%s' 'kldn_live_your_key_here' | keldron-agent login

Option 3: Run the agent with cloud streaming (no login step)

export KELDRON_CLOUD_API_KEY=kldn_live_your_key_here
keldron-agent

Check your connection:

keldron-agent whoami

Sign up for free at app.keldron.ai.

CLI reference

Run keldron-agent --help and keldron-agent <command> -h for flags.

What You Get

Example Prometheus output (real data from Apple Silicon):

keldron_gpu_temperature_celsius{adapter="apple_silicon",behavior_class="soc_integrated",device_id="hostname:0",device_model="M4-Pro",device_vendor="apple"} 52.3
keldron_risk_composite{behavior_class="soc_integrated",device_id="hostname:0"} 12.4
keldron_risk_severity{device_id="hostname:0"} 0
keldron_power_cost_monthly{device_id="hostname:0"} 4.32

Why Not Just nvidia-smi / powermetrics / lm-sensors?

Configuration

Create keldron-agent.yaml:

agent:
  device_name: "my-workstation"
  poll_interval: "2s"           # 2s–5m; use 10s–30s in production to reduce CPU/network load
  log_level: "info"
  electricity_rate: 0.12

adapters:
  apple_silicon:   # Mac: set enabled: true
    enabled: true
  nvidia_consumer: # Linux + NVIDIA: set enabled: true when nvidia-smi in PATH
    enabled: false
  dcgm:            # Datacenter NVIDIA (H100/B200)
    enabled: false
  rocm:            # AMD (MI300X, RX 7900)
    enabled: false

output:
  prometheus: true
  prometheus_port: 9100

Full config reference: configs/keldron-agent.example.yaml

Metrics Reference

Architecture

Adapters → Normalizer → Risk Engine → Prometheus /metrics
(IOKit, NVML,                          Stdout JSON
 ROCm, hwmon)                          Local dashboard :9200 (embedded UI)
                                       Keldron Cloud (optional)

The web UI is embedded at build time from frontend/ into internal/api/static/ (make build or the Dockerfile). The committed internal/api/static/index.html is only a fallback so bare go build succeeds without Node.js.

Security

The agent is read-only — it reads hardware sensors and computes scores. It does not execute arbitrary commands or alter system state beyond writing its own credential file (~/.keldron/credentials, created with 0600 permissions). Local HTTP servers (web UI on port 9200, Prometheus metrics on port 9100, health endpoint on port 8081) bind to 127.0.0.1 by default and are not exposed on public interfaces unless explicitly reconfigured.

• All HTTP servers bind to 127.0.0.1 (localhost) by default. Override via config for LAN access.
• Cloud telemetry is transmitted over HTTPS with TLS 1.2+.
• Credentials are stored with restricted file permissions (0600).
• The agent contains no tracking, analytics, or telemetry about your usage — only hardware sensor data.

To report a security issue, email ransom@keldron.ai.

Grafana Dashboard

A pre-built Grafana dashboard and Prometheus config live in examples/.

Quick start:

1. Start the agent: ./keldron-agent --local
2. Start Prometheus + Grafana: cd examples && docker compose -f docker-compose.grafana.yml up -d
3. Open Grafana at http://localhost:3000 (admin / password set via GF_ADMIN_PASSWORD env var)
4. Add a Prometheus data source: URL http://prometheus:9090
5. Import examples/grafana-dashboard.json (Dashboards → Import)

Keldron also exposes metrics at /metrics on the agent for any Grafana or Prometheus setup you already run.

Upgrade Path

Want fleet dashboards, 180-day history, and device health analytics?

→ Sign up free at app.keldron.ai → Learn more at keldron.ai

Contributing

PRs welcome. See our contributing guide.

License

Apache 2.0 — see LICENSE.