CodeWhale

iBefore you start

CodeWhale is installed and available as codewhale in your terminal.
A working Yolo Router endpoint, for example https://api.yolorouter.com.
A Yolo Router API Key generated from the console.
The model ID you want to use, for example deepseek-v4-pro. It must exactly match the model ID in the Yolo Router console and support tool calling and streaming.

Which provider to use

CodeWhale supports two integration paths. The DeepSeek provider path is simpler and recommended for DeepSeek-family models. Use the OpenAI provider path if you need to use non-DeepSeek models (e.g., Gemini, GLM) through Yolo Router.

Both paths use OpenAI-compatible API calls under the hood. The DeepSeek path is tuned for DeepSeek-specific features like reasoning blocks and prefix caching.

Setup

Install CodeWhale

If you haven't installed it yet, the easiest way is via npm:

npm install -g codewhale

Or use Cargo (requires Rust 1.88+):

cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

Verify it works:

codewhale --version

Other install options: Homebrew, Scoop (Windows), direct download from GitHub Releases, or Docker. See the official README for details.

Set environment variables (DeepSeek provider)

This is the recommended path for DeepSeek-family models. CodeWhale reads DEEPSEEK_BASE_URL and DEEPSEEK_API_KEY to route requests through Yolo Router.

export DEEPSEEK_API_KEY="sk-yolo-..."
export DEEPSEEK_BASE_URL="https://api.yolorouter.com"
export DEEPSEEK_MODEL="deepseek-v4-pro"

$env:DEEPSEEK_API_KEY = "sk-yolo-..."
$env:DEEPSEEK_BASE_URL = "https://api.yolorouter.com"
$env:DEEPSEEK_MODEL = "deepseek-v4-pro"

set DEEPSEEK_API_KEY=sk-yolo-...
set DEEPSEEK_BASE_URL=https://api.yolorouter.com
set DEEPSEEK_MODEL=deepseek-v4-pro

Variable reference:

DEEPSEEK_API_KEY: your Yolo Router API Key
DEEPSEEK_BASE_URL: Yolo Router gateway endpoint. CodeWhale appends /beta by default; Yolo Router forwards requests to the upstream model regardless of the path suffix
DEEPSEEK_MODEL: the model ID to use

Optional: use OpenAI provider

If you want to use non-DeepSeek models (e.g., Gemini, GLM), use the OpenAI-compatible provider:

export OPENAI_API_KEY="sk-yolo-..."
export OPENAI_BASE_URL="https://api.yolorouter.com/v1"
export OPENAI_MODEL="gemini-3.5-flash"

$env:OPENAI_API_KEY = "sk-yolo-..."
$env:OPENAI_BASE_URL = "https://api.yolorouter.com/v1"
$env:OPENAI_MODEL = "gemini-3.5-flash"

set OPENAI_API_KEY=sk-yolo-...
set OPENAI_BASE_URL=https://api.yolorouter.com/v1
set OPENAI_MODEL=gemini-3.5-flash

Then launch with --provider openai:

codewhale --provider openai --model gemini-3.5-flash

The OpenAI provider always requires the /v1 suffix in OPENAI_BASE_URL. If you need to use http:// on a trusted LAN, also set DEEPSEEK_ALLOW_INSECURE_HTTP=1.

Optional: save credentials with auth

Instead of environment variables, you can persist credentials to ~/.codewhale/config.toml:

codewhale auth set --provider deepseek --api-key "sk-yolo-..."

You can also set the base URL in ~/.codewhale/config.toml:

[providers.deepseek]
base_url = "https://api.yolorouter.com"
model = "deepseek-v4-pro"

Project-level overrides can be placed in <workspace>/.codewhale/config.toml (except api_key, base_url, and provider).

Do not commit real API keys to your repository.

Run CodeWhale

Launch the interactive TUI:

codewhale --model deepseek-v4-pro

Or run a one-shot prompt:

codewhale --model deepseek-v4-pro "Introduce the model you are using in one sentence"

To use auto mode (CodeWhale picks the model and thinking level per turn):

codewhale --model auto

Verify the connection

If CodeWhale responds normally, the integration is working. You can also run the built-in diagnostics:

codewhale doctor

Or verify that models are reachable:

curl https://api.yolorouter.com/v1/models \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY"

Troubleshooting

401 or auth failure

Check that DEEPSEEK_API_KEY (or OPENAI_API_KEY) is your Yolo Router API Key and has no extra spaces. Run codewhale auth status to see which credential source is active.

Model not found

Check that DEEPSEEK_MODEL (or --model) exactly matches the model ID in the Yolo Router console, and that the model supports tool calling and streaming.

If using the DeepSeek provider, CodeWhale appends /beta to DEEPSEEK_BASE_URL by default (e.g., https://api.yolorouter.com/beta). Yolo Router should forward these requests correctly. If you see 404 errors, try setting DEEPSEEK_BASE_URL to https://api.yolorouter.com/v1 and use the OpenAI provider path instead.

If using the OpenAI provider, check that OPENAI_BASE_URL includes the /v1 suffix: https://api.yolorouter.com/v1.

Reasoning models return 400

CodeWhale natively supports DeepSeek reasoning blocks. Make sure you are using the DeepSeek provider path (not OpenAI) and that DEEPSEEK_MODEL matches the model ID in Yolo Router.

CodeWhale defaults to api.deepseek.com

If you set DEEPSEEK_API_KEY but not DEEPSEEK_BASE_URL, CodeWhale will use the official DeepSeek API. Make sure both variables are set in the same terminal session, or use codewhale auth set and the config file approach.