Find a model. Check the file yourself.

Agent flow: find-runnable → download-plan → check SHA-256 → run

Reading the states: degraded or stale true means a live check did not finish, so you see the last checked answer (lastGood.ageSeconds or freshness.lastGoodAgeSeconds gives its age); each download is checked again when you request it. runTested means sealed exact-file commands exist; runReady is false only when runReadyReasonCodes names a concrete blocker (not freshness alone). Read summary for one plain sentence. selectionPin keeps one pick per query for a snapshot: held is the same pick as before, promoted means that pick became unavailable and the next best fitting file replaced it, unavailable means nothing fits right now. selectionProvisional true means better-ranked models were still being checked, so retry in a few seconds for the settled pick. A 503 or 429 carries retry_after_s: wait that long, then retry. MCP: the canonical endpoint is /api/mcp. /mcp is an alias handled by the same server code, with the same tools.

# 1. Find: picks one hosted file that fits your task and memory. find-model returns the same pick plus a shortlist. Optional os=macos|linux|windows selects a single local handoff when getRunning is enabled.
GET https://huggingbay.xyz/api/agents/find-runnable?task=chat&hardware=8gb-laptop&os=linux

# 2. Plan: lists every file with sha256, size and downloadEndpoint.
GET https://huggingbay.xyz/api/v1/artifacts/{id}/download-plan

# 3. Check: download from downloadEndpoint and compare the SHA-256 on your machine.
shasum -a 256 <file>

# 4. Run: use the tested commands in runKit when present.
GET https://huggingbay.xyz/api/agents/deployment-plan?artifact={id}

1. Get an API key (self-serve, no signup)

Public reads need no token, so you can skip this for search/resolve/download-plan. For account workflows POST /api/account/reader-token with no prior authentication; the token is shown once, so save it. Not sure which key you need? Read the three doors at /quickstart/keys.

curl -fsS -X POST 'https://huggingbay.xyz/api/account/reader-token' \
  -H 'Content-Type: application/json' \
  -d '{"displayName":"my app","purpose":"saving finds"}'
# -> { "apiKey": { "token": "hbk_..." }, ... }  (shown once)
export HUGGING_BAY_TOKEN="hbk_..."

Run models (Bay Run)

A separate service for running small specialist models. It uses a different origin and key. Public reads on this site need no key; account workflows use the reader token above; running models uses a free Bay Run key.

# START HERE → mint a free key (last checked 2026-09-26)
BAY_RUN_KEY=$(curl -sS -X POST 'https://run.huggingbay.xyz/v1/keys/free' -H 'content-type: application/json' -d '{}' | python3 -c "import json,sys; print(json.load(sys.stdin)['key'])")
# First run: uses the key from the line above, nothing to paste
curl -sS -X POST 'https://run.huggingbay.xyz/v1/run/route_00857aa05f863c2cdba0e908366b2cca' -H "Authorization: Bearer $BAY_RUN_KEY" -H 'content-type: application/json' -d '{"input":"The quick brown fox jumps over the lazy dog."}'

Which key do I need? Reader token = your account on this site (notify, watchlists). Free Bay Run key = running models on run.huggingbay.xyz. OAuth demo grant exists for agents that prefer it. The Bay Run skill has the full contract.

Free keys are for trying things: 500 tasks a day per key. Read the response for current limits and error guidance.

2. Make your first call (no key required)

Search returns catalog rows with artifact ids. For task-first discovery use find-model (the live /api/agents/find-model route) with a task and an optional hardware preset. Cursor pagination applies to list endpoints that document cursor and nextCursor; health and download plans are not paginated. General API errors carry a support id (request_id and requestId) and a next step. Notification subscribe and lookup errors use request_id; confirmation and unsubscribe errors have separate shapes. Paused subscribe and lookup responses return next: null and retryable: false.

# a) catalog search
curl -fsS 'https://huggingbay.xyz/api/v1/search?q=embedding&limit=3&sort=best'

# b) task-first discovery. find_model, matching the live API
curl -fsS 'https://huggingbay.xyz/api/agents/find-model?task=embeddings&hardware=8gb-laptop&limit=3'

3. Download a hosted model into your app

Resolve an upstream repo (or use an id from search) -> read the hosted download plan (per-file sha256 + size; honestly empty when nothing is hosted or the license does not permit a mirror) -> download a file from the plan's downloadUrl and check its SHA-256 locally. Pure curl works today with no install; the Python SDK does the resolve -> plan -> signed-URL download -> hash check -> attest chain for you.

# a) resolve to a catalog id (artifactId is the one id key every surface uses)
ID=$(curl -fsS 'https://huggingbay.xyz/api/v1/resolve?repo=sentence-transformers/all-MiniLM-L6-v2' | jq -r .artifactId)

# b) read the hosted plan (files, sizes, sha256) for that exact id
curl -fsS "https://huggingbay.xyz/api/v1/artifacts/$ID/download-plan"

# c) download a listed file and check its sha256 locally (no install)
curl -fsSL '<downloadUrl from the plan>' -o model.bin
printf '%s  model.bin\n' '<sha256 from the plan>' | shasum -a 256 -c -

# Ergonomic path: the Python SDK checks + attests for you.
# Install: python -m pip install hugging-bay  (details: https://huggingbay.xyz/python-sdk)
python - <<'PY'
from hugging_bay import Client
c = Client()
# SDK 0.4.9 supports device_family; hardware presets are available in REST.
pick = c.find_model("embeddings", device_family="cpu", limit=3)
# Resolve the same repo, then use the returned catalog id.
resolved = c.resolve("sentence-transformers/all-MiniLM-L6-v2")
artifact_id = resolved["artifactId"]
plan = c.download_plan(artifact_id)
# An artifact-wide lock is optional: it requires a complete hashed inventory.
# A 409 artifact_identity_unavailable does not invalidate a listed file hash.
for f in plan["files"]:
    c.download_file(artifact_id, f["path"], f["path"],
                    sha256=f["sha256"], size_bytes=f["sizeBytes"])
