HUD Documentation - Evaluations and RL Environments.

A Harbor import copies a zip of Harbor task folders and job folders into a taskset. Each task folder becomes a task of the taskset, and each job becomes an evaluation job whose traces replay the trials Harbor recorded, with their rewards. The import is the HUD counterpart of harbor publish for tasks and harbor upload for jobs. Imported tasks are for browsing and comparing runs; HUD cannot run them. To run Harbor tasks on HUD, adapt them with the SDK and deploy them.

Prepare the zip

One zip can hold tasks, jobs, or both, at any depth:

my-benchmark.zip
├── tasks/
│   ├── greet/                  # a task folder: holds task.toml
│   │   ├── task.toml
│   │   ├── instruction.md
│   │   ├── environment/Dockerfile
│   │   └── tests/test.sh
│   └── greet-loud/
└── jobs/
    └── 2026-10-01__12-00/      # a job folder: config.json, result.json, a folder per trial
        ├── config.json
        ├── result.json
        └── greet__4X34U7A/
            ├── result.json
            ├── lock.json
            └── agent/trajectory.json

A task folder is any folder holding task.toml. dataset.toml manifests are ignored; the task folders inside a dataset folder import like any other. The zip root itself cannot be a task folder: put each task in its own folder.
A job folder holds config.json and result.json and has a folder per trial, each with its own result.json. Include the whole job folder; a trial folder on its own is read past with a warning.

A zip of job folders alone imports runs of tasks imported earlier: import it into the taskset that holds those tasks.

Start an import

There are three ways to start an import. All three upload the zip to your team’s Data store and import it into a taskset you can edit, and every import shows up on the taskset’s Imports tab.

Web app
CLI
REST API

Select Import from Harbor on the Tasksets page to create a new taskset, named after the zip unless you rename it. To add to an existing taskset, select Import in the taskset’s header, or Import from Harbor on its Imports tab.Drop the zip on the dialog, click to choose it, or pick a zip already in Data with Choose from Data. The dialog estimates how long the import will take before you start it.

The Import from Harbor dialog with my-benchmark.zip chosen, the new taskset named my-benchmark, and an estimate of about a minute, free.

Start import opens the import on the taskset’s Imports tab.

hud harbor import takes Harbor folders, or one zip of them, and zips folders for you:

hud harbor import ./tasks ./jobs/2026-10-01__12-00 --taskset my-benchmark

--taskset takes a taskset name or ID; a name with no taskset creates it. The command follows the import until it ends and prints the report. hud harbor imports lists imports, hud harbor report <import-id> prints the report of an earlier import, and hud harbor cancel <import-id> stops a running one. See Harbor interoperability for every option.

The Imports endpoints take the same zip with format harbor:

POST /v2/imports/uploads reserves a data file and returns a presigned upload URL. Upload the zip with PUT, then publish it with POST /v2/data/{file_id}/complete.
POST /v2/imports with {"format": "harbor", "file_id": "...", "taskset_id": "..."} starts the import.
Poll GET /v2/imports/{import_id} until it ends, then read GET /v2/imports/{import_id}/report.

What an import creates

Tasks. Each task folder becomes an environment named after the folder, created in the taskset’s Project on first import and suffixed when your team already has an environment of that name, and a task of the taskset on that environment. The environment’s version is the folder’s Harbor content digest: importing the same content again changes nothing, and changed content becomes the environment’s next version, which its task moves to in every taskset you can edit.
Jobs. Each job folder becomes a HUD job, marked with a Harbor badge. Each finished trial becomes a trace of the task it ran: its agent/trajectory.json (ATIF) becomes the trace’s steps, and its result.json and verifier reward become the trace’s outcome. Unfinished trials are skipped.
Links between runs and tasks. A trial links to its task by the task digest in its lock.json, or, for trials from Harbor versions without trial locks, by the task_checksum in its result.json, matched against the task folders in the same zip. A task the zip does not hold is looked up among Harbor environments already in the taskset’s Project.

Follow an import

An import is queued, starting, or running while it works, and cancelling after a cancel request. It ends in one of four statuses:

Status	Meaning	Report
`completed`	The import ran to the end. Items it skipped or HUD refused are listed in the report.	Yes
`stopped`	The import was refused or stopped partway: the zip could not be read, you cannot edit the taskset, or a platform or storage failure interrupted it. Its summary and report say why. The web app shows it as Failed.	Yes
`failed`	The import could not run to an outcome. Its error says why.	No
`cancelled`	You cancelled it. Anything imported before the cancel stays in the taskset.	No

The taskset’s Imports tab lists its imports, newest first, with what each added and how many items it skipped or failed. Cancel a running import from its row.

A taskset's Imports tab listing a completed import of my-benchmark.zip that added three tasks and three runs and skipped one task.

Read the report

Open an import to read its report: every task, job, and trial in the zip, with its status and, for anything skipped or failed, the reason. Tasks open the taskset’s task, jobs open the job, and trials open their trace. Download saves the original zip or the report as JSON.

The report of an import, listing three imported tasks and one task skipped because it is missing instruction.md.

Item status	Meaning
Imported	Added by this import.
Updated	A task whose changed content moved it to a new version.
Unchanged	Already in HUD from an earlier import.
Skipped	Not imported; the reason says why.
Failed	HUD refused the item; the reason says why.

A job’s status follows its trials, unless the job folder itself was skipped or HUD refused the job. Skipped and failed items do not fail the import.

Import again

Importing the same zip again is safe, and resumes an import that stopped: environments, tasks, jobs, and traces are matched by digest and Harbor id instead of being created twice. To update a task, change its folder and import it again; to add runs, import their job folders into the taskset that holds the tasks.

Limits and permissions

The zip is at most 1 GiB, with at most 200,000 entries and 8 GiB unpacked. Import a larger set in several imports into the same taskset.
Harbor imports are free.
You must be able to edit the taskset. Team admins see every import on the team; other members see the imports they started.
A team holds one Harbor environment per task folder name. A task folder whose environment already exists in another Project fails, and two folders in one zip with the same name but different content stop the import.
A taskset holds one task per name. A task found in HUD joins the taskset only if the taskset has no task of that name, and a trial of another version of a task links only if the taskset’s task has held that version.
A trial without lock.json links only to a task folder in the same zip.

Common skip reasons

Reason in the report	What to do
`not a valid Harbor task: ...`	Harbor would not run the folder: its `task.toml` does not match Harbor’s schema, it has no environment, or it lacks `instruction.md` or a test script. Fix the folder until `harbor run` accepts it.
`same content as <path>, which is imported`	The zip holds the same task twice. Nothing to do.
`the trial has not finished`	Harbor was still running the trial when the job folder was zipped. Import the job again once it finishes.
`a trial outside its job folder; include the whole job folder`	Zip the job folder, not individual trial folders.
`it ran '<task>' (sha256:...), which is neither in the bundle nor a Harbor task in HUD`	Import the task folder, in the same zip or before the job, into the same taskset.
`... task folder <path> differs from it, so it changed after the run`	The task changed after the trial ran. Import the task folder as it was when the trial ran into the taskset, then import the job.
`it has no lock.json and its task_checksum matches no task folder in the bundle`	Trials from Harbor versions without `lock.json` link only to a task folder in the same zip. Include the unchanged task folder.
`its task is in HUD environment <name>, which belongs to a Project other than the taskset's`	Import into a taskset in that Project.
`its task is in several HUD environments (...)`	The same task content was imported under several names. Include the task folder in the zip to pick one.
`... is not a Harbor job result: ...` or `... is not a Harbor trial result: ...`	The job or trial files do not load with Harbor’s models. Check the Harbor version that wrote them.

Start here

Core workflows

Platform features

Reference

Harbor import

Prepare the zip

Start an import

What an import creates

Follow an import

Read the report

Import again

Limits and permissions

Common skip reasons

​Prepare the zip

​Start an import

​What an import creates

​Follow an import

​Read the report

​Import again

​Limits and permissions

​Common skip reasons

Prepare the zip

Start an import

What an import creates

Follow an import

Read the report

Import again

Limits and permissions

Common skip reasons