Skip to content

INSTALL.md

Latest commit

 

History

History
637 lines (473 loc) · 22.7 KB

INSTALL.md

File metadata and controls

637 lines (473 loc) · 22.7 KB

Installing CodeWhale

This page covers every supported install path and the most common "it didn't install" failures, including Linux ARM64 and other less common platforms.

If you just want the short version, see the main README or 简体中文 README.

1. Supported platforms

codewhale-tui ships prebuilt binaries for these platform/architecture combinations from v0.8.8 onward:

Platform Architecture npm install cargo install GitHub release asset
Linux x64 (x86_64) ✅ ✅ codewhale-linux-x64, codewhale-tui-linux-x64
Linux arm64 ✅ ✅ codewhale-linux-arm64, codewhale-tui-linux-arm64
macOS x64 ✅ ✅ codewhale-macos-x64, codewhale-tui-macos-x64
macOS arm64 (M-series) ✅ ✅ codewhale-macos-arm64, codewhale-tui-macos-arm64
Windows x64 ✅ ✅ codewhale-windows-x64.exe, codewhale-tui-windows-x64.exe
Other Linux (musl, riscv64, …) — ❌¹ ✅² build from source
FreeBSD / OpenBSD — ❌ ✅² build from source

¹ The npm package will exit with a clear error and point you here. ² Provided your toolchain can compile a recent Rust workspace; see Build from source below.

The Linux release assets are glibc builds, not musl builds. They dynamically link normal Linux runtime libraries such as libdbus-1 and libc; SQLite is currently bundled into the binary through rusqlite so users do not need a separate libsqlite3 runtime package for official release assets. Musl-based systems such as Alpine should use Build from source.

Linux ARM64 note (v0.8.7 and earlier). v0.8.7 and earlier do not publish a Linux ARM64 prebuilt; users on HarmonyOS thin-and-light, Asahi Linux, Raspberry Pi, AWS Graviton, etc. saw Unsupported architecture: arm64 from npm i -g codewhale. v0.8.8 publishes both codewhale-linux-arm64 and codewhale-tui-linux-arm64, so a plain npm i -g codewhale works on any glibc-based ARM64 Linux. If you're stuck on v0.8.7, jump to Build from source — cargo install works fine.

2. Download safety and checksums

Official release binaries are published only from https://github.com/Hmbown/CodeWhale/releases and the npm package named codewhale-tui. Do not install release assets from look-alike repositories, archives, or search-result mirrors unless you deliberately trust that mirror.

Every GitHub release includes codewhale-artifacts-sha256.txt. If you download binaries manually, verify them before running:

# Run from the directory containing the downloaded binaries.
curl -L -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing

On macOS, use shasum -a 256 -c codewhale-artifacts-sha256.txt instead of sha256sum.

If antivirus software flags an official release binary, treat it as unresolved until the exact artifact is identified. Please include all of the following in the GitHub issue:

  • the release tag, for example v0.8.36
  • the exact download URL
  • the filename, for example codewhale-linux-x64
  • the file SHA-256 from your machine
  • the antivirus product name and detection name

That lets maintainers distinguish a false positive on an official artifact from a download sourced from an impersonating repository or mirror.

3. Install via npm (recommended)

npm install -g codewhale
codewhale

postinstall downloads the right pair of binaries from the matching GitHub release, verifies a SHA-256 manifest, and exposes both codewhale and codewhale-tui on your PATH.

Useful environment variables:

Variable Purpose
DEEPSEEK_TUI_VERSION Pin which release the wrapper downloads (defaults to deepseekBinaryVersion)
DEEPSEEK_TUI_GITHUB_REPO Point the downloader at a fork (owner/repo)
DEEPSEEK_TUI_RELEASE_BASE_URL Override the download root (e.g. an internal mirror or release-asset proxy)
DEEPSEEK_TUI_FORCE_DOWNLOAD=1 Re-download even if a cached binary marker matches
DEEPSEEK_TUI_DISABLE_INSTALL=1 Skip the postinstall download entirely (CI smoke, vendored binaries)
DEEPSEEK_TUI_OPTIONAL_INSTALL=1 Don't fail npm install on download/extract errors — useful in CI matrices

