# Connect a coding agent to InferenceHub

InferenceHub is a byte-faithful gateway: one API key for Claude, GPT, and every model, served on their
native APIs with 0% per-token markup. Point any compatible client at the gateway and keep your existing code.

## Documentation map

Rendered docs live at https://inferencehub.tech/docs, one page per topic:

- Overview: https://inferencehub.tech/docs — What InferenceHub is and how the gateway works.
- Quickstart: https://inferencehub.tech/docs/quickstart — Key to first request in three steps — curl and SDK examples.
- Claude Code: https://inferencehub.tech/docs/agents/claude-code — Claude and the open-weight daily drivers in Claude Code.
- Codex: https://inferencehub.tech/docs/agents/codex — OpenAI Codex on the Responses wire.
- Cursor: https://inferencehub.tech/docs/agents/cursor — Open-weight, Claude, and GPT-5.6 as Cursor custom models.
- Kilo Code: https://inferencehub.tech/docs/agents/kilo-code — The full catalog from one kilo.json — CLI and VS Code extension.
- ZCode: https://inferencehub.tech/docs/agents/zcode — Z.ai's GLM-5.2 harness on your InferenceHub key.
- Hermes: https://inferencehub.tech/docs/agents/hermes — Open-weight chat models in the Hermes CLI.
- API overview: https://inferencehub.tech/docs/api — Wire formats, base URLs, authentication, streaming.
- Image generation: https://inferencehub.tech/docs/api/images — OpenAI Images API — gpt-image-2 and gpt-image-1.5.
- Embeddings & rerank: https://inferencehub.tech/docs/api/embeddings — Embedding and reranker models for RAG pipelines.
- Models: https://inferencehub.tech/docs/models — Model ids, aliases, and how to list what your key reaches.
- Auto routing: https://inferencehub.tech/docs/auto — ih-auto and ih-auto-smart — a flat sheet, per-request routing, and honest escalation.
- Model synthesis: https://inferencehub.tech/docs/synthesis — ih-synthesis presets and the model_synthesis tool — a model panel answers, a synthesizer merges.
- Billing & plans: https://inferencehub.tech/docs/billing — Prepaid balance, subscription plans, free chat models, and the daily reward.
- Desktop app: https://inferencehub.tech/docs/desktop — The open-source native client for the hosted chat.
- Troubleshooting: https://inferencehub.tech/docs/troubleshooting — Common HTTP errors and per-agent fixes.
- Support: https://inferencehub.tech/docs/support — Discord, Telegram, email, and the status page.

## Quickstart

1. Create an account at https://app.inferencehub.tech/portal — no credit card required. Every account starts with $1 in free credit.
2. Create an API key in the portal. It looks like `sk-prov-live-…`. Keep it secret; revoke any time.
3. Point your client at the gateway base URL and use your key. Then run your client exactly as usual.

## API surfaces

The gateway speaks the native wire formats below. Use whichever your client already supports — requests and
responses pass through byte-for-byte.

| Format | Endpoint | Base URL |
| --- | --- | --- |
| Anthropic Messages | `/v1/messages` | `https://app.inferencehub.tech` (bare origin — the client appends `/v1/messages`) |
| OpenAI Chat Completions | `/v1/chat/completions` | `https://app.inferencehub.tech/v1` |
| OpenAI Responses | `/v1/responses` | `https://app.inferencehub.tech/v1` |
| OpenAI Images | `/v1/images/generations` | `https://app.inferencehub.tech/v1` |
| OpenAI Embeddings | `/v1/embeddings` | `https://app.inferencehub.tech/v1` |
| Rerank | `/v1/rerank` | `https://app.inferencehub.tech/v1` |

## Image generation

The gateway serves the OpenAI Images API at `POST /v1/images/generations`; the OpenAI SDK's
`client.images.generate(...)` works unchanged against the `https://app.inferencehub.tech/v1` base.

