hud-python: RL environments and evals for AI agents, defined once
RL environments + evals for AI agents. Define once, train anything.
At a glance
- What is it?
- HUD is a Python SDK and CLI for writing RL environments that double as evals. It is protocol-first, so the same task definition runs against Claude, OpenAI, Gemini, or a harness you attach yourself.
- Who is it for?
- Adopt hud-python if you want one task definition to serve both grading and RL rollouts and you are willing to run a server-side platform for trace storage. Skip it if you need a fully offline eval loop or a Python 3.13 environment, since pyproject.toml pins requires-python to >=3.11, <3.13.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 18, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem hud-python solves: one definition, two jobs
Most agent work splits into two codebases. One grades a model on a fixed set of tasks. The other generates reward signal for training, usually with a different task format and a different runner. HUD's pitch is that these should be the same artifact. The README states the goal directly: define an environment, write tasks, and run them as evals and training across any model.
The intended user is an engineer who already has a benchmark or a task set and wants to turn it into training signal without rewriting it. The repository ships an environments/ directory and cookbooks/ alongside the SDK, so the project expects you to start from working examples rather than a blank file. The topics list reinforcement-learning-environments and grpo, which tells you the training side is aimed at policy-gradient style RL rather than supervised fine-tuning.
The scope claim is broad: coding, browser, computer-use, and robotics. That breadth comes from the capability model described below, not from four separate products. A robotics task and a shell task share the same task and grading code, and differ only in which capability the harness opens.
The protocol: manifest, tasks.start, tasks.grade
HUD is protocol-first. An agent and an environment exchange three things. The environment serves a manifest describing its capabilities and tasks. The agent calls tasks.start and receives a prompt. When it is done, it calls tasks.grade and receives a reward. Everything in between is the agent driving capabilities directly.
That middle phase is the design decision worth noting. HUD does not sit in the loop proxying every tool call. The environment holds and serves capabilities, and the harness attaches its own tools to them. The README lists five protocols: ssh for shell and files in a sandboxed workspace via env.workspace(root), mcp for Model Context Protocol tools, cdp for browser control over the Chrome DevTools Protocol, rfb for full computer-use over VNC, and robot, marked beta, for a schema-driven observation and action loop over WebSocket.
The consequence is that an environment outlives any single harness. A new model or a new agent framework keeps running against the same environments and tasksets. The cost is that the SDK owns only a thin envelope, so anything the protocol does not cover (retry policy, tool-call formatting, context management) is the harness author's problem. If you want a framework that also manages the agent loop, this is not that.
Install hud and run your first graded task
The README recommends installing the CLI as a uv tool, pinned to Python 3.12. A library install is also documented for code that imports hud directly.
uv tool install hud --python 3.12
# or as a library
pip install hudThe package was previously published as hud-python. Import and CLI names did not change, but the README warns that the two distributions can clobber each other's files, so migrate by uninstalling both before reinstalling.
pip uninstall -y hud-python hud && pip install hudGet an API key from hud.ai/project/api-keys and set it either through the CLI or as an environment variable.
hud set HUD_API_KEY=your-key-here
# or: export HUD_API_KEY=your-key-hereScaffold an environment. The README offers three templates: the default coding environment, cua for a desktop environment, and blank for a custom one.
hud init my-env
hud init my-desktop-env --template cua
hud init my-custom-env --template blankA template is an async generator registered with @env.template(). You yield a prompt, receive the agent's answer, and yield a reward. Calling the template mints a Task, so one function covers a whole dataset of variants.
from hud import Environment
env = Environment(name="letter-count")
@env.template()
async def count_letter(word: str = "strawberry", letter: str = "r"):
answer = yield f"How many '{letter}'s are in '{word}'? Reply with just the number."
yield 1.0 if answer and str(word.count(letter)) in answer else 0.0
tasks = [count_letter(word=w) for w in ("strawberry", "raspberry", "blueberry")]Run it against a model with the CLI, grouping three rollouts per task. With HUD_API_KEY set, the README says every rollout is recorded on hud.ai as a trace.
hud eval tasks.py claude --group 3To run on HUD rather than locally, deploy the environment and sync a taskset before evaluating remotely.
hud deploy
hud sync tasks my-taskset
hud eval my-taskset --remoteWhat the protocol-first design costs you
The trade-off is where the work lands. Because HUD exposes capabilities rather than a fixed agent, the SDK does not ship the agent loop for you. The README says a harness attaches to a capability and defines a tool spec, naming browser-use on cdp, a VLA policy on robot, or your own agent on ssh or mcp as examples. Native agents exist for Claude, OpenAI Responses, OpenAI-compatible endpoints, and Gemini through create_agent, but anything outside that set means writing the harness.
The second constraint is the runtime. pyproject.toml pins requires-python to >=3.11, <3.13, so a Python 3.13 environment will not install it. The dependency list is also not small: openai, anthropic, google-genai, asyncssh, asyncvnc, fastmcp, and pillow all come in with the base install, which is heavier than a pure eval library would be.
The third is observability. Trace recording on hud.ai is the documented path for reviewing rollouts, and the README does not describe a fully offline mode for that. If your evaluation data cannot leave your infrastructure, that is a real blocker rather than a configuration detail.
One more caveat sits in the README itself. The Harbor interop adapter, which converts existing Harbor task directories into HUD tasksets, is labelled experimental. Treat it as a migration aid, not a stable interface.
from hud.integrations import harbor
taskset = await harbor.adapt("./benchmark")hud-python compared with a plain eval harness
The closest alternative is a general-purpose eval framework such as Inspect, where you write a dataset, a solver, and a scorer, and the framework owns the agent loop and the logging. The difference is architectural rather than feature-level. Inspect-style frameworks put the harness in the middle and treat the model as something they drive. HUD puts the environment in the middle and treats the harness as something that attaches. That is why HUD can serve a VNC computer-use rollout and a one-shot letter-count question from the same task file, and why it does not give you a batteries-included agent loop.
If your goal is scoring models on a fixed suite and producing a report, a conventional eval framework will get you there with less protocol surface. If your goal is to reuse the same tasks for RL training and swap harnesses as models change, the capability boundary is what makes that reuse possible. The README also points at Harbor interop for teams that already have benchmark directories in that format, which is a migration path a generic eval framework would not offer.
Maintenance, packaging, and the MIT licence
The repository is not archived, and the last push was on 2026-09-14. Releases are frequent: v0.6.17 landed on 2026-09-14, v0.6.16 on 2026-09-10, and a dev build, v0.6.16.dev4, on 2026-09-02. The version is dynamic, read from hud/version.py by hatchling, so the number in pyproject.toml is not the source of truth.
Upgrade cost is mostly the dependency floor. Because the SDK pins openai, anthropic, and google-genai together, a major bump in any one of them lands on you through hud. The pillow floor carries a comment explaining that 11.2.x is what Isaac Sim's kit python pins, and that requiring 11.3 would force an upgrade that breaks the simulator. That is a deliberate constraint, and it tells you the robotics path is load-bearing for the dependency set.
The licence is MIT, declared in pyproject.toml and shipped as a LICENSE file. MIT is permissive, so it does not restrict commercial use or require you to open your environments. It also means no patent grant and no warranty, which is standard for this licence and worth knowing if you are building a product on top.
Editorial conclusion
Adopt hud-python if you want one task definition to serve both grading and RL rollouts and you are willing to run a server-side platform for trace storage. Skip it if you need a fully offline eval loop or a Python 3.13 environment, since pyproject.toml pins requires-python to >=3.11, <3.13. Before committing, install hud, run the letter-count template locally with hud eval, and confirm that the Harbor adapter under hud.integrations.harbor reads your existing benchmark directory, because the README labels that adapter experimental.
Frequently asked questions
What does HUD stand for in hud-python?
The README does not expand the acronym. It describes HUD as a platform for building RL environments for AI agents, and the package is published on PyPI as hud, previously hud-python.
What is HUD and how does it work?
HUD is a Python SDK and CLI for defining RL environments that also run as evals. An agent and an environment exchange a manifest of capabilities and tasks, tasks.start which returns the prompt, and tasks.grade which returns the reward. Between start and grade the agent drives capabilities such as ssh, mcp, cdp, rfb, or robot directly.
What is the difference between HUD and a UI?
HUD here is not a user-interface toolkit. It is a protocol and SDK for RL environments and evals for AI agents, installed with uv tool install hud and driven through the hud CLI or the Python API.
Does Python have a UI for hud-python?
The README does not document a graphical interface. Work is driven through the hud command line, the Python API, and the hud.ai platform, where rollouts are recorded as traces when HUD_API_KEY is set.
Community notes