Use Crush with Models Hub: crushrc Custom Provider

Edit Crush's crushrc file and use provider add and model add commands to connect Models Hub's OpenAI-compatible models, with verification and error troubleshooting.

Crush is an open-source terminal AI coding agent by Charm with multi-model switching, LSP integration, and MCP servers. Point a custom provider at Models Hub, and every chat and code edit inside crush uses your Models Hub balance for the model you choose. This page covers the connection only, not how to use Crush itself.

Three things you need

A Models Hub API key, the base URL https://modelsok.com/v1, and a model name. There's no one-click setup — Crush isn't one of the targets the Models Hub CLI supports.

Prerequisites

Crush installed. Run npm install -g @charmland/crush, or on macOS brew install charmbracelet/tap/crush; crush --version should print a version afterward. See the GitHub repository for details.
A Models Hub API key, created on the Tokens page. The token's group must have access to the models you plan to use.

Recommended models

Use case	Model	Pricing	Live status
Everyday coding	`claude-sonnet-4-6`	Price	Availability and latency
Harder reasoning and long tasks	`gpt-5.5`	Price	Availability and latency
Cheap and fast for small edits	`gpt-5.4-mini`	Price	Availability and latency

Model names are authoritative on the pricing page.

Setup

The old crush.json is deprecated

Crush now recommends declaring providers in crushrc, a Bash-style config script. The old crush.json JSON format still works but is officially marked deprecated — use crushrc for new setups.

Create or edit a crushrc file. Crush looks for one in this order: project-level ./.crushrc or ./crushrc, then the user-level ~/.config/crush/crushrc (%USERPROFILE%\.config\crush\crushrc on Windows). Add:

provider add modelsok --type openai-compat \
  --base-url "https://modelsok.com/v1" \
  --api-key "$MODELSOK_API_KEY"

model add modelsok/claude-sonnet-4-6 \
  --name "Claude Sonnet 4.6" \
  --context-window 200000 \
  --default-max-tokens 32768 \
  --can-reason

model add modelsok/gpt-5.4-mini \
  --name "GPT-5.4 Mini" \
  --context-window 128000 \
  --default-max-tokens 16384

Command / flag	Purpose
`provider add <id> --type openai-compat`	Declares an OpenAI-compatible provider; `<id>` is your own name for it
`--base-url`	The base URL, must end with `/v1`
`--api-key`	References an environment variable, avoiding a hardcoded key in the file
`model add <provider>/<model>`	Registers a model under the provider; `<model>` must match the Models Hub console
`--can-reason`	Marks the model as reasoning-capable; omit for non-reasoning models

Then set the environment variable:

Linux / macOS

export MODELSOK_API_KEY="your-models-hub-api-key"

Windows (PowerShell)

$env:MODELSOK_API_KEY="your-models-hub-api-key"

Add it to your shell config to make it persistent.

Verify

Run crush in a project directory, press Ctrl+L to open the model picker, choose a model under the modelsok provider, and send a test message. A normal reply means you're connected. Then open Usage logs in the Models Hub console; a request under your configured model name appears within seconds.

Common errors

Symptom	Cause	Fix
modelsok doesn't appear in the model picker	The `crushrc` path is wrong, or there's a script syntax error	Confirm the file path, then reopen Crush
`401 Unauthorized`	`MODELSOK_API_KEY` isn't exported in the current shell	Check the environment variable, reopen the terminal, and retry
Model not found	The model name in `model add` doesn't match the Models Hub console	Check the name on the pricing page
Changes to the config don't take effect	Crush reads `crushrc` once at startup	Quit Crush and restart
A reasoning model behaves oddly	You forgot to add `--can-reason` for it	Rerun `model add` with that flag included

FAQ

How is it billed? Per input and output token actually consumed, at the price on each model's pricing page; every request is itemized in usage logs.

How is this different from using the official APIs directly? Crush only speaks the OpenAI-compatible protocol; the Models Hub gateway forwards your request to the model you specify, so you don't need a separate account with each vendor.

How do I switch models? Press Ctrl+L or type /model inside Crush to open the picker — every registered model is listed. Run model add again to register a new one.

CLI one-command setup: Claude Code, Codex, Gemini CLI and OpenClaw support one-click configuration
Model pricing and model status
OpenCode setup, Pi setup