```bash
curl https://app.inferencehub.tech/v1/images/generations \
  -H "Authorization: Bearer sk-prov-live-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "flat minimalist vector logo of an orange fox head, white background",
    "size": "1024x1024",
    "quality": "low"
  }'
```

The image comes back inline as base64 in `.data[0].b64_json` (no `url` variant) — decode with
`jq -r '.data[0].b64_json' | base64 -d > image.png`.

Two models are live, billed per-token at the native published rates: `gpt-image-2` ($5.00/1M text-input,
$30.00/1M image-output tokens) and `gpt-image-1.5` ($5.00/1M in, $10.00/1M out). Cost scales with size and
`quality` (low / medium / high / auto) — the low-quality 1024×1024 example above bills about $0.006.

- Sizes: `1024x1024`, `1536x1024`, `1024x1536`, or `auto` — larger concrete sizes are rejected.
- Up to 4 images per request (`n`).
- Non-streaming only — omit `stream`.
- Generation only for now: `/v1/images/edits` and variations are not yet available.

## Embeddings & rerank

OpenAI Embeddings at `POST /v1/embeddings` (`input` = string or array of up to 2048 strings):

```bash
curl https://app.inferencehub.tech/v1/embeddings \
  -H "Authorization: Bearer sk-prov-live-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "bge-m3", "input": ["the quick brown fox", "pack my box"]}'
```

Live embedding models (input-only billing, per 1M tokens): `all-mini-lm-l6-v2` $0.009 ·
`multi-qa-mpnet-base-dot-v1` $0.009 · `bge-m3` $0.02 · `e5-large-v2` $0.02 ·
`qwen3-embedding-0.6b` $0.04 · `gte-large-en-v1.5` $0.09.

Rerank at `POST /v1/rerank` — `query` plus up to 150 `documents`, returning
`results[].{index, relevance_score}`. Serves `bge-reranker-v2-m3` at $0.01/1M tokens, input-only:

```bash
curl https://app.inferencehub.tech/v1/rerank \
  -H "Authorization: Bearer sk-prov-live-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "bge-reranker-v2-m3", "query": "how do I top up?", "documents": ["Top up with card or crypto.", "Models are served at parity."]}'
```

## Desktop app

InferenceHub Desktop is a lightweight, open-source native client for the hosted chat — frontier and
open-weight models with web search, deep research, and project files, outside the browser. Source:
https://github.com/InferenceHub/inferencehub-desktop. Download the latest release at
https://github.com/InferenceHub/inferencehub-desktop/releases/latest —
`InferenceHub_<version>_x64-setup.exe` (Windows x64) or
`InferenceHub_<version>_aarch64.dmg` (macOS Apple Silicon). Current builds are unsigned
preview builds (the OS warns on first run; install steps are in the project README). Code-signed
builds are in progress.

## Authentication

Use the same `sk-prov-live-…` value wherever your client expects its provider credential:

- OpenAI-format clients: as the OpenAI API key (sent as `Authorization: Bearer`).
- Anthropic-format clients: as the Anthropic API key / auth token (`x-api-key` or `ANTHROPIC_AUTH_TOKEN`).

## Discover the models your key can reach

The gateway serves whatever models the operator has enabled. List the live ids (the `.data[].id` shape is
common to both the Anthropic and OpenAI `/v1/models` responses, so this works for any client):

```bash
curl -s https://app.inferencehub.tech/v1/models \
  -H "Authorization: Bearer sk-prov-live-YOUR_KEY" | jq -r '.data[].id'
```

## Claude Code

Install: `npm install -g @anthropic-ai/claude-code` (verify with `claude --version`).

```json
// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://app.inferencehub.tech",
    "ANTHROPIC_AUTH_TOKEN": "sk-prov-live-YOUR_KEY",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  },
  "model": "sonnet"
}
```

