For builders
The card format
Each device has a card: one TOML file per model, at catalog/devices/<vendor>/<model>.toml. Cards are data only.
Every change takes the same road
A client never touches a device. It asks, and the daemon decides what happens from the device's card.
Is this battery worn enough to replace?
AskedA client proposes it
Card checkThe card lists it, and the value fits
Risk gate
Device
Worked examples are selected from the registry at build time. They illustrate labels, not live availability; consult the selected card's evidence and your local runtime.
What a card says
- [device]
- What the device is: vendor, name, kind and a one-line summary.
- [[match]]
- How software recognises it when it is attached: bus and identifiers.
- [keys]
- For keyboards: how key numbers, switch positions and lights line up.
- [[requires]]
- What has to be true before any of it works, such as a permission or a closed program.
- [[capability]]
- One thing the device can do: a word from the vocabulary, the adapter that reaches it, its risk, and how much has been checked.
- [[sources]]
- Where the information came from.
Risk
- read
- Nothing changes. The value is only read.
- reversible
- Changes take effect at once, can be undone at once, and cannot stop you using the machine.
- guarded
- Could get in the way of using the machine, so the change is reverted unless you confirm it within a few seconds.
- gated
- Cannot be undone, or needs a physical step. Nothing happens until you approve that exact action, and a step that needs your hands stays yours.
Checked
- tested
- Someone exercised this through the named adapter on that platform.
- observed
- Seen working or present on a real device, but not yet through the adapter.
- imported
- Taken from another project's data. Nobody here has tried it.
- unverified
- Documented somewhere. Nobody here has tried it.
Run it
It builds with Rust and needs no account. The first command works with no supported hardware attached.
Build it
cargo build --release
See what is attached, and which cards describe it
./target/release/hardpoint inventory
Try it with no hardware: it prints which keys would be lit
./target/release/hardpoint run --device dry --config examples/moonlander.toml
Let an agent connect, while `hardpoint run` is running
./target/release/hardpoint mcp
Report an agent session's state from any script or hook
./target/release/hardpoint emit --source my-tool --session 1 --state needs-you
An example
catalog/devices/zsa/moonlander-mk1.toml. The full rules are in docs/SPEC.md and catalog/schema/device.schema.json.
card = 1
[device]
id = "zsa/moonlander-mk1"
vendor = "ZSA"
name = "Moonlander Mark I"
identity = "model"
aliases = ["Moonlander MK1", "Moonlander"]
kind = "keyboard"
summary = "Split ergonomic keyboard with a light under every key and an open control protocol."
links = ["https://www.zsa.io/moonlander"]
[[match]]
bus = "usb"
vendor_id = 0x3297
product_id = 0x1969
# How key numbers, switch positions and lights line up. Each list has one
# entry per key, in key-number order.
[keys]
numbering = "Oryx key index: left half first, then right; within a half, row by row, then the thumb cluster"
matrix = [
[0, 0], [0, 1], [0, 2], [0, 3], [0, 4], [0, 5], [0, 6], [1, 0], [1, 1], [1, 2], [1, 3], [1, 4],
[1, 5], [1, 6], [2, 0], [2, 1], [2, 2], [2, 3], [2, 4], [2, 5], [2, 6], [3, 0], [3, 1], [3, 2],
[3, 3], [3, 4], [3, 5], [4, 0], [4, 1], [4, 2], [4, 3], [4, 4], [5, 3], [5, 0], [5, 1], [5, 2],
[6, 0], [6, 1], [6, 2], [6, 3], [6, 4], [6, 5], [6, 6], [7, 0], [7, 1], [7, 2], [7, 3], [7, 4],
[7, 5], [7, 6], [8, 0], [8, 1], [8, 2], [8, 3], [8, 4], [8, 5], [8, 6], [9, 1], [9, 2], [9, 3],
[9, 4], [9, 5], [9, 6], [10, 2], [10, 3], [10, 4], [10, 5], [10, 6], [11, 3], [11, 4], [11, 5], [11, 6],
]
leds = [
0, 5, 10, 15, 20, 25, 29, 1, 6, 11, 16, 21, 26, 30, 2, 7, 12, 17,
22, 27, 31, 3, 8, 13, 18, 23, 28, 4, 9, 14, 19, 24, 35, 32, 33, 34,
65, 61, 56, 51, 46, 41, 36, 66, 62, 57, 52, 47, 42, 37, 67, 63, 58, 53,
48, 43, 38, 64, 59, 54, 49, 44, 39, 60, 55, 50, 45, 40, 71, 70, 69, 68,
]
grid = [
[0, 0], [1, 0], [2, 0], [3, 0], [4, 0], [5, 0], [6, 0], [0, 1], [1, 1], [2, 1], [3, 1], [4, 1],
[5, 1], [6, 1], [0, 2], [1, 2], [2, 2], [3, 2], [4, 2], [5, 2], [6, 2], [0, 3], [1, 3], [2, 3],
[3, 3], [4, 3], [5, 3], [0, 4], [1, 4], [2, 4], [3, 4], [4, 4], [6, 5], [3, 5], [4, 5], [5, 5],
[8, 0], [9, 0], [10, 0], [11, 0], [12, 0], [13, 0], [14, 0], [8, 1], [9, 1], [10, 1], [11, 1], [12, 1],
[13, 1], [14, 1], [8, 2], [9, 2], [10, 2], [11, 2], [12, 2], [13, 2], [14, 2], [9, 3], [10, 3], [11, 3],
[12, 3], [13, 3], [14, 3], [10, 4], [11, 4], [12, 4], [13, 4], [14, 4], [8, 5], [9, 5], [10, 5], [11, 5],
]
[[requires]]
platform = "any"
what = "Sole use of the keyboard's control channel"
note = "ZSA's Keymapp holds the same channel, so it has to be closed. Checked on macOS."
[[capability]]
id = "identity.firmware"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "read"
note = "Reports the Oryx layout id and revision id that were flashed."
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-12 }]
[[capability]]
id = "keys.position_events"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "read"
privacy = "aggregate"
note = "Reported for every key, including keys with nothing assigned, so unused keys can be given meaning without reflashing."
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-12, note = "A press on a physical key was received and acted on." }]
[[capability]]
id = "keys.layer"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "read"
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-12, note = "The layer reported on connecting was received. A layer change was not exercised." }]
[[capability]]
id = "light.per_key"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "reversible"
note = "While the host controls lighting it must set every key; there is no overlay on the keyboard's own effects."
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-13, note = "Six keys confirmed by eye. The order of the other 66 follows QMK's published table." }]
[[capability]]
id = "light.global"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "reversible"
verification = [{ status = "tested", platform = "macos", os = "27.2", firmware = "Oryx protocol v4", date = 2026-11-12, note = "Taking and releasing control was confirmed by the keyboard's own reply." }]
[[capability]]
id = "light.status"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "reversible"
verification = [{ status = "unverified", platform = "macos", note = "In the published protocol. Not tried." }]
[[capability]]
id = "keys.layer_set"
adapter = "oryx-hid"
firmware = { family = "zsa-oryx" }
risk = "guarded"
verification = [{ status = "unverified", platform = "macos", note = "In the published protocol. Not tried." }]
[[capability]]
id = "firmware.flash"
adapter = "manual"
risk = "gated"
note = "You put the keyboard into update mode with its reset button, and ZSA's app writes the firmware. Hardpoint explains the steps."
verification = [{ status = "unverified", platform = "macos", note = "Taken from ZSA's documentation. Not tried." }]
[[sources]]
title = "ZSA: Moonlander product family"
url = "https://www.zsa.io/moonlander"
[[sources]]
title = "Oryx raw-HID protocol (zsa/qmk_modules)"
url = "https://github.com/zsa/qmk_modules/blob/main/oryx/oryx.h"
[[sources]]
title = "QMK keyboard definition, including LED order"
url = "https://github.com/qmk/qmk_firmware/blob/master/keyboards/zsa/moonlander/keyboard.json"