Skip to content
Hard Fault

Getting started

Hard Fault uses uv as its canonical environment and command surface. The team interpreter is pinned to Python 3.12 via .python-version.

1. Install uv

Section titled “1. Install uv”

uv is not assumed to exist on a raw machine — install it first.

Terminal window
# macOS
brew install uv


# Windows / Linux
pip install uv

2. Sync the environment

Section titled “2. Sync the environment”

From the repository root:

Terminal window
uv sync

This creates .venv/ and installs the locked dependency set. Run repo commands with uv run … so they always execute inside the pinned environment.

3. Run your first task

Section titled “3. Run your first task”

Point the agent at a board on your bench and give it a task:

Terminal window
uv run pyocd-debug run \
  --board-id nrf52833dk \
  --task "Verify this reference firmware is healthy and explain why."

pyocd-debug is the operator shell. For scripted or headless runs, use the turnkey CLI instead:

Terminal window
uv run pyocd-debug-brain run \
  --board-id nrf52833dk \
  --task "Diagnose this board interaction."

Configuration

Section titled “Configuration”

Runtime configuration is read from environment variables (and an optional, git-ignored .env). The most important one is the provider backend:

Terminal window
# openai-api | anthropic-api | codex-cli | claude-cli
PYOCD_TURNKEY_PROVIDER=codex-cli

See Providers & auth for the full list and how to authenticate each backend.

Next

Section titled “Next”

Before your first run against new hardware, walk through Bench bring-up to validate the host and the board.