| 1 | # Codewhale Classroom / Lab Install Checklist |
| 2 | |
| 3 | A step-by-step checklist for IT admins deploying Codewhale on lab or classroom |
| 4 | machines running Windows. |
| 5 | |
| 6 | > **Audience**: IT staff, teaching assistants, lab managers. |
| 7 | > **Prereq**: Each target machine runs Windows 10 (1809+) or Windows 11. |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## Pre-install checklist (run once per machine) |
| 12 | |
| 13 | | # | Task | Done? | |
| 14 | |---|------|-------| |
| 15 | | 1 | Confirm Windows version: `winver` → 10 build 17763+ or 11 | ☐ | |
| 16 | | 2 | Ensure the user account is a **standard user** (not a local admin). The installer does not require elevation. | ☐ | |
| 17 | | 3 | Verify outbound HTTPS (port 443) is open to `api.openai.com` (or whichever LLM provider the course uses). | ☐ | |
| 18 | | 4 | Obtain the installer: download `CodeWhaleSetup.exe` from a v0.8.50+ [release](https://github.com/Hmbown/CodeWhale/releases/latest) or from your department mirror. | ☐ | |
| 19 | | 5 | Verify SHA-256 hash against `codewhale-artifacts-sha256.txt` before deploying. | ☐ | |
| 20 | | 6 | Note that the public installer is currently unsigned and may trigger Windows SmartScreen unless your organization signs it before deployment. | ☐ | |
| 21 | |
| 22 | --- |
| 23 | |
| 24 | ## Installation |
| 25 | |
| 26 | ### Option A — Silent install (recommended for imaging / SCCM / Intune) |
| 27 | |
| 28 | ```powershell |
| 29 | # Run as the target user or via a per-user deployment tool |
| 30 | CodeWhaleSetup.exe /S |
| 31 | ``` |
| 32 | |
| 33 | The silent installer: |
| 34 | - Installs to `%LOCALAPPDATA%\Programs\CodeWhale\bin` |
| 35 | - Adds the bin directory to the **current user** PATH |
| 36 | - Registers in Windows "Apps & Features" for uninstall |
| 37 | |
| 38 | ### Option B — Interactive install |
| 39 | |
| 40 | 1. Double-click `CodeWhaleSetup.exe`. |
| 41 | 2. Accept the license. |
| 42 | 3. Choose the install directory (default is fine for most setups). |
| 43 | 4. Click **Install**. |
| 44 | |
| 45 | ### Option C — Manual fallback (no installer) |
| 46 | |
| 47 | If the NSIS installer is blocked by group policy, install manually: |
| 48 | |
| 49 | ```powershell |
| 50 | # 1. Create directory |
| 51 | $binDir = "$env:LOCALAPPDATA\Programs\CodeWhale\bin" |
| 52 | New-Item -ItemType Directory -Force -Path $binDir |
| 53 | |
| 54 | # 2. Download binaries (adjust URL to your mirror or release tag) |
| 55 | $tag = (Invoke-RestMethod -Uri "https://api.github.com/repos/Hmbown/CodeWhale/releases/latest").tag_name |
| 56 | Invoke-WebRequest -Uri "https://github.com/Hmbown/CodeWhale/releases/download/$tag/codewhale-windows-x64.exe" -OutFile "$binDir\codewhale.exe" |
| 57 | Invoke-WebRequest -Uri "https://github.com/Hmbown/CodeWhale/releases/download/$tag/codewhale-tui-windows-x64.exe" -OutFile "$binDir\codewhale-tui.exe" |
| 58 | |
| 59 | # 3. Add to user PATH (persistent) |
| 60 | $currentPath = [Environment]::GetEnvironmentVariable("Path", "User") |
| 61 | $pathParts = @($currentPath -split ";" | Where-Object { $_ }) |
| 62 | if ($pathParts -notcontains $binDir) { |
| 63 | $newPath = (@($pathParts) + $binDir) -join ";" |
| 64 | [Environment]::SetEnvironmentVariable("Path", $newPath, "User") |
| 65 | } |
| 66 | |
| 67 | # 4. Refresh current session PATH |
| 68 | $env:Path = [Environment]::GetEnvironmentVariable("Path", "User") + ";" + [Environment]::GetEnvironmentVariable("Path", "Machine") |
| 69 | ``` |
| 70 | |
| 71 | --- |
| 72 | |
| 73 | ## Post-install verification |
| 74 | |
| 75 | Run these on **each machine** (or spot-check a sample): |
| 76 | |
| 77 | | # | Command | Expected output | Done? | |
| 78 | |---|---------|-----------------|-------| |
| 79 | | 1 | `codewhale --version` | Prints version string | ☐ | |
| 80 | | 2 | `codewhale doctor` | Prints the offline structural report; live checks remain not probed | ☐ | |
| 81 | | 3 | `codewhale-tui --version` | Prints version string | ☐ | |
| 82 | |
| 83 | If `codewhale` is not found, the user may need to open a **new** terminal window for PATH changes to take effect. |
| 84 | |
| 85 | ## Lab validation checklist |
| 86 | |
| 87 | Run this once on a clean lab machine, and again on a machine that already has a |
| 88 | previous Codewhale install: |
| 89 | |
| 90 | | # | Scenario | Expected result | Done? | |
| 91 | |---|----------|-----------------|-------| |
| 92 | | 1 | Install with no existing CodeWhale PATH entry | Adds exactly `%LOCALAPPDATA%\Programs\CodeWhale\bin` | ☐ | |
| 93 | | 2 | Install twice | PATH is not duplicated | ☐ | |
| 94 | | 3 | Install with a neighboring PATH entry such as `C:\Tools\CodeWhale\bin-extra` | Neighboring entry is preserved | ☐ | |
| 95 | | 4 | Upgrade by installing a newer `CodeWhaleSetup.exe` over an older one | Apps & Features version and both `--version` outputs match the new build | ☐ | |
| 96 | | 5 | Silent uninstall with `Uninstall.exe /S` | Files, uninstall registry entry, and only the exact installer PATH entry are removed | ☐ | |
| 97 | |
| 98 | --- |
| 99 | |
| 100 | ## API key provisioning |
| 101 | |
| 102 | Each student needs an API key. Options: |
| 103 | |
| 104 | | Method | Pros | Cons | |
| 105 | |--------|------|------| |
| 106 | | **Per-student key** | Individual usage tracking | More key management | |
| 107 | | **Shared lab key** | Simple to deploy | Harder to audit; rate limits shared | |
| 108 | |
| 109 | ### Deploying a shared key via environment variable |
| 110 | |
| 111 | ```powershell |
| 112 | # Set for current user (persists across reboots) |
| 113 | [Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-...", "User") |
| 114 | ``` |
| 115 | |
| 116 | Or create a `config.toml` in `%APPDATA%\codewhale\`: |
| 117 | |
| 118 | ```toml |
| 119 | [provider] |
| 120 | api_key = "sk-..." |
| 121 | base_url = "https://api.openai.com/v1" |
| 122 | ``` |
| 123 | |
| 124 | ### Deploying per-student keys with Intune / GPO |
| 125 | |
| 126 | Use a Group Policy Preference or Intune PowerShell script to set the |
| 127 | `OPENAI_API_KEY` environment variable per user. The variable name depends on |
| 128 | your LLM provider — see [CONFIGURATION.md](CONFIGURATION.md). |
| 129 | |
| 130 | --- |
| 131 | |
| 132 | ## Uninstall |
| 133 | |
| 134 | ### Silent uninstall |
| 135 | |
| 136 | ```powershell |
| 137 | & "$env:LOCALAPPDATA\Programs\CodeWhale\Uninstall.exe" /S |
| 138 | ``` |
| 139 | |
| 140 | ### Manual uninstall (if installer was not used) |
| 141 | |
| 142 | ```powershell |
| 143 | $binDir = "$env:LOCALAPPDATA\Programs\CodeWhale\bin" |
| 144 | Remove-Item -Recurse -Force (Split-Path $binDir) |
| 145 | |
| 146 | # Remove from PATH |
| 147 | $currentPath = [Environment]::GetEnvironmentVariable("Path", "User") |
| 148 | $newPath = ($currentPath -split ";" | Where-Object { $_ -and ($_ -ne $binDir) }) -join ";" |
| 149 | [Environment]::SetEnvironmentVariable("Path", $newPath, "User") |
| 150 | ``` |
| 151 | |
| 152 | --- |
| 153 | |
| 154 | ## Troubleshooting |
| 155 | |
| 156 | | Symptom | Fix | |
| 157 | |---------|-----| |
| 158 | | `codewhale` not found after install | Open a **new** terminal. If still missing, check PATH: `echo $env:Path` | |
| 159 | | `MISSING_COMPANION_BINARY` | Ensure both `codewhale.exe` and `codewhale-tui.exe` are in the same directory | |
| 160 | | `TLS handshake` errors | Check proxy settings or use the CNB mirror (see [INSTALL.md](INSTALL.md)) | |
| 161 | | Antivirus quarantines binaries | Add the install directory to AV exclusions | |
| 162 | | `codewhale doctor` reports credential availability as `unknown`/`not_probed`/`unavailable` | This is the safe offline result. A declared environment, external-auth, OAuth, consent, or secret-store source is not proof of availability and does not certify Setup/Fleet readiness. `unavailable` means the route declared the legacy store sentinel but is not allowed to use that shared store. Use `codewhale doctor --probe-api` only on an approved connected machine when a live check is required. | |
| 163 | |
| 164 | --- |
| 165 | |
| 166 | ## Imaging / Golden Image Notes |
| 167 | |
| 168 | If building a golden image (WIM/FFU): |
| 169 | |
| 170 | 1. Install Codewhale using Option A (silent) or Option C (manual). |
| 171 | 2. Do **not** set API keys in the image — these are per-user/per-student. |
| 172 | 3. The install directory (`%LOCALAPPDATA%\Programs\CodeWhale\bin`) is per-user, |
| 173 | so it will be present for the user who installed it. For other users on the |
| 174 | same machine, run the installer again or use Option C. |
| 175 | 4. Alternatively, install to a shared location like `C:\Tools\CodeWhale\bin` |
| 176 | and add it to the **machine** PATH: |
| 177 | ```powershell |
| 178 | [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Tools\CodeWhale\bin", "Machine") |
| 179 | ``` |
| 180 | |
| 181 | --- |
| 182 | |
| 183 | ## Quick Reference: All file paths |
| 184 | |
| 185 | | Item | Default location | |
| 186 | |------|-----------------| |
| 187 | | Binaries | `%LOCALAPPDATA%\Programs\CodeWhale\bin\` | |
| 188 | | User config | `%APPDATA%\codewhale\config.toml` | |
| 189 | | Uninstaller | `%LOCALAPPDATA%\Programs\CodeWhale\Uninstall.exe` | |
| 190 | | PATH entry | `HKCU\Environment\Path` (current user) | |
| 191 | |
| 192 | --- |
| 193 | |
| 194 | *Last updated: 2026-06-02* |
| 195 |