# Codewhale pipes a remote script into your shell and picks your model for you

> Codewhale is a Rust agent harness that reads a project, edits files, runs commands, and works through a hosted or local model you select. Two things in the install and first-run path are worth reading before you type anything: macOS and Linux install by piping a remote script into a shell while Windows has no equivalent one-liner, and the first launch goes straight to the composer with no setup wizard.

**Hmbown/CodeWhale** — Open-source, community-driven agent harness. Why Codewhale:** **No lock-in.** DeepSeek, Claude, GPT, Kimi, GLM, 30+ providers, and your own vLLM, SGLang, or Ollama, no key required, run through one runtime and one toolset.

- Repository: https://github.com/Hmbown/CodeWhale
- Website: https://codewhale.net/
- Stars: 41,042 · Forks: 3,565
- Language: Rust
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/hmbown-codewhale

## macOS and Linux install by piping a script, Windows does not

The install section opens with the two-line version:

```bash
curl -fsSL https://codewhale.net/install.sh | sh
"$HOME/.local/bin/codewhale"
```

That is a remote script fetched over HTTPS and handed to a shell in one move, for a tool whose whole job is editing files and running commands in your repositories. The file does say the installer selects the latest published release, and it handles the follow-up problem where plain `codewhale` reports command not found because `~/.local/bin` is not yet on your PATH.

Windows gets no equivalent. There, you download a matching installer or archive from GitHub Releases, and for an existing direct install you run `codewhale update`, or `codewhale update --check` to inspect it. The updater prints the executable path and keeps newer builds.

The consequence is that the two platforms get different trust models and the file does not explain the difference. Anyone who pipes remote scripts into a shell as a matter of habit is unconcerned; anyone who does not is stuck on the manual path. Whichever you are, note that the update path exists for direct installs only, and that npm, Cargo, Docker, Nix, Scoop, Android and Termux are all offered as additional routes with migration instructions for existing package-managed installs.

## The first run has no wizard and the launch screen says no model connected

The first run opens straight to the composer. The file is explicit that it does not walk you through setup. Model replies require a connected hosted or local model, and until one is connected the launch screen says no model connected. You add a hosted key or pick a local runtime with `/provider`, or by pressing F3.

Then there is the sentence that changes how you should think about which model answered. If Ollama is already running with a chat model, Codewhale switches to it on its own.

That is convenient and it is also the risk. Which model handled your task is decided partly by ambient state on the machine, not only by the choice you made. A laptop with Ollama up will quietly go local; a workstation with a provider key exported in your shell will go hosted; a machine with neither is the no model connected screen. The file tells you the behaviour exists but does not tell you how to see, after the fact, which one was in use.

The consequence for anyone evaluating the tool is that a first impression depends on what happened to be running already. Pick a model deliberately with `/provider` and `/model` before you judge anything, and do not read a first session as evidence about hosted models if you never connected one.

## The workspace says 0.10.1 while the newest tag is v0.10.0

There are three version numbers in play and the file only explains the relationship between two of them. The workspace package version in Cargo.toml is 0.10.1. The newest published release is v0.10.0, dated 2026-09-22, with v0.9.13 and v0.9.12 before it. The last commit to the repository is 2026-09-29.

The link between the tag and the changelog is spelled out: the changelog also describes the next release's unreleased candidate, and those changes are not included in published downloads until the release is available.

The link between the tag and the manifest is not, and the gap is easy to misread as a mistake. It is not one. The installer hands you the published release, so you get 0.10.0, and anyone building from the branch gets 0.10.1, and the file's own sentence explains why the changelog can be ahead of both.

The consequence is that a bug you cannot reproduce locally is a version-skew question before it is anything else. A support report that omits the version and whether the binary came from the installer or a build is missing the first fact needed to triage it.

## Thirty crates in the workspace, and a root build gives you the CLI

The workspace lists thirty members, twenty-nine of them under crates/ and one under tests/. They span agent, app-server, cli, cloud-facts, command-contract, config, core, execpolicy, hooks, lane, localization, mcp, memory, models, palette, paths, protocol, release, runtime, secrets, state, telemetry, tools, tui, workflow and workflow-js, among others.

What a root build produces is narrower than that. `default-members` is set to a single crate, crates/cli, with resolver 2.

So `cargo build` in the repository root gives you the command line, not the system. The crate most of the documentation is about, crates/runtime, is not a default member, and neither is the tui crate that the interactive interface lives in. The documentation describes clients that connect to the Codewhale Runtime, so the runtime is the thing you want when you are building, and it is the thing a default root build skips.

The toolchain floor is stated as a consequence of a single feature. The manifest pins rust-version to 1.88 and explains that 1.88 stabilized let chains in if and while conditions, which the codebase relies on extensively, and that Cargo enforces the pin so older toolchains get a clear package requires rustc 1.88 error rather than a confusing E0658. A separate workspace lint block denies warnings, recording the policy CI already applies through RUSTFLAGS with -Dwarnings, so member crates opt in and a plain cargo check matches CI.

## A workspace .env takes credentials and ignores every other setting

The example environment file carries a warning that is easy to skim and expensive to get wrong. Shell-exported variables override what is in the file. Codewhale loads only literal credential names for built-in providers from a workspace `.env`. Routing, model and base URL, config and profile, MCP and plugin, sandbox, approval, executable-path and runtime settings are all ignored there, and belong in config.toml, CLI flags or the launching shell instead.

