MINERAGENT

Overview

MINERAGENT is an autonomous AI agent that runs alongside your Braiins OS Bitcoin miner, watching its telemetry in real time and making optimization decisions on your behalf. It was built for the Antminer S19K Pro, but the architecture is hardware-agnostic enough to extend to the rest of the Braiins OS lineup.

Think of it as a foundation rather than a finished product. The core handles the hard parts — safe telemetry collection, deterministic safety rules, LLM-driven power tuning, and a strict validation firewall — so you can focus on what to build on top. Fleet orchestration, difficulty-based power scaling, custom alerting, profitability-aware pool switching: all of these slot in cleanly without touching the safety primitives underneath.

The agent runs on a two-tier decision loop. A deterministic rule engine evaluates every telemetry snapshot for immediate hazards — overheating chips, dead fans, dropped pools — and pauses mining the moment something looks wrong. Independently, an LLM (Anthropic Claude by default) reviews the broader picture every few minutes and proposes power adjustments, restarts, or no action at all. Every LLM decision passes through a hard safety validator before it ever reaches the miner.

Telemetry  →  Rule Engine        →  Braiins API
               └─→  LLM Engine  →  SafetyValidator  →  Braiins API

What's Inside

MINERAGENT speaks to the miner over three channels. The BOSminer TCP API on port 4028 streams the full telemetry picture — hashrate, per-board temperatures, fan RPM, power draw, pool status — once every polling cycle. Power targets and lifecycle commands go out over Braiins gRPC when available, with the REST API as an automatic fallback if grpcurl isn't on the path.

Five safety rules run on the deterministic side: an overheat guard that trips at 90°C, fan-failure detection while the miner is drawing power, a hashrate anomaly check against a 30-minute rolling average, pool-disconnection escalation after five minutes offline, and per-board hardware-error spike monitoring. These rules are not advisory — they short-circuit the loop and trigger actions directly.

The LLM side handles the softer optimization problem: how to fine-tune within the safe envelope. The engine sends a filtered telemetry snapshot to Anthropic Claude every few minutes (configurable) and gets back a JSON decision. Rate limits are handled gracefully — a 429 response blocks further calls for the duration the API requests, instead of hammering it with retries.

Every snapshot ends up in logs/miner_YYYY-MM-DD.jsonl, one JSON object per line. The same format the agent uses for its own memory is also what the included daily_summary.py reads to produce daily efficiency reports.

You can run the whole thing in simulation mode first — no commands ever reach the miner, but every other moving piece (telemetry parsing, rule evaluation, LLM calls, validator decisions) runs exactly as it would in production.

Getting Started

You'll need Python 3.10 or newer, a Braiins OS miner reachable on your local network, and an Anthropic API key (sign up at console.anthropic.com). grpcurl is optional — if it's missing, MINERAGENT falls back to the REST path for power control.

Clone the repository and set up a virtual environment:

git clone https://github.com/YOUR_USERNAME/MINERAGENT.git
cd MINERAGENT

python -m venv venv
source venv/bin/activate        # Linux / macOS
# venv\Scripts\activate         # Windows

pip install -r requirements.txt

Then copy the environment template and fill in your values:

cp .env.example .env

Open .env in your editor of choice and set MINER_IP, MINER_PASS, and CLAUDE_API_KEY at minimum. Everything else has sensible defaults you can tune later.

Configuration

All runtime behavior is driven by environment variables loaded from .env. The table below documents what each variable controls and what happens if you leave it at the default.

Variable	What it controls	Default
LLM_PROVIDER	Which provider the LLM engine talks to (claude or google)	claude
LLM_API_KEY	API key for the selected provider — env var name is CLAUDE_API_KEY for claude, GOOGLE_API_KEY for google	—
MINER_IP	Local network address of the Braiins OS miner	—
MINER_USER	Braiins OS web interface username	root
MINER_PASS	Braiins OS web interface password	—
SIMULATE_MODE	When True, all miner commands are logged but never sent	True
POLLING_INTERVAL	Seconds between telemetry collections	10
LLM_INTERVAL	Seconds between LLM optimization calls	300

