Troubleshooting

Common issues and how to fix them. Most install problems fall into one of these categories — find yours and follow the steps.

Windows SmartScreen or Defender warning

You see “Windows protected your PC” or a Defender pop-up when running the installer. This is expected — Cerebro is not code-signed yet.

Why it happens. SmartScreen flags executables without a paid Extended Validation (EV) code-signing certificate. Cerebro doesn't have one yet. The warning is cosmetic — the installer is safe, and every release build and its checksum are published on GitHub.

Verify the installer — download SHA256SUMS from the same GitHub release and compare:

Get-FileHash Cerebro-Installer.exe -Algorithm SHA256

macOS Gatekeeper blocks the app

macOS says “Cerebro can't be opened because it is from an unidentified developer.” Gatekeeper works the same way as SmartScreen — no Apple Developer certificate yet.

On macOS 14 Sonoma and earlier you can instead right-click (or Control-click) the app in Finder, choose Open, then click Open in the dialog. Cerebro for Mac is built for Apple Silicon (M1–M4); Intel Macs are not supported yet.

winget not found (older Windows 10)

The setup wizard uses winget to install Git on Windows. winget ships with Windows 10 21H1 and later; older builds don't have it.

Option A — update Windows. Settings → Windows Update, install pending updates. Windows 10 21H1 (May 2021) or later includes winget automatically.

Option B — install winget manually. Install the App Installer package from the Microsoft Store, or from PowerShell:

# Download and install App Installer (includes winget)
Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe

Option C — install Git directly. Skip winget: download the Git installer from git-scm.com and run it. Then use the wizard's [Show manual instructions] option and complete setup from there.

Corporate proxy or offline installation

The setup wizard downloads prerequisite installers from official sources (claude.ai, nodejs.org, winget/brew). A corporate proxy or firewall that intercepts HTTPS will block these requests.

Manual pre-install (recommended for managed machines). Use [Show manual instructions] instead of [Install for me], install prerequisites through your organization's approved channels, then relaunch the wizard.

# Set proxy for npm / Node.js tools
npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port

# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

Fully offline. On a machine with internet access, download all prerequisites and transfer them to the air-gapped machine. Install each one, then run the Cerebro installer — the wizard detects them as present and proceeds to launch.

“claude not found” or “command not found: claude”

The Claude Code CLI installed successfully, but Cerebro (or your terminal) can't find it. This is a PATH issue — the install directory isn't in your shell's search path.

macOS / Linux — add to PATH, then restart your shell:

# Add these lines and then restart your shell
export PATH="$HOME/.local/bin:$PATH"
export PATH="/usr/local/bin:$PATH"

# Reload without restarting
source ~/.zshrc   # or source ~/.bashrc

Windows — search for “Edit the system environment variables”, click Environment Variables, find Path under User variables, and add the directory where claude.cmd was installed (typically %APPDATA%\npm). To find it:

where.exe claude

After updating PATH, restart Cerebro Desktop so it picks up the new environment.

No administrator rights

You don't have admin access on the machine (common on managed corporate laptops). Some install steps require elevated permissions.

What still works without admin:

• Cerebro Desktop itself installs to your user folder — no admin needed
• Claude Code CLI via npm install -g installs to your user directory (no sudo for user-scoped npm)
• Node.js via nvm (Linux/macOS) or nvm-windows — user-only install

Node.js without admin — use nvm:

# Install nvm (no sudo)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Reload shell, then install Node LTS
nvm install --lts
nvm use --lts

If your organization's policy blocks all user installs, ask IT to pre-install Node.js LTS and the Claude Code CLI. Once present, Cerebro detects them and proceeds without installing anything.

AppImage won't run — FUSE error on Linux

You see fuse: failed to exec fusermount3: No such file or directory or a similar FUSE message. AppImages use FUSE to mount themselves — it must be installed.

# Ubuntu 24.04+ (libfuse2 was renamed to libfuse2t64)
sudo apt-get install -y libfuse2t64
# Ubuntu 20.04 / 22.04 and Debian
sudo apt-get install -y libfuse2
# Fedora / RHEL
sudo dnf install fuse-libs
# Arch Linux
sudo pacman -S fuse2

Alternative — extract and run without FUSE. If you can't install FUSE (no sudo, locked-down distro), extract the AppImage and run the binary directly:

chmod +x Cerebro-Installer.AppImage
./Cerebro-Installer.AppImage --appimage-extract
./squashfs-root/AppRun