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:

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:

HARBOR_HF_CONTROL_URL
HARBOR_HF_CONTROL_BEARER_TOKEN

Use the thin client:

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.