rackhands documentation

rackhands is one static binary that is both a CLI and an MCP server for server BMCs. It speaks Redfish to Dell iDRAC, HPE iLO, Lenovo XCC, Supermicro and any DMTF-conformant BMC, and falls back to IPMI 2.0. It reads freely. It changes nothing unless you enable that class of operation and confirm the single machine it touches.

Install

$ go install github.com/Blackman99/rackhands/cmd/rackhands@latest

You can also download a release archive for linux, darwin or windows (amd64 or arm64) from GitHub Releases. Releases ship with checksums.txt. There is no runtime dependency: no Python, no ipmitool. IPMI is spoken natively.

For a one-off without a config file:

$ export RACKHANDS_PASSWORD='…'
$ rackhands --host https://10.20.0.11 --user root health
$ rackhands --ipmi 192.168.88.40 --user ADMIN sensors 192.168.88.40   # IPMI-only box

targets.yaml

rackhands reads $RACKHANDS_CONFIG, or ~/.config/rackhands/targets.yaml, or --config FILE. Keys under defaults apply to every target unless that target sets them itself.

defaults:
  username: rackhands-ro
  password_env: BMC_PASSWORD
targets:
  - name: db-01
    redfish: https://10.20.0.11     # https:// assumed if no scheme
    ipmi: 10.20.0.11                # optional; :623 assumed
    tags: [prod, db]
    allow: [power]                  # the per-target key for dangerous classes
  - name: lab-x10
    ipmi: 192.168.88.40             # IPMI only
    password_file: ~/.config/rackhands/lab.pass
audit_log: ~/.local/state/rackhands/audit.jsonl

Read commands

A TARGET is a name, all (the default), or tag:NAME. Reads run against up to 8 BMCs at a time.

Dangerous operations

Each one prints a plan first: what will be sent, to which URL, with which body, and the current state. Then it asks you to type the target name. In scripts, pass --yes NAME (it must be the exact name of the target). --dry-run prints the plan and stops.

$ rackhands --allow power power db-01 force-off
PLAN  power force-off db-01 (Dell PowerEdge R750, ResetType=ForceOff, currently On)
      POST /redfish/v1/Systems/System.Embedded.1/Actions/ComputerSystem.Reset {"ResetType":"ForceOff"}
      via redfish
Type the target name (db-01) to confirm: db-01
DONE  db-01: accepted (HTTP 204)

The safety model

1. Off by default. Without --allow (or RACKHANDS_ALLOW), every dangerous command is refused with exit 3, and the MCP server does not list the tools at all.
2. Two keys. The runtime --allow CLASS and the target's allow: list must both name the class. A mistyped target name or a box that nobody opened is refused. Ad-hoc --host targets have no config file, so for them only the runtime key applies.
3. One machine. all, tag: and multiple names are refused for dangerous classes.
4. Confirmation. On the CLI you type the name, or pass --yes NAME. With no terminal and no --yes, rackhands refuses. Over MCP the first call returns the plan and a token. The token is HMAC-signed, valid for 2 minutes and usable once. It is bound to the target, class, action, arguments and the protocol that will carry the request.
5. Audit. Every refusal, plan, rejected token, execution and failure is appended to a JSONL file.

Defence in depth: a read-only BMC account

Give agents a read-only BMC account, and keep a separate, privileged config for humans. The gate above is enforced by rackhands. The strongest guarantee is enforced by the BMC: an account with the Redfish ReadOnly role (on iLO, an account without the Virtual Power and Reset, iLO Config, Virtual Media and Host BIOS privileges) or the IPMI User privilege cannot power anything off, whatever program holds the password. Every read command works with such an account.

rackhands inventory and the MCP get_inventory tool report the effective privilege of the account each target logs in with, under account: role, can_control, privileges and where it came from. Over Redfish rackhands finds its own user in AccountService/Accounts and reads RoleId and the role's privileges, or the iLO Oem.Hpe.Privileges flags. Over IPMI it uses Get Session Info and Get User Access, and a read-only IPMI account that is refused an Administrator session gets a User session instead. When a target has no dangerous allow: classes but its account could power it off, rackhands adds a warning (and prints WARN on stderr). This is detection only: rackhands never changes BMC accounts. When the BMC hides AccountService from the account, the role is Unknown.

