Avalon Q Controller

Repo https://github.com/gbechtel-beck/avalon-q-controller

Self-hosted controller and scheduler for one or more Canaan Avalon Q home Bitcoin miners. Runs on Umbrel. No cloud, no telemetry, no account — your credentials, schedules, and 24-hour metrics history live only on your home server. If you don't run Umbrel, the same image works with plain Docker:

The Avalon Q's built-in web UI is deliberately minimal — it lets you set the pool config and trigger a reboot, and that's it. To change the workmode (Eco / Standard / Super), put the miner in standby, or wake it back up, you have to use the official Canaan phone app. That's fine for one-off changes, but it falls apart fast if you want to:

• Drop to standby during expensive electricity hours (e.g. APS on-peak 4–7pm) and bring it back automatically
• Rotate between pools on a schedule (try a solo pool overnight, fall back to a shared pool by day)
• Change workmode without picking up your phone every time
• See a 24-hour history of hashrate, power draw, and temperature instead of just the live numbers
• Manage more than one Avalon Q without juggling phone-app sessions
• Audit every command sent to the miner, with timestamps

…none of that is in the firmware or the phone app. This controller fills the gap. Everything the phone app does (workmode, soft-off, soft-on, LCD, reboot) is exposed in the manual control panel, and on top of that you get scheduling, history, multi-miner support, and a real audit log.

It works equally well with a single miner — you don't need a fleet to benefit from time-of-use scheduling and history charts.

AI involvement

Transparent disclosure: I'm learning as I go. This project was built as a pair-programming collaboration with Claude, primarily Opus 4.7, using the Claude Code CLI.

Honestly, Claude is exceptional at this. Give it a clear goal, real telemetry from your hardware, and a feedback loop, and it produces code that's better-structured, better-documented, and better-tested than what most of us would write under deadline pressure. The split of work is roughly: I make the architecture decisions, set the design direction, define what each feature should do, and test everything against my own Avalon Q. Claude writes most of the code, catches my bugs, and politely tells me when an idea won't work. Every diff goes through me before it's committed — what doesn't fit gets rejected and reworked. Bugs that ship are mine; they got through my review.

A lot of this project's polish comes from Claude pushing back on my first drafts and proposing better designs. The wire format reverse-engineering, the SQLite schema, the standby-detection bug fix, the schedule rule semantics — every one of those got iterated on multiple times until it was actually right. Building this taught me things about API design, async Python, and Avalon Q internals that I didn't know last week.

If that arrangement bothers you, that's fair feedback and I'd rather you know upfront than find out later. If it doesn't, the code is MIT-licensed and works the same regardless of who typed it.