Skip to main content

Connect Crush with Zeldoc.ai

Crush is Charm's open source, terminal-first coding agent. It supports custom OpenAI-compatible providers through a small config file called crushrc, so Zeldoc.ai drops in with a handful of lines.

Prerequisites​

Add Zeldoc.ai to your crushrc​

A crushrc is a Bash script with Crush-specific commands. The global one lives at ~/.config/crush/crushrc (on Windows, %USERPROFILE%\.config\crush\crushrc); a .crushrc in a project directory takes precedence. Add the following:

# Zeldoc.ai as an OpenAI-compatible provider. The key is read from the environment.
provider add zeldoc --type openai-compat \
  --name "Zeldoc.ai" \
  --base-url "https://api.zeldoc.ai/v1" \
  --api-key "$ZELDOC_API_KEY"

# ZDev, with its limits and capabilities.
model add zeldoc/zdev \
  --name "ZDev" \
  --context-window 1000000 \
  --default-max-tokens 131072 \
  --can-reason true \
  --supports-images true

# Use ZDev for both of Crush's model slots, with thinking on.
model large zeldoc/zdev --think --reasoning-effort high
model small zeldoc/zdev

Crush uses the large model for the main agent and the small model for lightweight work such as titles and summaries. Pointing both at ZDev keeps everything on Zeldoc.ai.

Then set the environment variable before starting Crush:

export ZELDOC_API_KEY=your-api-key
Persist the environment variable

Add the export line to your shell profile (e.g. ~/.bashrc or ~/.zshrc) so the key is available in every new terminal session.

openai-compat, not openai

Crush has two OpenAI provider types. openai is for requests that go to OpenAI itself; openai-compat is for other providers that speak the OpenAI API, which is what Zeldoc.ai needs.

Verify the connection​

Run a one-off prompt from the terminal:

crush run "Reply with the single word OK."

A reply from the model confirms Zeldoc.ai is connected. You can also list the models Crush knows about:

crush models zdev

Inside an interactive Crush session, press ctrl+l to open the model picker and switch between models.

Use other Zeldoc.ai models​

Register more models with additional model add lines, using the model ID exactly as Zeldoc.ai reports it — see list your available models:

model add zeldoc/zdev-2 \
  --name "ZDev 2" \
  --context-window 1000000 \
  --default-max-tokens 131072 \
  --can-reason true \
  --supports-images true

Discover the whole catalog​

Instead of listing models by hand, let Crush fetch everything your key can access by adding --discover-models true to the provider:

provider add zeldoc --type openai-compat \
  --name "Zeldoc.ai" \
  --base-url "https://api.zeldoc.ai/v1" \
  --api-key "$ZELDOC_API_KEY" \
  --discover-models true

Discovered models are merged with the ones you declared, and your explicit settings win on conflicts. Keep the model add zeldoc/zdev block so ZDev has the right context window and capabilities; discovery can't read those from the API.

Discovery lists everything

Zeldoc.ai's catalog includes image, audio, and embedding models, and discovery shows them too. They aren't usable as an agent model, so pick chat models in the model picker.

Two crushrc options are worth setting when you use Crush with Zeldoc.ai:

# Hide Crush's built-in providers so you don't accidentally pick another one.
option default-providers false

# Don't send anonymous usage metrics to Charm.
option metrics false
  • default-providers false removes the built-in provider list from the model picker, leaving only the providers you declared. Turn it back on if you use other providers alongside Zeldoc.ai.
  • metrics false turns off Crush's pseudonymous usage metrics. Crush never sends prompts or responses, but if you'd rather send nothing at all, this is the switch. Setting CRUSH_DISABLE_METRICS=1 or DO_NOT_TRACK=1 in your environment does the same.