Harbor interop

Load Harbor tasks into the HUD runtime or export HUD tasks to Harbor folders, with the converter CLI and a field-by-field mapping between formats.

Everything that authors tasks - HUD’s own env.py, platform rows, Harbor task dirs - is a frontend that loads into the same primitives (Environment, Task, Taskset). Integrations are loaders, not converters: no codegen roundtrip to run foreign tasks. The Harbor integration lives in the SDK repo at integrations/harbor.py

• a public-surface loader that maps Harbor folders into SDK primitives. The included HarborRuntime is maintained with the SDK for local Docker execution; copy the loader into your project or run it from a checkout.

Prerequisites

• A Harbor task directory - each task has task.toml + instruction.md, and usually an environment/ (with a Dockerfile) and tests/.

Load Harbor tasks

load(path) parses a Harbor task dir (or a dataset of them) into a Taskset directly - one row per task dir (id = the dir name), sharing one declarative Environment per distinct environment/ build context:

from integrations.harbor import detect, load

assert detect("./harbor_tasks")
taskset = load("./harbor_tasks")

for task in taskset:
    print(task.env, task.id)

Like every task row, the result carries no placement. Run it by supplying one. For local Docker-backed Harbor execution, use HarborRuntime; it builds the task’s environment/ image, runs a fresh container, exposes the workspace through HUD’s normal shell capability, and grades by running tests/test.sh:

from integrations.harbor import HarborRuntime

job = await taskset.run(agent, runtime=HarborRuntime("./harbor_tasks"))

The eval CLI can run local Harbor task directories and datasets when you opt into the Harbor source format:

hud eval ./harbor_tasks claude --format harbor --task-ids cancel-async-tasks --max-steps 30

Export HUD tasks to Harbor

export(source, out_dir) goes the other way: it turns a HUD task source (a .py file/dir exposing Tasks, or a .json/.jsonl taskset next to its env.py) into self-contained Harbor task folders:

from integrations.harbor import export

created = await export("tasks.py", "harbor_tasks")

harbor_tasks/
└── <slug>/
    ├── task.toml             # Harbor-native config (+ hud_task/hud_args metadata)
    ├── instruction.md        # the materialized prompt + answer-file convention
    ├── environment/          # the env build context + baked HUD entrypoint
    │   ├── Dockerfile
    │   └── hud_entrypoint.sh
    └── tests/test.sh         # grades over the in-container control channel

How the lifecycle maps:

HUD	Harbor
serving (python -m hud.environment.server) + task start	the baked image ENTRYPOINT serves the control channel and parks the run
the agent works, writes answer.txt	the agent works in the container
task evaluate (grade)	tests/test.sh grades the parked run, writes reward.txt

Only environments whose capabilities are ssh/mcp are exportable (Harbor is shell-centric; rfb/cdp don’t map). The exported task grades over the HUD control channel, so it needs Harbor’s default same-container verifier - don’t set [verifier.environment] in task.toml.

Review, then rely

The mapping is mechanical, so review the result - confirm the prompt reads naturally, the grader scores what the prompt asks for, and there’s no leftover answer leakage (see Designing tasks for signal).

See also

Package & deploy

Tasks & placement

Designing tasks for signal

CLI reference