Automating a MegaRAC BMC KVM Console

When a bare-metal server loses SSH, everything that matters moves behind the BMC: BIOS screens, boot menus, kernel panics, and OS install wizards, all locked inside the board management controller's HTML5 KVM viewer. That viewer was built for a human with a browser, a mouse, and eyes. Automating it, so a script or an agent can drive the physical console without a person sitting in front of a KVM tab, is possible but full of small traps that cost hours the first time you meet them. This page covers how the automation works on the common AMI MegaRAC BMC and the specific gotchas that make it fragile. Pulsed Media's own autonomous AI sysadmin, Väinämöinen, drives server consoles this way when SSH is gone.

Why the console, not SSH

SSH and IPMI serial-over-LAN cover most remote work, but three situations force you onto the graphical KVM:

BIOS and UEFI setup: boot order, virtualisation toggles, CSM/Legacy-vs-UEFI, and firmware settings live on a graphical screen no shell can reach (unless serial console redirection is enabled in firmware first, which is often off by default).
Pre-boot and install: a stuck boot menu, a GRUB rescue prompt, an OS installer, or a POST error is visible only on the console.
A host with no working OS at all: when the operating system is gone, the KVM is the only way in short of a physical visit.

For a network switch or router CLI you would reach for a purpose-built tool such as Netmiko or an expect library. The BMC KVM is different: it is a pixel framebuffer, not a text stream, so you capture images and send keystrokes rather than reading and matching text.

The tool: mcxBMCView

mcxBMCView is an open-source (Apache-2.0) toolkit for exactly this, built for headless and automated management of AMI MegaRAC HTML5 consoles. It exposes a few stateless commands that authenticate, act, clean up, and exit:

getscreen: captures the server's physical display as a JPEG. The screenshot path is printed on stdout; exit code 0 is success, 1 is failure. Feed the image to OCR or a vision model to read what is on screen.
sendkeys: types keyboard input into the console: login sequences, BIOS navigation, boot-menu selections, anything a human would type.
power: an ipmitool chassis power wrapper with a confirm gate: read-only operations (status, sensors, SEL) run freely, while destructive ones (on, off, cycle, reset) require an explicit confirm flag, and every call is logged.

The screenshot-and-keystroke tools drive the HTML5 viewer through a headless browser; the power tool needs only ipmitool. The design is deterministic: each command does one thing and exits, so it composes into scripts.

The driving loop

Automating the console is a loop, not a one-shot: capture the screen, decide the single next keystroke, send it, capture again, and verify before moving on. The verify-every-step discipline matters more here than almost anywhere else, because a blind sequence of keystrokes that misfires on one screen turns one problem into two, and you cannot see that it went wrong until you capture again.

A minimal loop looks like: getscreen → read the image → decide one action → sendkeys → getscreen → confirm the expected change → repeat. Judge the result by the content of the new screenshot, not by whether the frame merely changed.

The gotchas

These are the failures that make console automation feel unreliable until you know them.

The video encoder starts cold

The most common false alarm: getscreen returns a zero-byte image or an HTTP error, and it looks as if the server is off or the display is dark. Usually it is neither. The BMC's video encoder has not engaged yet, so there is nothing to capture even though a physical monitor plugged into the same server would show the screen fine. Retry three to five times before concluding anything is wrong. A capture failure is not a dark host.

Force a redraw before you re-capture

After a keystroke, the console may not repaint on its own. Send a harmless redraw (an extra key, or a no-op) before the next getscreen, and again, judge by content rather than by whether the image visibly changed from the last one.

BIOS capture is cropped

Many BIOS screens render at a native 4:3 resolution that the HTML5 capture pipeline crops on a widescreen capture, losing a slice of the vertical content. Menu items at the top or bottom edge can be off-screen entirely. Do not assume the whole menu is visible: scroll or navigate rather than trusting that an item you cannot see is absent.

The BIOS entry key varies by board

There is no universal "enter setup" key. It differs by motherboard vendor and model (Del, F2, F11, and others), and the boot-menu key differs again. Detect POST and send the correct key for that specific board rather than assuming one key works everywhere. A persistent approach that watches for POST and repeatedly sends the entry key is more reliable than a single timed press.

Restart the video service at most once

If the encoder is genuinely wedged rather than merely cold, restarting the BMC's video service sometimes recovers it, but repeated restarts are a bad bet: on some controllers they leave the BMC in a worse state that needs a full reboot anyway. Prefer a single clean BMC reboot over bouncing the service several times, and treat that reboot as the reset of last resort.

Safety

The console is the physical machine. Power operations (off, cycle, reset) are destructive and should sit behind a confirm gate and an audit log, exactly as the tool's power command does. Reflashing firmware over the BMC is powerful and equally dangerous: gate it, log it, and never run it speculatively. Treat "type into the console" as you would treat root on the host, because functionally it is.