Slow npm download from mainland China? If npm install itself is slow (not just the postinstall binary download), use an npm registry mirror:

npm config set registry https://registry.npmmirror.com
npm install -g codewhale

See also Section 4 if you prefer Cargo over npm.

4. Install via Cargo (any Tier-1 Rust target)

If GitHub releases are slow, blocked, or you're on an unsupported architecture, install from crates.io directly. Both crates are required — the dispatcher delegates to the TUI runtime at runtime.

# Requires Rust 1.88+ (https://rustup.rs)
cargo install codewhale-cli --locked   # provides `codewhale`
cargo install codewhale-tui     --locked   # provides `codewhale-tui`
codewhale --version

China / mirror-friendly install

When installing from mainland China, configure mirrors for both rustup (the Rust toolchain installer) and Cargo (the package registry) to avoid TLS timeouts and download failures.

Step 1: Install Rust via a rustup mirror

# PowerShell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
(New-Object Net.WebClient).DownloadFile('https://win.rustup.rs/x86_64', 'rustup-init.exe')

# git-bash / msys2
export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
./rustup-init.exe -y --default-toolchain stable

# Linux / macOS
export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable

If the TUNA mirror is slow from your network, rsproxy.cn is another rustup mirror option for Linux/macOS:

export RUSTUP_DIST_SERVER=https://rsproxy.cn
export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain stable

The RUSTUP_DIST_SERVER and RUSTUP_UPDATE_ROOT environment variables must be set before running rustup-init; the toolchain download otherwise hits the same TLS handshake problem as the installer.

Step 2: Configure Cargo registry mirror

# ~/.cargo/config.toml
[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

rsproxy, Tencent COS, and Aliyun OSS mirrors work the same way; pick whichever is fastest from your network.

Tencent Cloud remote-first setup

For an always-on workspace that can be controlled from a phone, use the Tencent-native path instead of treating install as a single laptop step:

  • CNB mirror/source: https://cnb.cool/codewhale.net/codewhale.git
  • Tencent Lighthouse HK: /opt/whalebro remote workspace
  • Feishu/Lark: long-connection phone bridge
  • EdgeOne: optional public HTTPS edge for docs/status/webhook surfaces

Start with Tencent Cloud Remote-First Quickstart, then follow Tencent Lighthouse Hong Kong Phone Setup.

5. Install via Nix

Try it

If you already have Nix with flake support, run:

nix run github:Hmbown/CodeWhale

Nix builds codewhale-tui and then starts the codewhale dispatcher. Pass arguments after --, for example:

nix run github:Hmbown/CodeWhale -- --help

Flake

Add inputs to flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    codewhale-tui.url = "github:Hmbown/CodeWhale";
    codewhale-tui.inputs.nixpkgs.follows = "nixpkgs";
  };
}

Install into a NixOS module:

{
  outputs = { self, nixpkgs, codewhale-tui }:
  let
    # replace system "x86_64-linux" with your system
    system = "x86_64-linux";
  in
  {
    # change `yourhostname` to your actual hostname
    nixosConfigurations.yourhostname = nixpkgs.lib.nixosSystem {
      inherit system;
      modules = [
        # ...
        {
          environment.systemPackages = [ codewhale-tui.packages.${system}.default ];
        }
      ];
    };
  };
}

6. Manual download from GitHub Releases

Grab the matching pair of binaries for your platform from the Releases page and drop them side by side into a directory on your PATH (e.g. ~/.local/bin):

# Linux ARM64 example
mkdir -p ~/.local/bin
curl -L -o ~/.local/bin/codewhale      \
    https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-linux-arm64
