halkit 0.1.0

An open-source protocol for AI agents to control hardware.

Install

On macOS and Linux, run this command in a terminal.

curl -LsSf https://sohanbhat.me/OpenHAL/install.sh | sh

On Windows, run this command in PowerShell.

irm https://sohanbhat.me/OpenHAL/install.ps1 | iex

Then run the demo. The demo uses simulated devices, so nothing touches real hardware.

openhal demo

You'll see the agent raise the bed target from 60 °C to 70 °C, have a request for a nozzle temperature of 300 °C blocked at the nozzle limit of 260 °C and pause the print when the camera shows the print has come loose. The owner then approves the cancel, and the printer's state becomes cancelled.

OpenHAL runs on Python 3.12 or newer. The install guide covers uv, pipx, a clone, the background service and Raspberry Pi.

Why OpenHAL

Agents usually reach each printer or lab instrument through a script or MCP server made for that one device, with the limits in that server's code. OpenHAL is a universal driver specification instead. Agents discover, integrate and control lab and manufacturing equipment through one standard set of commands such as read and write, and every command is checked against the device's limits.

How it works

• A .hal.yaml device file lists a device's channels and actions, with units and limits.
• The safety kernel checks range, rate, interlocks and confirmation before a driver acts. A command outside the limits is blocked with an error such as LIMIT_EXCEEDED.
• One driver covers a device family, such as SCPI for bench instruments.
• Agents connect over MCP, the CLI or the Python client, and the protocol is JSON-RPC 2.0 over WebSocket and stdio.

Safety model

• Every channel and action has a risk level of low, medium or high. A device file's hazard sets the minimum level for every channel and action on the device.
• High risk channels and actions stay read-only until a person confirms the limits. An agent's proposal never counts as a confirmation.
• Low and medium channels and actions take commands within the device's own range. Only a person lowers a level, with openhal risk set.
• Each hardware change needs a single-use grant for that exact command.
• A stale or missing reading blocks the command.
• One stop puts every device in a safe state until a person lifts the stop.
• Every decision goes into a hash-chained audit log.

docs/SAFETY.md has the details.

Supported devices

OpenHAL has 36 drivers. Every driver passes the conformance suite on a simulator, and none is verified on real hardware yet. No driver covers clinical or patient-connected medical devices. To test a device you own, follow the hardware test plans. The device library lists the bundled device files.

Connect Claude or another MCP client

openhal init sets up the hub, makes a token and offers to add OpenHAL to Claude Desktop, Claude Code and Cursor. The setup for every client is printed either way.

openhal init
openhal start

Any other MCP client runs openhal mcp over stdio with a separate agent token, as the MCP guide shows. Connect Claude covers the manual setup.

Docs and specification

• Documentation
• Specification, also in spec/
• The demo step by step, with the simulated printer and camera
• Mapping to Anthropic's MHS. OpenHAL is not affiliated with Anthropic or the Model Hardware Standard.

Contributing

Drivers, device files, hardware test reports and docs fixes are welcome. See CONTRIBUTING.md, the driver guide and issues labeled good first issue. Report security or safety problems privately through SECURITY.md.

License

Apache-2.0, in LICENSE. Device files in library/ are CC0.