Variable expansion is described as deliberately unsupported, and the file tells you to keep values literal and keep `.env` untracked.

The consequence is a silent failure mode. A developer who pastes a base URL override next to the API key, or who tries to pin the sandbox setting or an approval mode from `.env` because it is the file they already have open, gets no error and no warning. The value is simply not read, and the agent runs with whatever the config file or the shell already said. The reason expansion is off is the same reason: it stops a credential from being assembled out of fragments, which is a sensible design choice that costs you the ability to compose values at all.

## The Docker image refuses to bake keys and pins the state volume

The Dockerfile is annotated at the top with its own build and run lines. Build is a buildx call across two platforms, linux/amd64 and linux/arm64, tagged codewhale:latest. Run passes the key as an environment variable and mounts a named volume at a fixed path:

```
docker buildx build --platform linux/amd64,linux/arm64 -t codewhale:latest .
docker run --rm -it -e DEEPSEEK_API_KEY -v codewhale-home:/home/codewhale/.codewhale codewhale
```

The rule is stated in capitals in the file: API keys must be passed at runtime, never baked into the image. Or you can mount an env file instead with --env-file. The image ships both the `codewhale` and `codew` command names.

The build is a two-stage one starting from a Rust slim bookworm image at a pinned Rust version, with a cross-compiler installed only when the target architecture differs from the build platform.

The consequence is that the container is honest about credentials and opinionated about state. Run it without the variable and you are back to the no model connected screen, inside a container this time. And because the state path is fixed, a second container either shares the first one's session history or needs a different volume name, which the file does not discuss.

## The desktop app and the editor extension both live in other repositories

The client story is split across three places and only one of them is this repository. The terminal client is here, as `codewhale` for the interactive interface and `codewhale exec` for a task from a script or a CI job, plus `codewhale web` for the bundled local web client, all connecting to the Codewhale Runtime.

The desktop app is not. It is a GPUI application, and the file says it is developed in a separate repository and is the direction for the signed-in product client, with the hosted web app at app.codewhale.net to be rebuilt to match it while the marketing, sign-in, billing, legal and download pages stay on the web.

The VS Code extension is not either. It is community-maintained, connects to the local Runtime from a sidebar, and lives at github.com/HengQuWorld/CodeWhale-VSCode with a marketplace listing under a different item name.

The consequence is that two of the three clients people look for first are maintained by other people, on other schedules, with no version compatibility statement in this repository. If the Runtime protocol moves and the extension lags, the file gives you nothing to check against, and the only place that knows is the extension's own repository.

## Conclusion

Adopt Codewhale if you want one runtime across DeepSeek, Claude, GPT, Kimi, GLM, thirty or more hosted providers, and your own Ollama, vLLM or SGLang deployment, and if you are willing to read the authorization order and modes documentation before granting an agent write access to a repository. Do not adopt it if you want a guided first run, because there is no wizard, or if you need the desktop client or the editor extension to ship from the same place, because both live in other repositories under other owners. Before you install, decide how you are going to review the installer, because the macOS and Linux path pipes a remote script into a shell, and the Windows path is a manual download instead. After you install, connect a model explicitly with /provider rather than relying on the automatic Ollama switch, and remember that a workspace build reports 0.10.1 while the newest published release is v0.10.0.

## FAQ

### what is codewhale

It is an open-source, community-driven agent harness written in Rust that reads your project, edits files, runs commands, and checks its work using a hosted or local model you choose. The pitch is no lock-in: DeepSeek, Claude, GPT, Kimi, GLM, thirty or more providers, and your own vLLM, SGLang or Ollama, all through one runtime and one toolset.

### how to install codewhale

On macOS and Linux the file gives one line, `curl -fsSL https://codewhale.net/install.sh | sh`, then tells you to run `"$HOME/.local/bin/codewhale"` and to add `~/.local/bin` to your PATH if the bare command is not found. On Windows you download a matching installer or archive from GitHub Releases, and an existing direct install updates with `codewhale update` or `codewhale update --check`.

### codewhale vscode

The VS Code extension is not part of this repository. It is community-maintained, connects to the local Runtime from a sidebar, and its source is at github.com/HengQuWorld/CodeWhale-VSCode with a listing on the VS Code Marketplace under the item name HengQuWorld.brotherwhale-vscode.

### code whale vs claude code

The file makes no comparison. What it states is that you choose the model, listing Claude alongside DeepSeek, GPT, Kimi, GLM and thirty or more providers, and that you can also run local models through Ollama, vLLM or SGLang, switching provider with `/provider` and model with `/model`.

### Is there a DeepSeek coding agent?

Codewhale is one, and DeepSeek is its default provider. The example environment file lists DEEPSEEK_API_KEY under DeepSeek API as the default provider, alongside NVIDIA NIM keys, an AtlasCloud OpenAI-compatible endpoint, Mistral AI, and a Codewhale account key with the models:infer scope.

## Sources

- [Official documentation](https://codewhale.net/)
- [Official README](https://github.com/Hmbown/CodeWhale#readme)
- [Project repository](https://github.com/Hmbown/CodeWhale)
- [Release notes](https://github.com/Hmbown/CodeWhale/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hmbown-codewhale