The `model` field sets the default for every new session (a short alias: `sonnet`, `opus`, or `haiku`).
With `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` set (Claude Code >= 2.1.129), the `/model` picker
auto-lists every model on your plan: the Claude ids as-is, and the open-weight daily drivers under
`claude-code-*` aliases (`claude-code-glm-5.2`, `claude-code-deepseek-3.2`, … — same models, same
prices). To pin a version, launch `claude --model claude-sonnet-4-6` or use
`/model claude-sonnet-4-6` mid-session. Then just run `claude`.

**Open-weight daily drivers work here too.** Claude Code can drive every open-weight model on the
platform — `glm-5.2`, `deepseek-3.2`, `kimi-k3`, `kimi-k2.6`, `minimax-m2.5`, `qwen3.5-397b-a17b` — with tool
calls and thinking, on the same Anthropic-compatible endpoint. Set one as the default
(`"model": "glm-5.2"`) or per-session:

```bash
export ANTHROPIC_MODEL="glm-5.2"
export ANTHROPIC_SMALL_FAST_MODEL="glm-5.2"   # background calls stay open-weight too
claude
```

Switch mid-session with `/model kimi-k3` (or back to `opus` for design work) — with gateway
discovery on, these also sit in the `/model` picker as the `claude-code-*` entries. On a plan,
open-weight and lower-priced Claude usage (like `sonnet`) draws the standard windows; premium
models like `opus` draw the shared premium budget (Claude + GPT pooled).

Prefer not to pick a model at all? `ANTHROPIC_MODEL="ih-auto-smart"` routes each turn to a fast
open-weight model at a flat $1 in / $5 out per 1M tokens and escalates hard turns to Sonnet 5 (billed as
a normal `sonnet-5` pick; both sides draw the standard windows) — details at https://inferencehub.tech/docs/auto.

## Codex

Install: `npm install -g @openai/codex` (verify with `codex --version`).

```toml
# ~/.codex/config.toml
model = "gpt-5.3-codex"
model_provider = "inference-hub"

[model_providers.inference-hub]
name = "InferenceHub"
base_url = "https://app.inferencehub.tech/v1"
env_key = "INFERENCE_HUB_API_KEY"
wire_api = "responses"
```

Save your key once so it persists across sessions:

```bash
echo 'export INFERENCE_HUB_API_KEY="sk-prov-live-YOUR_KEY"' >> ~/.zshrc
source ~/.zshrc
```

Then run `codex`. (`wire_api` must be `responses` — Codex is Responses-only.)

## Cursor

Install: download the app at https://cursor.com. NOTE: a paid Cursor plan is required — Cursor's free
(Hobby) plan only allows its "Auto" model, which ignores custom endpoints. Enter these in Settings →
Models (no config file):

1. Enable "Override OpenAI Base URL" and paste: `https://app.inferencehub.tech/v1`
2. Paste your key into "OpenAI API Key": `sk-prov-live-YOUR_KEY`
3. "Add model" → e.g. `gpt-oss-120b` → Verify.

