Find a model. Check the file yourself.

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

Reading the states: servedFrom recent means a checked answer from the last hour (answerAgeSeconds gives its age); use it. degraded or stale true means a live check did not finish and the answer is older than that, so re-read the download plan before using it; 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.
curl --retry 3 --retry-delay 5 --retry-max-time 30 -fsS 'https://huggingbay.xyz/api/agents/find-runnable?task=chat&hardware=8gb-laptop&os=linux'

# 2. Plan: lists every file with sha256, size and downloadEndpoint. This example stops before downloading model bytes.
ID=$(curl --retry 3 --retry-delay 5 --retry-max-time 30 -fsS 'https://huggingbay.xyz/api/v1/resolve?repo=sentence-transformers/all-MiniLM-L6-v2' | python3 -c 'import json,sys; print(json.load(sys.stdin)["artifactId"])')
curl --retry 3 --retry-delay 5 --retry-max-time 30 -fsS 'https://huggingbay.xyz/api/v1/artifacts/'"$ID"'/download-plan'

# 4. Run: lists the tested commands in runKit when present; inspect them before running anything locally.
ID=$(curl --retry 3 --retry-delay 5 --retry-max-time 30 -fsS 'https://huggingbay.xyz/api/v1/resolve?repo=sentence-transformers/all-MiniLM-L6-v2' | python3 -c 'import json,sys; print(json.load(sys.stdin)["artifactId"])')
curl --retry 3 --retry-delay 5 --retry-max-time 30 -fsS 'https://huggingbay.xyz/api/agents/deployment-plan?artifact='"$ID"

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

Public reads need no token. For account workflows, use the self-serve key page at /quickstart/keys; the token is shown once, so save it.

Inspect the separate Bay Run service

Bay Run runs small specialist models on a separate service. These public GET requests show its status and route catalog without creating credentials or sending task input. Its own quickstart explains authenticated runs.

# Read the public service manifest
curl -fsS 'https://run.huggingbay.xyz/v1'
# List public task routes
curl -fsS 'https://run.huggingbay.xyz/v1/pins'

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. Check a hosted download plan

Resolve an upstream repo (or use an id from search), then read its current plan for file paths, hashes and sizes. This quickstart stops before downloading. The Python SDK's download_file method also submits a completion receipt after a successful transfer.

ID=$(curl --retry 3 --retry-delay 5 --retry-max-time 30 -fsS 'https://huggingbay.xyz/api/v1/resolve?repo=sentence-transformers/all-MiniLM-L6-v2' | python3 -c 'import json,sys; print(json.load(sys.stdin)["artifactId"])')
curl --retry 3 --retry-delay 5 --retry-max-time 30 -fsS "https://huggingbay.xyz/api/v1/artifacts/$ID/download-plan"

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

Current published tools: MCP 0.1.14, Python SDK 0.4.12, hbay CLI 0.2.1. Point an MCP client at the remote endpoint or use the pinned install channels.

# Check the published MCP package, then install the Python SDK in a fresh environment.
npx -y hugging-bay-mcp@0.1.14 --version
python3 -m venv .venv && . .venv/bin/activate
python -m pip install hugging-bay==0.4.12

# 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.1 release is available for Linux x86_64/aarch64 and Apple silicon macOS. This install pins the published release for your machine without changing the server's configured default. Start with --help; catalog only reads public metadata.

curl -fsSL 'https://huggingbay.xyz/cli/install.sh' | RELEASE_BASE_URL='https://storage.googleapis.com/hb-desktop-releases-barneyserver/hbay/hbay-0.2.1-native-5789eb6b6-20261024' sh
export PATH="$HOME/.local/bin:$PATH"
hbay --version
hbay --help
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.12"

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.77; 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.77_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";
const getJson = async (url) => {
  const response = await fetch(url);
  const body = await response.json();
  if (!response.ok) throw new Error(`GET ${url} returned ${response.status}: ${JSON.stringify(body)}`);
  return body;
};

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

// 2. resolve -> id, then read the hosted plan
const resolved = await getJson(`${BASE}/api/v1/resolve?repo=sentence-transformers/all-MiniLM-L6-v2`);
const plan = await getJson(`${BASE}/api/v1/artifacts/${resolved.artifactId}/download-plan`);
if (!resolved.artifactId || !Array.isArray(plan.files)) throw new Error('resolve or download plan returned an invalid shape');
// 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)