Skip to content

docs: document OrcaRouter as a named provider in the Crush guide #1048

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
putraperdana1207-pixel wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document OrcaRouter as a named provider in the Crush guide #1048

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions packages/varlock-website/src/content/docs/guides/ai-tools/crush.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,41 @@ For install, schema setup, and shared patterns, see the [AI Tools overview](/gui

You can also paste a key in the TUI model picker (`ctrl+l`). Prefer env injection so the key is not typed into the UI or stored in project config.

## OrcaRouter

[OrcaRouter](https://www.orcarouter.ai) is an OpenAI-compatible AI gateway that exposes many models behind one endpoint, with adaptive routing, automatic failover, zero-markup inference, observability, and guardrails. It works with Crush as a custom `openai-compat` provider, so Crush's model calls can route through OrcaRouter without treating it as an anonymous custom base URL.

Add the provider to `~/.config/crush/crush.json` and reference an env var for the key:

```json title="~/.config/crush/crush.json"
{
"providers": {
"orcarouter": {
"type": "openai-compat",
"base_url": "https://api.orcarouter.ai/v1",
"api_key": "$ORCAROUTER_API_KEY",
"models": [

@pullfrog pullfrog Bot Aug 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This explicit model entry is incomplete under Crush's current JSON schema: models also require pricing, context-window, token-limit, reasoning, and attachment fields, so users copying this example will not get a valid model configuration. Please switch the example to the current crushrc commands (model discovery can avoid hard-coding those fields), or supply a schema-complete legacy model.

Technical details 
# Use a valid current Crush configuration

## Affected sites
- `packages/varlock-website/src/content/docs/guides/ai-tools/crush.mdx:27` - recommends the deprecated `~/.config/crush/crush.json` format
- `packages/varlock-website/src/content/docs/guides/ai-tools/crush.mdx:34` - starts an explicit model object that omits required fields

## Required outcome
- Give readers a configuration accepted by current Crush while retaining `$ORCAROUTER_API_KEY`, `https://api.orcarouter.ai/v1`, and access to `orcarouter/auto`.

## Suggested approach
- Use `~/.config/crush/crushrc` with `provider add orcarouter --type openai-compat --base-url "https://api.orcarouter.ai/v1" --api-key "$ORCAROUTER_API_KEY"`; current Crush discovers models for an `openai-compat` provider when no explicit model list is supplied.
- Upstream references: https://github.com/charmbracelet/crush/blob/main/docs/config/README.md and https://github.com/charmbracelet/crush/blob/main/schema.json

{
"id": "orcarouter/auto",
"name": "OrcaRouter Auto"
}
]
}
}
}
```

Then declare the key in your schema and run Crush through varlock:

```env-spec
# @sensitive
ORCAROUTER_API_KEY=op(op://api-local/orcarouter/api-key)
```

```bash
varlock run -- crush
```

## In a project

Add to `.env.schema`:
Expand Down