hud 0.6.19.dev2

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 environment reference.

Install

# Install the CLI (recommended)
uv tool install hud --python 3.12

# …or as a library
pip install hud

Previously published as hud-python. The import and CLI names are unchanged. If you have hud-python installed, migrate with pip uninstall -y hud-python hud && pip install hud (uninstalling both first avoids the two packages clobbering each other's files), and replace hud-python with hud in requirements files and CI configs.

Get 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-here

Then start from the coding environment, or choose another example environment:

hud init my-env
hud init my-desktop-env --template cua
hud init my-custom-env --template blank

The protocol

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)
    Note over Env,Caps: environment holds & serves these
    Agent->>Env: hello
    Env-->>Agent: manifest (capabilities)
    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.

Package & run anywhere

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 --remote

→ Run & deploy

Environments & templates

A 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 3

Each 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

Capabilities & harnesses

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.

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

Deploy on the platform

From the platform UI you can run batches, compare models on the same taskset, and inspect every trace.

Hosted Claude Code and Codex harnesses reach platform inference through an environment-owned, workspace-local endpoint. The endpoint is available only to bwrap workspaces with network isolation and is bound to the exact CLI process selected by the harness. Platform credentials stay in the environment-owned relay rather than the CLI environment, workspace manifest, or child processes. Codex therefore uses the environment sandbox instead of starting a nested Codex sandbox for process-bound hosted execution. The workspace probes its substrate and uses either seccomp notification or a ptrace-backed seccomp guard; it does not advertise process-bound connections when neither enforcement backend is available.

→ Run & deploy

Train on rewards

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 pass the graded runs to TrainingClient.step():

from hud import TrainingClient
from hud.agents import create_agent
from hud.eval import Job

agent = create_agent("arith-rl", completion_kwargs={"extra_body": {"return_token_ids": True}})
trainer = TrainingClient("arith-rl")
taskset, runtime = ...  # your Taskset and where rollouts run

session = await Job.start("arith-rl", group=8)
start = len(session.runs)
await taskset.run(agent, runtime=runtime, group=8, job=session)
await trainer.step(session.runs[start:], learning_rate=1e-5, group_size=8)

HUD 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

Links

• Documentation
• Quickstart
• CLI reference
• Environment templates
• Supported models
• Discord

Enterprise

Building agents at scale? We work with teams on custom environments, benchmarks, and training.

📅 Book a call · 📧 founders@hud.ai

Contributing

We welcome contributions! See CONTRIBUTING.md.

Key areas: Agents · Environments · Capabilities · Eval · Integrations

Citation

@software{hud2025agentevalplatform,
  author = {HUD and Jay Ram and Lorenss Martinsons and Parth Patel and Govind Pimpale and Dylan Bowman and Jaideep Chawla and Nguyen Nhat Minh},
  title  = {HUD: An Evaluation and RL Environments Platform for Agents},
  date   = {2025-04},
  url    = {https://github.com/hud-evals/hud-python},
  langid = {en}
}

MIT License · LICENSE