curl -L -o ~/.local/bin/codewhale-tui  \
    https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-tui-linux-arm64
chmod +x ~/.local/bin/codewhale ~/.local/bin/codewhale-tui
codewhale --version

Verify integrity against the per-release SHA-256 manifest:

curl -L -o /tmp/codewhale-artifacts-sha256.txt \
    https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
( cd ~/.local/bin && sha256sum -c /tmp/codewhale-artifacts-sha256.txt --ignore-missing )

(Use shasum -a 256 -c instead of sha256sum on macOS.)

Windows Scoop

The codewhale package is listed in Scoop's main bucket:

scoop update
scoop install codewhale
codewhale --version

Scoop manifests are maintained outside this repository's release workflow and can lag GitHub/npm/Cargo releases. Use npm or manual GitHub release downloads when you need the newest version immediately.

7. Build from source

This is the catch-all for any platform we don't ship — including musl, riscv64, LoongArch, FreeBSD, and pre-2024 ARM64 distros.

Prerequisites

  • Rust 1.88 or later — install with rustup.
  • Linux build-time deps (Debian/Ubuntu/openEuler/Kylin): 
    sudo apt-get install -y build-essential pkg-config libdbus-1-dev
# openEuler / RHEL family:
# sudo dnf install -y gcc make pkgconf-pkg-config dbus-devel
  • A working cmake is not required.

Build and install

git clone https://github.com/Hmbown/CodeWhale.git
cd CodeWhale

cargo install --path crates/cli --locked   # provides `codewhale`
cargo install --path crates/tui --locked   # provides `codewhale-tui`

codewhale --version

Both binaries land in ~/.cargo/bin/ by default; make sure that directory is on your PATH.

Cross-compiling from x64 to ARM64 Linux

If you want to build an ARM64 Linux binary on an x64 Linux host (e.g. for a HarmonyOS / openEuler ARM64 thin-and-light), use cross, which wraps the official Rust cross-targets in a Docker container:

# Once
rustup target add aarch64-unknown-linux-gnu
cargo install cross --locked

# Per build
cross build --release --target aarch64-unknown-linux-gnu -p codewhale-cli
cross build --release --target aarch64-unknown-linux-gnu -p codewhale-tui

The resulting binaries land in target/aarch64-unknown-linux-gnu/release/codewhale and target/aarch64-unknown-linux-gnu/release/codewhale-tui. Copy the matched pair to the ARM64 host (e.g. via scp) and chmod +x them.

If you don't have Docker available, install the cross-linker directly and let Cargo do the work:

sudo apt-get install -y gcc-aarch64-linux-gnu
rustup target add aarch64-unknown-linux-gnu

