Getting started

Installation

One command, no install wizard, no account. The bwhale launcher fetches the runtime once and starts the app in your browser.

Requirements

Requirement	Details
Node.js	`>= 20` — needed by the launcher only. The app ships its own runtime Node, so any recent Node works.
Operating system	macOS (Apple silicon + Intel), Linux (x64 + arm64), Windows x64.
git	Required — it powers session history. Ships with the macOS developer tools and most Linux distros; on Windows, `winget install Git.Git`.
Python	Used for office-file creation. macOS ships it with the dev tools; Linux needs `python3`; Windows needs Python 3.12 from `winget`. Office libraries install themselves on first boot.
API key	DeepSeek, OpenRouter, or another compatible provider. See Configuration.
LibreOffice (optional)	Enables pixel-perfect file previews and formula recalculation — installable manually or through the in-app one-time setup. See Previews.

Install and run

bash

npm i -g @haifai/bwhale
bwhale

First run fetches the runtime once (about 400 MB, from the project's GitHub Releases) into ~/.bwhale, checks your platform's prerequisites, and opens http://127.0.0.1:24680 in your browser. Office libraries install themselves on first boot. Later runs start instantly.

✓

Not sure about your machine? Run bwhale doctor — it reports exactly what's present, what's missing, and the platform-native command to fix it.

First launch

Choose a workspace. Pick or create a local folder — this is where uploads and finished files live.
Pick Coworker mode. It loads the office skills and tools this documentation covers.
Add your API key. If you haven't yet, the app will prompt you — see Configuration & API keys.
Give it something to do. Try the bundled demo: a messy spreadsheet and a walkthrough live in examples/whale-demo in the repository.

Commands

Command	What it does
`bwhale`	Start the app (first run installs the runtime).
`bwhale --no-open`	Start without opening the browser — useful over SSH.
`bwhale doctor`	Report what's present / missing on your machine.
`bwhale update`	Refresh to the latest release on next start.
`bwhale stop`	Stop a running server. Closing the browser tab doesn't stop it — `bwhale --stop` works too.
`bwhale --version`	Report the installed runtime version.
`bwhale --port 8080`	Dash-flags like `--port` and `--host` forward to the app — handy when 24680 is taken. (`--host 0.0.0.0` isn't supported yet.)

Where things live

~/.bwhale — the app runtime, fetched on first run (override with the BWHALE_HOME environment variable).
~/.dsh/ — configuration, including .credentials.yaml for your API key.
Your workspace folder — per-session subfolders with uploads/, scripts/, and deliverables/.
Baby Whale's Python environment — created on first office use, so installs never touch your system Python.

Next: connect your provider →