my-env/
├── env.pythe environment: object, capabilities, and task definitions
├── tasks.pythe concrete tasks to run, filled in with real arguments
├── Dockerfile.hudhow the environment is packaged into an image on deploy
└── pyproject.tomlthe Python dependencies
## The `env.py` file
`env.py` is the only file that defines behavior. In this section we'll go through each part of a full example (see it in full below).
It's an environment that gives the agent a sandboxed shell and file system, asks it to count a letter in a sentence, and scores the answer.
1 · Imports and the environment object
`env = Environment(name="counter")` creates the environment - the central object everything else
attaches to. Capabilities, lifecycle hooks, and tasks all register against `env`; it holds nothing on
its own. The `name` identifies it - how a task finds its way back to this definition, and what it's
published under when you deploy.
env.py
```python theme={"dark"}
from pathlib import Path
from hud.environment import Environment
ROOT = Path("workspace")
env = Environment(name="counter")
```
3 · Lifecycle hooks
`@env.initialize` runs once before the env serves - the place to seed files or start services - and
`@env.shutdown` runs on teardown, after the run finishes, to release them. Both are optional; here
they're dummy hooks for demonstration, writing and removing a file.
env.py
```python theme={"dark"}
@env.initialize
async def _setup():
(ROOT / "instructions.txt").write_text("Count letters case-insensitively.\n")
@env.shutdown
async def _teardown():
(ROOT / "instructions.txt").unlink(missing_ok=True)
```
## Lifecycle hooks
When a task needs state - seeded files, a running service, a browser - you bring it up in
`@env.initialize` and release it in `@env.shutdown`. `@env.initialize` runs once before the env accepts
any connection, so by the time an agent connects, everything it needs is already in place. Because the
`env.workspace(...)` hook is registered first, the workspace directory already exists when your own
hook runs, so you can write straight into `ROOT`.
Hooks run per environment, not per task, so use them for state every task shares. The [environment
reference](/v6/reference/environment#methods) covers the full lifecycle.
4 · Tasks
`@env.template(id="count")` defines the task. The first `yield` sends the prompt and pauses; when the
agent's `answer` arrives the function resumes, and the second `yield` returns the reward - `1.0` if the
count matches, else `0.0`.
env.py
```python theme={"dark"}
@env.template(id="count")
async def count(sentence: str, letter: str):
answer = yield f"How many times does '{letter}' appear in '{sentence}'?"
yield 1.0 if str(sentence.lower().count(letter.lower())) in (answer or "") else 0.0
```
## Tasks
A **task** is HUD's unit of evaluation: a prompt the agent attempts and a reward that scores how it did.
You write one as an async generator with exactly two `yield`s:
1. **The first `yield` returns the prompt** and pauses the function while the agent works in the
environment, driving whatever capabilities it was given. Its answer comes back into `answer`.
2. **The second `yield` returns the score** - a reward from `0.0` to `1.0`. This is where grading goes:
compare `answer` inline, or call a [grader](#grading) to judge what the agent left behind.
`@env.template()` registers it as a **template**, not a single task: its parameters fill in per run, so
one definition describes a whole space of tasks. Calling it - `count(sentence="strawberry",
letter="r")` - mints one concrete, runnable [task](/v6/reference/tasks).
## Grading
The second yield is the reward, a number from `0.0` to `1.0`. Here it's plain Python: compare the
agent's answer to the count Python computes. You have three options as tasks grow:
| Approach | What it does |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Plain Python | Compute the answer inline, like above. Comparison helpers (`exact_match`, `numeric_match`, ...) live in `hud.graders`. |
| Async graders | `BashGrader` scores a shell command by exit code; `LLMJudgeGrader` scores against rubric criteria. This is how you grade the state the agent left behind - a test passing, a file written. |
| Composed graders | `combine` runs several at once and weights them into one reward, each subscore visible in the trace. |
An async grader is an `await`ed call whose result you yield - `BashGrader`, for instance, runs a command
in the workspace and scores by exit code:
```python theme={"dark"}
result = await BashGrader.grade(weight=1.0, command="pytest -q", cwd=str(ROOT))
yield result.value
```
The full set lives in the [graders](/v6/reference/graders) reference; see [designing
tasks](/v6/reference/advice) for what separates good rewards from hackable ones.
## Listing tasks in `tasks.py`
`env.py` defines the shape of a task. `tasks.py` lists the concrete ones to run by calling the template
with real arguments:
```python tasks.py theme={"dark"}
from env import count
tasks = [
count(sentence="strawberry", letter="r"),
count(sentence="banana", letter="a"),
]
```
Each call binds one runnable task. Build them in a loop to turn one definition into a whole dataset.
## Testing the environment locally
Run an agent against the tasks. `hud eval` spawns the environment locally, runs the agent, grades each
task, and prints the reward:
```bash theme={"dark"}
hud eval tasks.py claude
```
No Docker or separate server needed - the only thing you need is a provider key for the model
(`ANTHROPIC_API_KEY`, ...), or a `HUD_API_KEY` to route through the HUD gateway instead.