Install

OpenHAL needs Python 3.12 or newer. uv is the quickest way to get both.

From a clone

This is the README's route, which runs the CLI from the checkout and installs nothing else.

git clone https://github.com/sohan-bhat/OpenHAL
cd OpenHAL
uv run openhal demo

As a tool

uv tool install and pipx install put openhal and openhald on your PATH, each in its own environment. OpenHAL isn't on PyPI yet, so install OpenHAL from GitHub.

uv tool install --compile-bytecode git+https://github.com/sohan-bhat/OpenHAL
pipx install git+https://github.com/sohan-bhat/OpenHAL

You can also build a wheel in a clone and install that file.

uv build --wheel
uv tool install --compile-bytecode dist/openhal_hub-0.1.0.dev0-py3-none-any.whl
pipx install dist/openhal_hub-0.1.0.dev0-py3-none-any.whl

--compile-bytecode makes the first run about twice as fast.
Driver extras go in brackets, as in "openhal-hub[esphome,openhal-firmware] @ git+https://github.com/sohan-bhat/OpenHAL". Installing again with other extras replaces the ones you had, so list every extra you use. openhal doctor lists the drivers whose extras are missing.
A few dependencies have no Intel Mac wheels in their newest versions, and building those dependencies needs Rust, so on an Intel Mac add --no-build to uv, or --pip-args=--only-binary=:all: to pipx.

Set up

openhal init

In a terminal, openhal init prompts with a few short questions.

Look for devices, using only read-only identify commands.
Add each device discovery found as a read-only device file. OpenHAL firmware boards and ESPHome nodes describe themselves and library matches come from the device library, but no limit is confirmed for you.
Make a token for your AI client, read-only unless you pick another scope.
Save a client's config for you. The setup for Claude Desktop, Claude Code and Cursor is printed either way, and a file is backed up before it changes.
Run the hub in the background, starting at login.

openhal init --yes takes the safe defaults without prompting. With --yes, init looks for devices, adds every device read-only and makes a read token. A client config is saved only with --client NAME, and the service installs only with --service.

A device that discovery can't find, such as a board on a known port, goes in with --device.

openhal init --device openhal-firmware=/dev/ttyACM0

Background service

openhal service install

macOS gets a launchd agent in ~/Library/LaunchAgents, and Linux gets a systemd user unit in ~/.config/systemd/user. The hub starts now and at every login. status, restart and uninstall act as their names describe, print shows the file, and --dry-run prints every step and changes nothing.

On Linux the hub stops when you log out, unless lingering is on with sudo loginctl enable-linger $USER.

Raspberry Pi

git clone https://github.com/sohan-bhat/OpenHAL
OpenHAL/scripts/install-pi.sh

The script installs uv if it's missing, the system packages the Pi drivers need, and the hub with the rpi-gpio, rpi-camera, pi-i2c-spi, serial and openhal-firmware extras. The script then adds you to the gpio, i2c, spi and dialout groups, turns on lingering, installs the service and prints the next command. Add --dry-run to see every command first.

The camera needs Raspberry Pi OS with Python 3.12 or newer, so the hub can import the system's picamera2.

Quickstart runs the demo and a hub you control.
Connect Claude gives an AI client its own token.