Hf Broker

Hugging Face Broker

Use the preconfigured HF Broker for protected Hugging Face operations. Never ask for, print, copy, or export the broker's Hugging Face token. Do not run hf auth login to work around a broker decision.

Choose a workflow

Use the advertised hf_* MCP tools for ordinary typed operations and grant management. Use hf-broker client when a local file must enter or leave the protected stream store. The runtime already provides the broker endpoint and a limited agent credential.

Every mutation needs a stable request ID. Reuse it only for an exact retry of the same operation. If a response is lost, recover the existing operation or grant instead of submitting another mutation.

Request reusable write access

Request a temporary grant only when repeated operations are needed. Keep the scope as narrow as the user requested, and always use the number of uses the user requested. Do not substitute a fixed example value. A day is 1,440 minutes and a week is 10,080 minutes.

For job.run and job.uv.run:

• "Allow any N jobs" means max_uses: N with attrs omitted or empty, so job arguments may change between uses for the same target.
• "Run this exact job N times" means max_uses: N with exact target and argument digest attrs.
• If it is unclear whether arguments may change, ask one short question before requesting the grant.

Before requesting approval, say either "any job arguments for this target" or "exact job arguments only." Never silently narrow an any-job request with exact digests.

Set REQUESTED_USES to the number the user requested. For one bucket key prefix:

hf-broker client grant request bucket.object.write OWNER/BUCKET \
  --key 'artifacts/**' \
  --minutes 10080 \
  --max-uses "$REQUESTED_USES" \
  --reason "Write the requested artifacts for one week" \
  --request-id STABLE-GRANT-REQUEST-ID

For one repository path prefix:

hf-broker client grant request repo.commit.create OWNER/REPO \
  --type dataset \
  --path 'data/**' \
  --minutes 1440 \
  --max-uses "$REQUESTED_USES" \
  --reason "Update the requested dataset path for one day" \
  --request-id STABLE-GRANT-REQUEST-ID

Normal append-only Git pushes can also use a scoped git.push.append grant. Keep the repository type, ref, and path selectors exact. Force pushes, ref deletion, repository deletion, visibility changes, and access management stay short-lived or single-use.

A pending grant requires an operator decision. Keep waiting on the same grant rather than creating another request:

hf-broker client grant wait --wait-timeout 15m GRANT-ID
hf-broker client grant get GRANT-ID

MCP grant calls use bounded waits. If hf_grant_request or hf_grant_wait returns pending, call hf_grant_wait again with the same grant ID. Use hf_grant_cancel for an unapproved request and hf_grant_revoke when reusable access is no longer needed.

Write and read bucket objects

Upload a local file through the broker's stream store. File bytes do not belong in MCP JSON, chat messages, plans, approvals, or logs.

hf-broker client bucket object write \
  --target-json '{"kind":"bucket","namespace":"OWNER","name":"BUCKET"}' \
  --arguments-json '{"path":"artifacts/result.bin"}' \
  --source ./result.bin \
  --media-type application/octet-stream \
  --reason "Upload the requested result" \
  --request-id STABLE-WRITE-REQUEST-ID \
  --wait=true \
  --wait-timeout 15m

Set "overwrite":true only when replacing the currently observed object is intentional. The broker checks the bound precondition again before commit.

Read into a new destination and let the client verify the returned stream:

hf-broker client bucket object read \
  --target-json '{"kind":"bucket","namespace":"OWNER","name":"BUCKET"}' \
  --arguments-json '{"path":"artifacts/result.bin"}' \
  --output ./downloaded-result.bin \
  --reason "Read the requested result" \
  --wait=true \
  --wait-timeout 15m

Use hf_bucket_object_list or the matching client command to inspect only the approved bucket prefix. Do not use the ML Claw state bucket for agent work. Its exact target is denied by deployment policy, and approval cannot override that deny.

Recover operations

A timeout may leave a durable operation pending. Continue with its operation ID or recover it by request ID:

hf-broker client operation get OPERATION-ID
hf-broker client operation wait --wait-timeout 15m OPERATION-ID
hf-broker client operation cancel OPERATION-ID

If the operation ID was lost, call the hf_operation_list MCP tool with the stable request_id, then continue with the returned operation ID.

Stop only after a terminal result, explicit cancellation, or an unrecoverable broker error. Revocation and expiry prevent later matching writes from reaching Hugging Face.