PY

4. Connect an agent (MCP) or install the tools

Current published tools: MCP 0.1.10, Python SDK 0.4.9, hbay CLI 0.2.0. Point an MCP client at the remote endpoint or use the pinned install channels.

# Published clients
npx -y hugging-bay-mcp@0.1.10
python -m pip install hugging-bay==0.4.9

# Remote MCP (list the self-describing tools)
curl -fsS 'https://huggingbay.xyz/api/mcp' -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Manifest + one-file server card
curl -fsS 'https://huggingbay.xyz/.well-known/mcp.json'

# Connection guide + install channels (CLI, stdio MCP, SDK):
#   https://huggingbay.xyz/developers/mcp   https://huggingbay.xyz/install   https://huggingbay.xyz/python-sdk

Try local chat (native CLI preview)

The signed hbay 0.2.0 release includes these opt-in preview commands. General --help omits them; after setting the flag, use hbay chat --help, hbay pick --help or hbay doctor --help to check your build. Chat and pick need an interactive terminal; for scripts use hbay catalog and hbay download. Chat asks what you need and how much memory to use, with a detected default. It starts only when a small model has fresh matching run evidence. Pick shows estimated memory fit. Doctor explains local setup problems; --fix repairs common ones. Downloads can resume when you repeat the command. Release availability is listed on /install. The extra examples below require a newer source build and are not included in the signed release.

export PATH="$HOME/.local/bin:$PATH"
export HBAY_ENABLE_FRIENDLY_CLI=1
hbay chat

# Search and choose a model.
hbay pick qwen

# Check setup, then apply common fixes.
hbay doctor
hbay doctor --fix

# Disable terminal colours.
NO_COLOR=1 hbay download ARTIFACT_ID

# Newer source build only (not the signed release above).
hbay pick --task chat --ram 8
hbay chat owner/model-name
hbay catalog qwen --task chat --max-ram 8

On a server, CI runner or AI-agent VM (no display, no GPU)

You do not need a screen or a graphics card. Pick one of these.

1. Connect an agent to the hosted MCP server

Nothing to install. Point your MCP client at this address. It uses plain HTTPS; in our test it also worked through a proxy that inspects HTTPS traffic.

https://huggingbay.xyz/api/mcp

2. Use the Python SDK

Install it in a virtual environment; many Linux systems block pip install outside one.

python3 -m venv .venv && . .venv/bin/activate
pip install "hugging-bay==0.4.9"

Behind a proxy that inspects HTTPS traffic, point Python at the system certificates (or your company's certificate file):

export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt

3. Run a model on the CPU with the Linux app

The Linux AppImage from the desktop page (current release 0.2.9; the recorded walkthrough used 0.2.6) includes a command-line tool, hbay-desktop. Servers often lack the libraries the app window needs, so unpack the AppImage first and run the tool directly:

./The.Hugging.Bay_0.2.9_amd64.AppImage --appimage-extract
H=squashfs-root/usr/bin/hbay-desktop
$H catalog qwen3
$H download ARTIFACT_ID
$H prompt /path/to/model.gguf --sha256 SHA256_FROM_DOWNLOAD --prompt "Hello" --max-tokens 96

download prints the file path and SHA-256 as JSON. prompt checks the SHA-256 before loading the model and runs on the CPU, on this machine.

Behind a proxy

Set the usual proxy variables, and tell Python and Node.js tools where your certificates are:

export HTTPS_PROXY=http://proxy.example:3128 HTTP_PROXY=http://proxy.example:3128
export NO_PROXY=localhost,127.0.0.1,::1
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt        # Python
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt  # Node.js

Write ::1 without brackets in NO_PROXY; the Python SDK ignores [::1]. In our test, NODE_EXTRA_CA_CERTS let the npm MCP package start, but its tool calls still failed behind the proxy, so use the hosted MCP server above.

JavaScript / TypeScript

The read path is a plain fetch; the check-and-attest download path lives in the Python SDK and CLI.

// Node 18+ / browsers: reads need no key. Send Authorization: Bearer <token>
// only for account workflows. Downloads use short-lived signed URLs; use the
// Python SDK (or the CLI) for the check + attest step.
const BASE = "https://huggingbay.xyz";

// 1. search
const rows = await fetch(`${BASE}/api/v1/search?q=embedding&limit=3`).then(r => r.json());

// 2. resolve -> id, then read the hosted plan
const resolved = await fetch(`${BASE}/api/v1/resolve?repo=sentence-transformers/all-MiniLM-L6-v2`).then(r => r.json());
const plan = await fetch(`${BASE}/api/v1/artifacts/${resolved.artifactId}/download-plan`).then(r => r.json());
// plan.files[].sha256 / .sizeBytes are what you check after download.

Reference and honesty rules

Copy-paste API recipes live under /api and the full interactive contract at /docs/api (OpenAPI 3.1). Download URLs come from plans for reviewed, hosted files. Empty plans contain files: [] and serve.downloadReady: false. After downloading, compare the file's SHA-256 with the plan.

Intents are capped at 2000 characters; input is never echoed back raw. A request blocked by the abuse filter returns 403 request_blocked as JSON before processing.

Which key do you need? (three doors)