# Harbor Hf

> Submit, monitor, pause, resume, cancel, and inspect Harbor benchmark runs through the hosted Harbor-HF control service and Hugging Face Jobs.

- Skill: `huggingface/harbor-hf` (Agent Skill)
- Install (CLI): `npx skillmds@latest add huggingface/harbor-hf`
- Raw SKILL.md: https://api.skillmd.com/api/skills/huggingface/harbor-hf/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Hugging Face (https://skillmd.com/u/huggingface)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/huggingface/harbor-hf

---


# Harbor-HF operations

Use this skill for Harbor benchmark runs on Hugging Face infrastructure.

Harbor-HF has two persistent resources:

- one private control Space
- one private Bucket for run records and Harbor output

Do not create a run-specific repository, Space, Bucket, Dataset, endpoint, or
coordination store. Use the existing control service and Bucket.

## Read the current contract

Before an operation, read these files from the Harbor-HF repository:

- `docs/2026-09-04-simplification-implementation-spec.md`
- `docs/CONTROL_SERVICE.md`
- `docs/architecture.md`

Use the `paid-compute-launch` skill before a paid Job launch, retry, or resume.
Use the Hugging Face CLI and Spaces skills for Hub and Space operations.

## Keep credentials separate

The control Space has two secrets:

- `HF_TOKEN` controls the Bucket and HF Jobs.
- `HF_INFERENCE_TOKEN` is for model inference through the Hugging Face router.

Do not print either value. Do not put a credential literal in a run request,
Bucket object, Job label, log, or result. The control service gives both secrets
to the reviewed parent Job as ephemeral Job secrets. The parent uses the control
token to start and label child Sandbox Jobs. The benchmark agent receives only
the inference token through the fixed `${HF_INFERENCE_TOKEN}` template. Pi uses
its built-in Hugging Face provider so model prices remain available for Harbor
cost accounting.

Do not copy a token to another store. Use a configured token in place.

## Submit a run

Prefer a reviewed preset in the web console or `POST /api/v1/runs`. A preset
submission selects:

- one benchmark preset
- one model ID and provider
- one agent preset and reasoning value
- one positive maximum cost in USD for the complete campaign
- a `final` or `diagnostic` role

Use a unique `Idempotency-Key`. A repeated key with the same request adopts the
existing run. A repeated key with different content is an error.

Use a direct Harbor `JobConfig` only when a preset cannot express the test:

```bash
uv run harbor-hf submit \
  --config job.yaml \
  --cost-ceiling-usd 100
```

The service replaces caller-controlled paths, environment, and router
credentials. It rejects unknown fields, multiple agents, source jobs, local
paths, caller-supplied agent environments or skills, custom environments,
credential literals, and credentials in URLs. Direct runs are diagnostic and
cannot enter the leaderboard.

## Inspect and control runs

Set these environment variables without printing their values:

```text
HARBOR_HF_CONTROL_URL
HARBOR_HF_CONTROL_BEARER_TOKEN
```

Use the thin client:

```bash
uv run harbor-hf run list
uv run harbor-hf run status <run-id>
uv run harbor-hf jobs
uv run harbor-hf presets
uv run harbor-hf run pause <run-id>
uv run harbor-hf run resume <run-id>
uv run harbor-hf run cancel <run-id> --yes
```

A pause cancels the active parent and labeled child Jobs. Resume starts a new
parent against the same Harbor `job/` folder. Harbor skips completed trials.
Cancellation is permanent.

The Bucket is the durable source of truth. SQLite is a disposable three-table
projection. HF Job state is an observation, not the run record.

## Cost and completion rules

The campaign cost ceiling is checked after each trial because Harbor writes the
result before it calls the end hook. The parent writes one immutable cost receipt
for each Harbor attempt before Harbor can remove a failed retry folder. It
reloads these receipts after restart. A missing cost stays null in the receipt
and contributes zero to the ceiling calculation. It does not stop other work.

The ceiling applies to the sum of all trial-attempt costs in the campaign. It is
not divided into per-trial limits. With concurrent trials, work that is already
active can finish before cancellation, so reported cost can exceed the ceiling.

Treat a run as complete only when:

- Harbor wrote `job/result.json` with a finished status;
- no labeled parent or child Job is active;
- each expected trial has a durable Harbor result;
- the known trial cost total is within the approved limit; and
- the projection rebuild gives the same run state.

Only completed `final` runs from a leaderboard-eligible preset, with at least
one score, enter the public leaderboard.

## Stop conditions

Stop automatic work and report evidence for:

- credential exposure or token reuse;
- a Harbor, benchmark, image, or backend revision mismatch;
- a deterministic shared parent or child defect;
- duplicate logical execution;
- cost outside the approved limit;
- an immutable run-record conflict;
- a Bucket integrity or Harbor resume failure; or
- a labeled Job that the reconciler cannot stop.

Do not bypass a stop by creating another resource, copying a credential, or
using an unreviewed runtime.