HUD is a platform for building RL environments for AI agents, across coding, browser, computer-use, and robotics. Define an environment, write tasks, and run them as evals and training across any model, at any scale.
To learn more, see the documentation and API reference.
# Install the CLI (recommended)
uv tool install hud-python --python 3.12
# …or as a library
pip install hud-pythonGet your API key at hud.ai/project/api-keys and set it:
hud set HUD_API_KEY=your-key-here
# or: export HUD_API_KEY=your-key-hereThen scaffold your first environment:
hud init my-env
HUD is protocol-first. An agent and an environment exchange just three things: a manifest (the environment's capabilities and tasks), tasks.start that returns the prompt, and tasks.grade that returns the reward. In between, the agent just works, driving the capabilities itself. HUD owns only that thin envelope, so any model or harness plugs into any environment.
sequenceDiagram
participant Agent
participant Env as Environment
participant Caps as Capabilities (ssh · mcp · cdp · rfb · robot)
Agent->>Env: manifest exchange
Env-->>Agent: capabilities + tasks
Agent->>Env: tasks.start
Env-->>Agent: prompt
rect rgb(238,238,238)
Note over Agent,Caps: the agent works, driving capabilities directly
Agent->>Caps: shell · browser · GUI · tools · robot
Caps-->>Agent: observations
end
Agent->>Env: tasks.grade
Env-->>Agent: reward
Because the protocol only exposes capabilities (never a fixed agent), an environment outlives any single harness: new harnesses and models keep running against the same environments, benchmarks, and tasks.
A built image is the end product for your tasks: one build packs every task from a single definition. The recommended path is hud deploy, which builds and registers your environment on HUD in one step; then sync a taskset and run remotely:
hud deploy
hud sync tasks my-taskset
hud eval my-taskset --remoteFor local iteration, the same protocol works against a container on your laptop:
hud build .
docker run -d --name run1 my-env
docker exec run1 hud task start fix_bug
docker exec run1 hud task grade fix_bug --answer "…"
docker rm -f run1A template is an async generator registered with @env.template(): yield a prompt, receive the agent's answer, yield a reward. Calling the template mints a runnable Task; one function spans a whole dataset of variants. The simplest needs no capabilities — just a prompt and a grader:
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 immediately against any model:
hud eval tasks.py claude --group 3Each graded evaluation is a trace (the SDK's live handle is a Run). With HUD_API_KEY set, every rollout is recorded on hud.ai. Tasks that need a shell, browser, GUI, or robot declare capabilities (below); everything else — variants, grading, batching — stays identical.
→ Quickstart · Tasks & tasksets
A capability is a connection the environment exposes; a harness attaches its own tools to it. The same environment serves a one-shot Q&A or a full computer-use rollout, depending on which capabilities the harness opens.
| Protocol | What it exposes |
|---|---|
ssh |
Shell + files in a sandboxed workspace (env.workspace(root)) |
mcp |
Tools over the Model Context Protocol |
cdp |
Browser control over the Chrome DevTools Protocol |
rfb |
Full computer-use over VNC: screen + keyboard/mouse |
robot (beta) |
Schema-driven robot observation/action loop over WebSocket |
Ships natively: Claude, OpenAI (Responses), OpenAI-compatible endpoints, and Gemini via create_agent("claude-sonnet-4-5") (or gpt-…, gemini-…). The harness wires capability-backed tools for the model you choose at run time.
Bring your own: a harness attaches to a capability and defines a tool spec — wrap browser-use on cdp, a VLA policy on robot, or your own agent on ssh / mcp. No protocol work required.
→ Capabilities · Models · Robots
From the platform UI you can run batches, compare models on the same taskset, and inspect every trace.
→ Deploy · Leaderboards
Every rollout returns a Run carrying a trace_id and a reward, so the tasks you evaluate are already training data. Run a group per task and turn the rewards into GRPO advantages with group_relative():
from hud.agents import create_agent
from hud.eval import Taskset, group_relative
agent = create_agent("claude-sonnet-4-5")
job = await Taskset(count_letter(word=w) for w in words).run(agent, group=16)
for runs in job.results.values():
advantages = group_relative([r.reward for r in runs], normalize_std=True)
... # feed (run.trace_id, adv) into your optimizerHUD is the environment-and-reward source for your own GRPO/PPO loop — the same environment trains any model, text or multimodal, unchanged.
→ Training · Designing tasks for signal
Building agents at scale? We work with teams on custom environments, benchmarks, and training.
📅 Book a call · 📧 founders@hud.ai
We welcome contributions! See CONTRIBUTING.md.
Key areas: Agents · Environments · Capabilities · Eval
@software{hud2025agentevalplatform,
author = {HUD and Jay Ram and Lorenss Martinsons and Parth Patel and Govind Pimpale and Dylan Bowman and Jaideep and Nguyen Nhat Minh},
title = {HUD: An Evaluation and RL Envrionments Platform for Agents},
date = {2025-04},
url = {https://github.com/hud-evals/hud-python},
langid = {en}
}MIT License · LICENSE