Leave SIMULATE_MODE=True the first time you run the agent. You want to see the telemetry flow correctly, the rules fire on test conditions, and the LLM return sensible decisions before any of those decisions actually reach the miner. Once you're confident, flip it to False and pass --real to agent_loop.py to go live.

Usage

Start the Agent

# Simulation mode (default — no real commands sent)
python agent_loop.py

# Live mode — sends real commands to your miner
python agent_loop.py --real

# Custom miner IP and polling interval
python agent_loop.py --ip 87.124.55.91 --interval 15

Telemetry Only

# Single snapshot
python miner_telemetry.py

# Live dashboard (refresh every 10 seconds)
python miner_telemetry.py --watch 10

# Save snapshots to logs/
python miner_telemetry.py --save

# JSON output (for piping to other tools)
python miner_telemetry.py --json

Daily Summary Report

# Generate report for today
python daily_summary.py

# Generate report for a specific date
python daily_summary.py --date 2025-01-15

This reads the JSONL logs and outputs average hashrate, temperature, power, and efficiency stats. Also exports an Excel file to logs/.

Running as a Service

To run MINERAGENT as a background daemon on Ubuntu/Debian:

1. Edit mineragent.service and replace YOUR_SSH_USER with your Linux username
2. Copy and enable the service:

sudo cp mineragent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable mineragent
sudo systemctl start mineragent

3. Check status and logs:

sudo systemctl status mineragent
journalctl -u mineragent -f

Project Structure

MINERAGENT/
├── agent_loop.py           # Main entry point — runs the telemetry → rules → LLM loop
├── miner_telemetry.py      # Collects all miner data via BOSminer TCP API (port 4028)
├── rule_engine.py          # Tier-1: deterministic safety rules (overheat, fan, pool, HW errors)
├── llm_engine.py           # Tier-2: sends telemetry to LLM, parses JSON action response
├── safety_validator.py     # Hard firewall — validates every LLM action before execution
├── braiins_api.py          # REST API client for Braiins OS miner control
├── braiins_grpc.py         # gRPC client for power target control (via grpcurl)
├── orchestrator_state.py   # Shared state coordination for staged power ramp sequences
├── mineragent.service      # Systemd unit file template for Linux deployment
├── daily_summary.py        # Generates daily stats report from JSONL logs
├── requirements.txt        # Python dependencies
└── .env.example            # Environment variable template

Safety Architecture

MINERAGENT is not fully LLM-driven by design. LLMs can hallucinate, produce invalid outputs, or make decisions that ignore physical constraints. Trusting an AI model with direct hardware control would be reckless — a single bad command could overheat a chip, trip a breaker, or damage expensive equipment. That's why safety is enforced at three independent layers that operate regardless of what the LLM suggests:

Layer 1 — Rule Engine

Runs every polling cycle. Cannot be overridden by the LLM. Triggers immediate protective actions:

• Chip temperature ≥ 90°C → pause mining + alert
• Fan RPM = 0 while mining → pause mining + alert
• Hashrate drops > 20% from 30-min average → alert
• Pool offline > 5 minutes → switch to fallback pool
• HW error spike (> 50 in 5 minutes) → alert

Layer 2 — Safety Validator

Every LLM decision is validated before execution:

• Action must be in the whitelist (adjust_power_limit, pause, resume, none, restart)
• Power targets must be within 1000W–2500W
• Non-numeric or missing values are blocked
• Unknown actions are silently dropped

Layer 3 — Orchestrator Lock

During staged power ramp-up, the LLM engine is paused entirely. The orchestrator owns all power decisions until the ramp is complete, preventing the LLM from undoing the startup sequence.

Extending MINERAGENT

This project is a core you can build on. Some ideas:

• Fleet management — Control multiple miners from a single agent with per-device configs
• Difficulty-based scaling — Monitor Bitcoin network difficulty and adjust power targets accordingly
• Custom alert channels — Add Telegram, Discord, email, or webhook notifications
• Pool rotation strategies — Automatically switch pools based on profitability or latency
• Web dashboard — Build a real-time monitoring UI on top of the JSONL telemetry logs
• Hardware profiles — Add support for other Braiins OS miners beyond the S19K Pro

License

MIT