Cursor reaches InferenceHub's open-weight chat models (gpt-oss, GLM, DeepSeek, Kimi, Nemotron) — AND,
since July 2026, **Claude** and **GPT-5.6**: the gateway's translation lanes bridge Cursor's OpenAI-chat
wire to each model's native API, so `sonnet`, `sonnet-5`, `haiku`, `opus`, `fable-5`, and
`gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna` all work as custom models (Chat/Ask, Cmd-K, and
Agent mode; Tab autocomplete always uses Cursor's own models). Use ids exactly as your portal's Connect →
Cursor tab lists them — short aliases like `sonnet`, never `claude-*` names, and vendor-prefixed
open-weight ids where listed (e.g. `moonshotai-kimi-k2.6`, `zai-glm-5.2`) — Cursor hijacks names it
recognizes to its own providers. Cost note: Claude through Cursor's wire earns the prompt-cache read
discount automatically, same as on the Anthropic wire; GPT-5.6 through
Cursor earns automatic prefix-cache discounts. The flat-priced Auto ids (`ih-auto`,
`ih-auto-smart`) also work as custom models — the gateway picks the model per request
(https://inferencehub.tech/docs/auto); they're unrelated to Cursor's built-in "Auto".

## Kilo Code

Kilo ships in two forms with different base-URL rules — and both reach the FULL catalog (Claude,
open-weight, and GPT-5.6), not just Claude (verified in a real Kilo CLI session, 2026-07-17).

Kilo CLI — add InferenceHub as CUSTOM providers (NOT Kilo's built-in "Anthropic", which talks to
api.anthropic.com and rejects your key). One kilo.json carries both wires. Run `/connect` → "Other Custom
provider" → id `inferencehub` → paste your key; repeat once with id `inferencehub-oai` and the same key
(Kilo stores keys per provider id). Then create `~/.config/kilo/kilo.json` (base URLs end in `/v1`; keys
stay in Kilo's store):

```json
{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "inferencehub/sonnet",
  "provider": {
    "inferencehub": {
      "npm": "@ai-sdk/anthropic",
      "name": "InferenceHub",
      "options": { "baseURL": "https://app.inferencehub.tech/v1" },
      "models": {
        "sonnet":       { "name": "Claude Sonnet 4.6" },
        "sonnet-5":     { "name": "Claude Sonnet 5" },
        "opus":         { "name": "Claude Opus 4.8" },
        "haiku":        { "name": "Claude Haiku 4.5" },
        "zai-glm-5.2":  { "name": "GLM-5.2" },
        "deepseek-3.2": { "name": "DeepSeek 3.2" }
      }
    },
    "inferencehub-oai": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "InferenceHub (OpenAI wire)",
      "options": { "baseURL": "https://app.inferencehub.tech/v1" },
      "models": {
        "zai-glm-5.2":          { "name": "GLM-5.2" },
        "moonshotai-kimi-k3":   { "name": "Kimi K3" },
        "moonshotai-kimi-k2.6": { "name": "Kimi K2.6" },
        "gpt-5.6-sol":          { "name": "GPT-5.6 Sol" },
        "gpt-5.6-terra":        { "name": "GPT-5.6 Terra" }
      }
    }
  }
}
```

Declare any enabled model id the same way — your portal's Connect → Kilo Code tab emits this file with the
full list. Which model on which provider: keep Claude on `inferencehub` (its native Anthropic wire —
though both wires earn the prompt-cache read discount), GPT-5.6 and the chat catalog on `inferencehub-oai`;
open-weight ids work on either.

Kilo VS Code extension — Settings → Providers: API Provider "Anthropic", tick "Use custom base URL" and
paste the BARE origin (no `/v1` — the extension's SDK appends `/v1/messages`): `https://app.inferencehub.tech`. Paste your key
into "Anthropic API Key". Pick a Claude model. For GPT-5.6 / open-weight chat models, add a second custom
provider instead: Settings → Providers → "Custom provider" → Provider API "OpenAI Compatible", Base URL
`https://app.inferencehub.tech/v1`, same key — the model picker auto-fetches the catalog from the gateway's `/v1/models`.

## Hermes

The OpenAI Chat surface is enabled per-gateway by the operator; if Hermes can't connect, it isn't turned on
yet.

```yaml
# ~/.hermes/config.yaml
model:
  provider: custom
  base_url: https://app.inferencehub.tech/v1
  api_key: sk-prov-live-YOUR_KEY
  default: gpt-oss-120b
  api_mode: chat_completions
  context_length: 131072
```

Then run `hermes`. (`context_length` must be ≥ 64000.)

## ZCode

Z.ai's desktop coding agent (the official GLM-5.2 harness). Install: download at https://zcode.z.ai.
No config file — everything is entered in the GUI. 60-second setup demo: /demo/zcode-demo.mp4

1. Settings → Model settings → Add provider → name it "InferenceHub".
2. API format: `Anthropic messages (/v1/messages)`.
3. Base URL: `https://app.inferencehub.tech` — the BARE origin. ZCode appends `/v1/messages` itself; a base ending in
   `/v1` posts to `/v1/v1/messages` and 404s.
4. API key: `sk-prov-live-YOUR_KEY`.
5. Model list → Add model → `glm-5.2` (the daily driver ZCode is built around; any enabled Claude id
   works on the same provider).
6. In the chat box's model selector, pick the model under the InferenceHub provider — NOT ZCode's
   built-in Z.ai provider (that bills a GLM Coding Plan instead).

## Troubleshooting

Common HTTP errors, whatever the client:

- `401` / "invalid x-api-key" / "Unauthorized" — key wrong, revoked, or not pasted in full. Create a fresh key and re-paste the whole `sk-prov-live-…` value (no quotes, no trailing space).
- `402` / "insufficient balance" — prepaid balance and free credit spent. Top up (card or crypto) or start a subscription.
- `404` / "model not found" — that id isn't enabled on this gateway. Run the discover-models command above; check the readiness pill on the portal's Agents page.

Agent-specific:

- Claude Code — the `/model` picker lists aliases (sonnet/opus/haiku) plus a Default row; `model` in settings.json sets the default, `--model <full-id>` pins a version. Still prompts an Anthropic login or hits api.anthropic.com → run `/logout`; the config authenticates with `ANTHROPIC_AUTH_TOKEN` so no Anthropic login is needed. A stale shell export of `ANTHROPIC_BASE_URL` wins over settings.json — `echo $ANTHROPIC_BASE_URL` and unset any old one.
- Codex — every turn 400s → `wire_api = "responses"`. No key found → export `INFERENCE_HUB_API_KEY` and `source` it.
- Cursor — "Named models unavailable — Free plans can only use Auto" → Cursor's free plan blocks custom models; a paid Cursor plan is required. "Unauthorized User API key" on kimi/glm → use the vendor-prefixed id (`moonshotai-kimi-k2.6`, `zai-glm-5.2`). A `claude-*` id won't route → use the short alias exactly as listed (`sonnet`, `opus`). Tab autocomplete always uses Cursor's own models.
- Kilo Code — "invalid x-api-key" → chose built-in "Anthropic" instead of the InferenceHub custom provider. Base URL: CLI ends in `/v1`, the VS Code extension uses the bare origin. "model not found" on a `gpt-5.6-*` id → those serve on the `inferencehub-oai` (OpenAI-wire) provider, not the Anthropic one. Claude feels pricier than in Claude Code → you put it on the OpenAI-wire provider; keep Claude on `inferencehub` for the prompt-cache discount. Second provider won't authenticate → run `/connect` again with id `inferencehub-oai` (Kilo stores keys per provider id).
- Hermes — can't connect → the OpenAI Chat surface is operator-gated. "context length" error → keep `context_length: 131072`.
- ZCode — 404 on every request → Base URL must be the bare origin (no `/v1`; ZCode appends `/v1/messages`). "model not found" → use the exact gateway id (`glm-5.2`, not `zai-glm5.2`). Billed to your GLM Coding Plan → you picked the built-in Z.ai provider; select the model under the InferenceHub custom provider.

## Models & pricing

One key reaches every model — Claude (Fable, Opus, Sonnet, Haiku), GPT and Codex, GLM, DeepSeek, Kimi,
MiniMax, Qwen, NVIDIA Nemotron, and more. Select a model with the usual `model` field; switch models
without changing keys or accounts. You pay native per-token rates with 0% markup (one deliberate
exception: the flat-priced `ih-auto` routing ids — https://inferencehub.tech/docs/auto). Plans — All Access
$10/mo, Plus $25/mo, Max $50/mo — cover every model (including Opus) and every coding agent, with
overflow at the same pay-as-you-go rates and no hard stop.

## Support

- Discord: https://discord.gg/UA54nHBSJ
- Telegram: https://t.me/inference_hub
- Email: support@inferencehub.tech