cat >> ~/.cargo/config.toml <<'EOF'
[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"
EOF

cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-cli
cargo build --release --target aarch64-unknown-linux-gnu -p codewhale-tui

The same recipe works for aarch64-unknown-linux-musl if your distro is musl-based.

Windows build from source

Building on Windows requires the MSVC C toolchain from Visual Studio Build Tools (the free workload-selectable installer, not the full IDE).

Prerequisites (Windows)

  1. Install Visual Studio 2022 Build Tools — select the "Desktop development with C++" workload.
  2. Install Rust 1.88+ (see the China mirror instructions above if downloading from mainland China).
  3. Install Git for Windows (provides git and the git-bash terminal).

Recommended terminals: Windows Terminal, git-bash, or PowerShell. cmd.exe works but has a small buffer and limited PATH behavior.

Setting up the MSVC environment

Visual Studio Build Tools install cl.exe to a versioned directory but do not add it to PATH globally. You must set the environment manually or use a Developer Command Prompt. The required variables are:

# Adjust version numbers to match your installation
$msvc = "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207"
$sdk   = "C:\Program Files (x86)\Windows Kits\10"
$sdkv  = "10.0.26100.0"

$env:INCLUDE  = "$msvc\include;$msvc\atlmfc\include;$sdk\Include\$sdkv\ucrt;$sdk\Include\$sdkv\um;$sdk\Include\$sdkv\shared"
$env:LIB      = "$msvc\lib\x64;$msvc\atlmfc\lib\x64;$sdk\Lib\$sdkv\ucrt\x64;$sdk\Lib\$sdkv\um\x64"
$env:LIBPATH  = "$msvc\lib\x64;$msvc\atlmfc\lib\x64"
$env:CC       = "$msvc\bin\Hostx64\x64\cl.exe"
$env:CXX      = "$msvc\bin\Hostx64\x64\cl.exe"
$env:PATH     = "$msvc\bin\Hostx64\x64;$env:PATH"

Alternatively, open a "Developer Command Prompt for VS 2022" (available from the Start Menu after installing Build Tools), which runs vcvars64.bat to configure all of the above automatically. Then add cargo to PATH inside that session and run cargo build from the project root.

Cargo registry mirror — on Windows the mirror config goes to %USERPROFILE%\.cargo\config.toml. See Step 2 above.

Build

git clone https://github.com/Hmbown/CodeWhale.git
cd CodeWhale
set CARGO_HTTP_CHECK_REVOKE=false   # may be needed behind some Chinese ISPs
cargo build --release

Both binaries appear in target\release\codewhale.exe and target\release\codewhale-tui.exe.

Prefer npm install -g on Windows unless you need to modify source. The npm package pulls prebuilt binaries and avoids the C toolchain dependency entirely — see Section 3.

8. Troubleshooting

Unsupported architecture: arm64 on platform linux

You're on a release earlier than v0.8.8 that doesn't publish Linux ARM64 binaries. Either upgrade (npm i -g codewhale@latest) or use cargo install per Section 4.

MISSING_COMPANION_BINARY at runtime

The dispatcher (codewhale) requires the TUI runtime (codewhale-tui) to be on the same PATH. If you installed only one crate via cargo install, install both:

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

codewhale update reports no asset found for platform codewhale-linux-aarch64

This is #503 in v0.8.7 — the self-updater used Rust's aarch64/x86_64 arch names instead of the release artifact's arm64/x64. Workaround until v0.8.8:

npm i -g codewhale@latest
# or
cargo install codewhale-cli --locked

npm download is slow or times out from mainland China

Set DEEPSEEK_TUI_RELEASE_BASE_URL to a mirrored release-asset directory (rsproxy, TUNA, Tencent COS, Aliyun OSS), or skip npm entirely and use the Cargo mirror setup in Section 4.

codewhale update is blocked by GitHub from mainland China

codewhale update normally contacts GitHub Releases for metadata and binary assets. On networks where GitHub is blocked or unreliable, use the CNB source mirror instead and install both binaries from the release tag:

cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-cli --locked --force
cargo install --git https://cnb.cool/codewhale.net/codewhale --tag vX.Y.Z codewhale-tui     --locked --force

If you operate a binary asset mirror, codewhale update can use it directly:

DEEPSEEK_TUI_VERSION=X.Y.Z \
DEEPSEEK_TUI_RELEASE_BASE_URL=https://your-mirror.example.com/DeepSeek-TUI/vX.Y.Z/ \
codewhale update

The mirror directory must contain codewhale-artifacts-sha256.txt and the platform binaries from the GitHub release.

Debian/Ubuntu: feature edition2024 is required from cargo install

Some Debian/Ubuntu distro packages ship an older Cargo that cannot parse Rust 2024 crates. For example, Cargo 1.75.0 on Ubuntu 24.04 fails before building with:

feature `edition2024` is required
The package requires the Cargo feature called `edition2024`, but that feature
is not stabilized in this version of Cargo

Install current stable Rust through rustup, then rerun the two Cargo install commands from Section 4. For mainland China networks, this rsproxy-based sequence has been verified to work:

export RUSTUP_DIST_SERVER=https://rsproxy.cn
export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup default stable
cargo install codewhale-cli --locked
cargo install codewhale-tui     --locked

Afterward, which cargo should point to ~/.cargo/bin/cargo, not /usr/bin/cargo.

Debian/Ubuntu: error: linker 'cc' not found while building

Install the C toolchain:

sudo apt-get install -y build-essential pkg-config libdbus-1-dev

Wrapper installs but codewhale isn't found

npm i -g installs into $(npm prefix -g)/bin; make sure that directory is on your shell's PATH. With nvm: nvm use --lts && hash -r.

Windows: TLS handshake eof or CRYPT_E_REVOCATION_OFFLINE from rustup-init

The TLS handshake to static.rust-lang.org fails from behind the GFW or certain Chinese ISPs. Set the rustup mirror environment variables before running the installer:

# git-bash / msys2
export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
./rustup-init.exe -y --default-toolchain stable

If you see CRYPT_E_REVOCATION_OFFLINE from Cargo after Rust is installed, also set CARGO_HTTP_CHECK_REVOKE=false during cargo build.

Windows: MSVC compiler (cl.exe) not found during cargo build

Visual Studio Build Tools do not add cl.exe to the global PATH. Either:

  1. Open "Developer Command Prompt for VS 2022" from the Start Menu, add %USERPROFILE%\.cargo\bin to PATH in that window, and run cargo build from there; or
  2. Set the MSVC environment variables manually — see the Windows build from source section for the PowerShell snippet.

Verify the compiler is reachable: cl.exe /? should print help text.

Windows: 拒绝访问 (os error 5) when Cargo executes build scripts

Third-party antivirus software (Huorong, 360, Kaspersky, etc.) may block Cargo from executing freshly-compiled build-script binaries (e.g. libsqlite3-sys, aws-lc-sys, instability). The error is path-agnostic — moving target-dir does not help.

Symptoms: could not execute process ... build-script-build (never executed)

Workarounds (pick one):

  1. Add the project's target/ directory to your AV exclusions list.
  2. Close the antivirus software temporarily during cargo build.
  3. Use npm install -g codewhale instead — the npm package ships prebuilt binaries and skips the Cargo build entirely (Section 3).
  4. Use cargo install codewhale-cli --locked from crates.io — this changes the binary path, which some AV tools treat differently.

To verify that the build-script binary itself is valid (not corrupted), locate it under target/debug/build/<crate>/build-script-build and run it manually:

target/debug/build/libsqlite3-sys-*/build-script-build
# If this runs but panics with "NotPresent" (no C compiler), the binary is
# fine — the AV is blocking Cargo's process-spawning path specifically.

npm binary download times out

If codewhale waits several seconds and prints connect ETIMEDOUT or EAI_AGAIN while fetching from github.com, the npm wrapper installed successfully but the prebuilt binary download from GitHub Releases is blocked or unreliable on your network. This download is separate from the npm registry package download.

Use one of these paths:

  1. Set a proxy and retry:

    export HTTPS_PROXY=http://your-proxy:port
codewhale

  2. Mirror the release assets internally and set DEEPSEEK_TUI_RELEASE_BASE_URL:

    export DEEPSEEK_TUI_RELEASE_BASE_URL=https://your-mirror.example.com/DeepSeek-TUI/
codewhale

    The directory must contain codewhale-artifacts-sha256.txt and the platform binaries from the GitHub release.

  3. Install via Cargo, which builds locally and does not download GitHub release assets. See Section 4.

  4. Download both codewhale and codewhale-tui manually from the Releases page, place them in a directory on PATH, and make them executable. See Section 6.

9. Verifying your install

codewhale --version
codewhale doctor       # checks API key, provider, runtime, and PATH integrity
codewhale doctor --json

doctor exits non-zero if it finds a problem and prints structured remediation hints. Paste the JSON output into a GitHub issue if you need help.