$ rackhands --json inventory x11 | jq '.[0].data.account'
{"user": "ADMIN", "role": "Administrator", "can_control": true,
 "warning": "logs in as Administrator, which can power off or reconfigure this machine, but no dangerous class is allowed for it; use a read-only BMC account (Redfish ReadOnly role, IPMI User privilege)", …}

MCP server

{"mcpServers": {"rackhands": {
  "command": "rackhands",
  "args": ["mcp"],
  "env": {"BMC_PASSWORD": "…"}
}}}

Point the MCP server at a config whose BMC accounts are read-only (Redfish ReadOnly, IPMI User); get_inventory shows each account's effective role and warns about over-privileged ones (details).

Add "--allow", "power" to args to expose power_action, and nothing else. Use --config to point at a specific targets file.

Read tools are annotated readOnlyHint, and dangerous ones destructiveHint. A dangerous tool called without a token returns {"status": "confirmation_required", "plan": …, "confirm_token": …, "next": …}. Called again with the token, it returns {"status": "done", "result": …}. The server instructions tell the agent to show the plan and wait for a human yes. The token makes sure that what runs is exactly what was shown.

Vendor notes

Units are normalised (Cel to C, Percent to %), severities map to OK / Warning / Critical, and event times are UTC.

IPMI and fallback

With both redfish and ipmi set, rackhands tries Redfish first. It falls back to IPMI when the service is unreachable, does not support the operation, or answers 404, 501 or 503. It does not fall back on 401 or 403: a wrong password should be fixed, not hidden by trying another protocol. Results say via: "ipmi (fallback)", and JSON adds fallback_reason.

Over IPMI you get FRU inventory, threshold sensors with health from the threshold status, SEL, chassis status faults, power state and control, boot device and BMC cold reset. Firmware update and virtual media are Redfish-only. Over IPMI, firmware shows only the BMC revision, and boot order is not available. SDR and SEL walks retry automatically when another client cancels the reservation.

Output and exit codes

--json prints a list of {"target", "via", "fallback_reason"?, "data"?, "error"?} for fleet reads, and {"target", "via", "data"} for single-target reads. One unreachable BMC does not hide the others: its entry carries an error.

Audit log

The audit log is at ~/.local/state/rackhands/audit.jsonl by default. Override it with --audit-log FILE, RACKHANDS_AUDIT_LOG or audit_log:, or turn it off with --audit-log off. One JSON object per line:

{"time":"2026-10-12T08:14:03Z","actor":"mcp","phase":"planned","op":{"target":"db-01","class":"power","action":"force-off","args":{"via":"redfish"}},"summary":"power force-off db-01 …","method":"POST","path":"/redfish/v1/Systems/…/ComputerSystem.Reset","body":{"ResetType":"ForceOff"}}
{"time":"2026-10-12T08:14:31Z","actor":"mcp","phase":"executed","op":{…},"result":"accepted (HTTP 204)"}

Phases: refused, planned, token-rejected, executed, failed.

How it is tested

Unit tests replay vendor mockups (Dell R750, HPE DL380 Gen10, Lenovo SR650 V2, Supermicro X11) through an in-process Redfish server that records every write. CI then runs the real binary (test/integration.sh) against the DMTF Redfish-Mockup-Server, which serves DMTF's public-rackmount1 mockup and the four vendor mockups, and against OpenIPMI ipmi_sim over a real RMCP+ session. The MCP server is exercised over stdio through the full plan, token and done sequence.

FAQ

Why not just give the agent ipmitool or curl? Because nothing stands between "check the fans" and chassis power off. rackhands gives the agent the reads and nothing else unless you open a class, and even then a human approves each request.

Can I use it without an agent? Yes. The CLI is a complete tool on its own.

Does it change BIOS settings, RAID, or BMC users? No. See GOAL.md.

My vendor behaves differently. Open an issue with an anonymised capture of the relevant Redfish resources. New quirks are added as mockups first.