# CodeWhale First Run Setup: Installation, Authentication, and Verification Guide > Master CodeWhale installation and authentication. Follow this guide to set up, connect your API key, and verify your CodeWhale first run setup for seamless project integration. - Repository: [Hunter Bown/CodeWhale](https://github.com/Hmbown/CodeWhale) - Tags: getting-started - Published: 2026-06-02 --- **Run `npm install -g codewhale`, execute `codewhale` in your project directory to generate `~/.codewhale/config.toml`, set your API key with `codewhale auth set --provider deepseek`, and verify with `codewhale doctor` to complete the first run setup.** CodeWhale is an AI-augmented coding assistant shipped as two binaries—the **dispatcher** (`codewhale`) and the **terminal UI runtime** (`codewhale-tui`). This guide walks through the complete first run setup process, from binary installation to environment verification, as implemented in the `Hmbown/CodeWhale` repository. ## Phase 1: Installing the CodeWhale Binaries CodeWhale requires both the dispatcher and TUI runtime binaries available on your `PATH`. The dispatcher locates its TUI partner at runtime via a simple `PATH` lookup, and they must be version-matched according to [`docs/INSTALL.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md). ### Install via npm (Recommended) The npm package pulls pre-built binaries and writes them to `$(npm prefix -g)/bin`. The post-install script enforces version matching via a SHA-256 manifest. ```bash npm install -g codewhale codewhale # triggers the post-install download of the matching binaries ``` ### Install via Cargo Build from source for any Tier-1 Rust target. This installs both components separately: ```bash cargo install codewhale-cli --locked # dispatcher cargo install codewhale-tui --locked # TUI runtime ``` ### Install via Docker Run in an isolated container with persistent volumes for configuration: ```bash docker volume create codewhale-home docker run --rm -it \ -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ -v codewhale-home:/home/codewhale/.codewhale \ -v "$PWD:/workspace" -w /workspace \ ghcr.io/hmbown/codewhale:latest ``` Alternative methods including **Homebrew**, **Nix**, **Windows installers**, and manual download are documented in [`docs/INSTALL.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md). ## Phase 2: Bootstrapping the Runtime and Configuration Navigate to your project directory and launch the dispatcher. On first run, CodeWhale reads or creates the runtime configuration. ```bash cd /path/to/your/project codewhale ``` The dispatcher performs the following initialization sequence defined in [`docs/GUIDE.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/GUIDE.md): - Creates `~/.codewhale/config.toml` if it does not exist - Falls back to legacy `~/.deepseek/config.toml` for backward compatibility ### Configuration Hierarchy The runtime resolves configuration using the following precedence order: 1. **Environment variables** (highest priority) 2. **`~/.codewhale/config.toml`** (new standard location) 3. **`~/.deepseek/config.toml`** (legacy location) This layered approach allows temporary overrides without editing files. ## Phase 3: Authentication and Provider Setup CodeWhale defaults to the **DeepSeek** provider. You must supply a valid API key before initiating your first task. ### Interactive Authentication Run the auth command to persist credentials to the configuration file: ```bash codewhale auth set --provider deepseek ``` ### Environment Variable Method For CI pipelines or Docker containers, export the key before running: ```bash export DEEPSEEK_API_KEY="your-key" codewhale ``` Provider definitions and alternative endpoints are documented in [`docs/PROVIDERS.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/PROVIDERS.md). The same flow works for any OpenAI-compatible endpoint once the proper provider ID is set. ## Phase 4: Verifying Your Installation Run the health-check command to validate the binary pair, stored configuration, and provider credentials: ```bash codewhale doctor # human-readable report codewhale doctor --json # machine-readable JSON for issue filing ``` A successful verification confirms: - Both `codewhale` and `codewhale-tui` are discoverable on `PATH` - The stored API key is valid for the chosen provider - No conflicting environment variables override the saved config A non-zero exit code signals a problem that must be resolved before productive use, as noted in [`docs/INSTALL.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/INSTALL.md). ## Understanding the Dispatcher-Runtime Architecture The **dispatcher** spawns the **TUI runtime** via process execution. Key architectural constraints include: - **PATH Dependency**: The dispatcher expects `codewhale-tui` available in the same `PATH` context - **Version Coupling**: Binaries must be version-matched. The npm post-install script enforces this via SHA-256 checksums against a manifest - **Runtime Spawning**: When you execute `codewhale`, it delegates terminal rendering to the `codewhale-tui` binary After successful verification, you are ready to start your first task: ```bash codewhale ask "What files define the CLI entry point?" ``` ## Summary - **CodeWhale consists of two binaries**: the dispatcher (`codewhale`) and the TUI runtime (`codewhale-tui`), which must be version-matched and available on `PATH` - **Configuration resides** in `~/.codewhale/config.toml`, with fallback support for the legacy `~/.deepseek/config.toml` location - **Authentication defaults to DeepSeek** via `codewhale auth set --provider deepseek` or the `DEEPSEEK_API_KEY` environment variable - **Always verify** your installation using `codewhale doctor` before starting productive work to ensure binary compatibility and valid credentials ## Frequently Asked Questions ### Where does CodeWhale store its configuration files? CodeWhale stores runtime configuration in `~/.codewhale/config.toml`. If this file does not exist on first launch, the dispatcher creates it automatically. For backward compatibility, CodeWhale will read from the legacy `~/.deepseek/config.toml` location if the new path is empty, as documented in [`docs/GUIDE.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/GUIDE.md). ### Can I use CodeWhale with OpenAI-compatible providers other than DeepSeek? Yes. While DeepSeek is the default provider, you can configure any OpenAI-compatible endpoint by setting the appropriate provider ID via `codewhale --provider ` or the `/provider` command inside the TUI. Refer to [`docs/PROVIDERS.md`](https://github.com/Hmbown/CodeWhale/blob/main/docs/PROVIDERS.md) for available provider IDs and their specific credential requirements. ### How do I fix "binary not found" errors during first run? Ensure both `codewhale` and `codewhale-tui` are installed and available on your `PATH`. If installing via npm, run `codewhale` once to trigger the post-install download of the TUI binary. For Cargo installations, verify that `$HOME/.cargo/bin` is in your `PATH`. Run `codewhale doctor` to diagnose specific binary discovery issues. ### Is it safe to commit the `~/.codewhale/config.toml` file to version control? No. This file typically contains sensitive API keys and provider credentials. Keep it in your home directory and add it to your `.gitignore` if working within a repository. Use environment variables like `DEEPSEEK_API_KEY` for CI environments rather than committing the configuration file.