How to Use a Mirror for CodeWhale Release Assets During Installation

Set the DEEPSEEK_TUI_RELEASE_BASE_URL environment variable to your mirror’s base URL before running npm install or codewhale to redirect binary downloads away from GitHub Releases.

CodeWhale is distributed through npm as a wrapper package, but the actual pre-built binaries (codewhale and codewhale-tui) are fetched separately from GitHub Releases during the post-install phase. When direct access to GitHub is restricted by firewalls or network latency causes timeouts, configuring a mirror for CodeWhale release assets ensures reliable installation across mainland China, corporate networks, and restricted environments.

Why Use a Mirror for CodeWhale Binary Downloads?

The npm package installs quickly from the registry, but the install script in npm/codewhale/scripts/install.js initiates a secondary download for platform-specific binaries. In docs/INSTALL.md, the documentation notes that users frequently encounter ETIMEDOUT or EAI_AGAIN errors when the installer attempts to reach github.com directly. By hosting a mirror of the release assets and pointing the installer to it with an environment variable, you bypass these network constraints entirely.

Setting Up the CodeWhale Release Mirror

Hosting Requirements for the Mirror

Your mirror server must replicate the exact directory structure of a GitHub Release. Specifically, the mirror directory must contain:

• Platform-specific binary archives (e.g., codewhale-linux-x64.tar.gz, codewhale-macos-arm64.zip)
• The checksum file codewhale-artifacts-sha256.txt for integrity verification
• The same file naming conventions used in the official Hmbown/CodeWhale releases

Configuring the Environment Variable

The installer checks for DEEPSEEK_TUI_RELEASE_BASE_URL at runtime. When set, the logic in npm/codewhale/scripts/install.js (lines 95-104) substitutes the GitHub Releases base URL with your custom mirror path.

Set the variable to the base directory containing the release assets:

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

Once exported, both initial installations and subsequent codewhale update operations will pull binaries from this location.

Environment Variables for CodeWhale Installation

CodeWhale’s npm wrapper recognizes three environment variables that control binary acquisition:

• DEEPSEEK_TUI_RELEASE_BASE_URL — Overrides the default GitHub Releases URL with your mirror address. Required for offline or restricted-network installations.
• DEEPSEEK_TUI_FORCE_DOWNLOAD=1 — Forces the installer to re-download binaries even if a cached version exists locally.
• DEEPSEEK_TUI_DISABLE_INSTALL=1 — Skips the post-install binary download entirely. Useful for CI pipelines where binaries are pre-cached or managed separately.

Reference npm/codewhale/scripts/install.js to see how these variables are parsed and prioritized during the installation lifecycle.

Practical Installation Examples

Permanent Mirror Configuration

Add the export to your shell profile for persistent usage:

# Add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile

export DEEPSEEK_TUI_RELEASE_BASE_URL=https://my-mirror.local/DeepSeek-TUI/

# Install CodeWhale globally

npm install -g codewhale

# Verify binary sourcing

codewhale --version

Temporary Mirror Usage

Test a mirror without modifying shell configuration by prefixing the command:

DEEPSEEK_TUI_RELEASE_BASE_URL=https://mirror.local/DeepSeek-TUI/ npm install -g codewhale

Or run the CLI directly with the variable:

DEEPSEEK_TUI_RELEASE_BASE_URL=https://mirror.local/DeepSeek-TUI/ codewhale

CI/CD Implementation

For automated pipelines where you want to skip downloads or force fresh binaries:

# Skip binary download (binaries pre-cached in image)

DEEPSEEK_TUI_DISABLE_INSTALL=1 npm ci

# Or force fresh download from mirror

DEEPSEEK_TUI_RELEASE_BASE_URL=https://internal-mirror.org/releases/ \
DEEPSEEK_TUI_FORCE_DOWNLOAD=1 \
npm install -g codewhale

Troubleshooting Mirror Configuration

If the mirror is unreachable or missing required files, the installer prints a diagnostic hint showing the current value of DEEPSEEK_TUI_RELEASE_BASE_URL and reminds you to verify that codewhale-artifacts-sha256.txt and the platform binaries exist at that path. This behavior is implemented in npm/codewhale/scripts/install.js (lines 95-104).

Ensure your mirror URL ends with a trailing slash and that the directory structure mirrors the official GitHub Release assets exactly. Check .env.example in the repository root for a template showing optional configuration patterns.

Summary

• Set DEEPSEEK_TUI_RELEASE_BASE_URL to redirect binary downloads from GitHub to your internal or regional mirror.
• Mirror requirements: Host the exact release directory structure including codewhale-artifacts-sha256.txt and platform-specific archives.
• Applies to all operations: The variable affects initial npm install and future codewhale update commands.
• Additional controls: Use DEEPSEEK_TUI_FORCE_DOWNLOAD to bypass cache or DEEPSEEK_TUI_DISABLE_INSTALL to skip downloads in CI environments.
• Source locations: Logic resides in npm/codewhale/scripts/install.js; documentation is in docs/INSTALL.md.

Frequently Asked Questions

How do I know if CodeWhale is downloading from my mirror and not GitHub?

Run the installation with the environment variable set and check the console output. If the mirror is unreachable or files are missing, the error message from npm/codewhale/scripts/install.js will display the current value of DEEPSEEK_TUI_RELEASE_BASE_URL, confirming which base URL is active.

What files must I include in my CodeWhale mirror?

You must host all platform-specific binaries (e.g., codewhale-linux-x64.tar.gz, codewhale-win32-x64.zip) and the codewhale-artifacts-sha256.txt checksum file. The installer validates downloads against this checksum, so omitting it will cause installation failures.

Does the mirror setting persist after installation?

Yes. The DEEPSEEK_TUI_RELEASE_BASE_URL variable is checked by the codewhale update command, so any future upgrades will also pull from your configured mirror. Set this variable in your shell profile to make the configuration permanent.

Can I install CodeWhale without downloading any binaries?

Yes. Set DEEPSEEK_TUI_DISABLE_INSTALL=1 before running npm install. This skips the post-install binary download entirely, allowing you to manually place binaries or manage them through a separate configuration management system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}