/

Getting started

Configuration & API keys

Baby Whale doesn't proxy your model traffic. You bring a key from your provider, and requests go from your machine to the provider you chose.

The easy way: in-app setup

Open Settings → Providers in the Web UI, pick your provider, and paste your key. The app writes the credentials file for you — this is the recommended path, because it keeps the file's format valid.

The file: credentials.yaml

Keys live in ~/.dsh/.credentials.yaml. The file is YAML, and YAML is indentation-sensitive:

~/.dsh/.credentials.yaml
version: 1
refs:
  DEEPSEEK_API_KEY: "sk-your-key-here"

Then lock it down:

bash
chmod 600 ~/.dsh/.credentials.yaml
⚠

The permissions aren't optional. The app refuses to start if the credentials file is readable by group or others — it tells you itself: run "chmod 600 ~/.dsh/.credentials.yaml". And the most common boot failure after hand-editing is a YAML indent error: two spaces per level, no tabs, quotes around the key.

Supported providers

Any provider with a compatible API works. The common ones:

  • DeepSeek — keys from platform.deepseek.com.
  • OpenRouter — one key, many models behind it.
  • Other OpenAI-compatible endpoints — point the base URL at your provider in Settings → Providers.

Each provider uses its own ref name in the credentials file (the DeepSeek one is DEEPSEEK_API_KEY) — the in-app setup writes the right one for you. Provider support expands with the harness; check Settings for the current list.

Choosing a model

The model selector sits in the composer, next to the send button. Sessions are cheap to start — pick a stronger model for planning-heavy office work and a faster one for quick edits. Different sessions can use different models.

Permission modes

The composer also shows the permission mode — for example Workspace Write. It controls how much Baby Whale may do without asking:

  • Read-only — it can look, but every write needs confirmation.
  • Workspace Write — it may create and edit files inside the session workspace without asking each time. This is the normal office-work mode.

Actions outside the workspace, or sensitive operations, always require explicit confirmation regardless of mode.

ⓘ

Your key, your account. API usage is billed by your provider under your account. Baby Whale never sees a bill and never stores your key anywhere except the local credentials file.