Documentation
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
Windows SmartScreen flags executables that don't have a paid Extended Validation (EV) code-signing certificate. Cerebro doesn't have one yet. The warning is cosmetic — the installer is safe. Every release build and its checksum are published on GitHub.
What to do
When the SmartScreen dialog appears, click More info.
Click Run anyway.
If Windows Defender quarantines the file, open Defender → Virus & threat protection → Protection history → find the entry and click Allow.
Verify the installer
Download the SHA256SUMS file from the same GitHub release and compare:
Get-FileHash Cerebro-Installer.exe -Algorithm SHA256macOS 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.
What to do
In Finder, right-click (or Control-click) the app icon.
Select Open from the context menu.
Click Open in the dialog. After this first approval, double-clicking works normally.
If the right-click method doesn't work, go to System Settings → Privacy & Security and look for a button near the bottom that says "Cerebro was blocked" — click Open Anyway.
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
Go to Settings → Windows Update and install pending updates. Windows 10 21H1 (May 2021) or later includes winget automatically.
Option B — Install winget manually
Download the App Installer package from the Microsoft Store or the GitHub release:
# Download and install App Installer (includes winget)
Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbweOption C — Install Git directly
Skip winget entirely. Download the Git installer from git-scm.com and run it. Once Git is installed, 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] in the wizard instead of [Install for me]. Then install prerequisites manually through your organization's approved channels before relaunching 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-codeFully offline
On a machine with internet access, download all prerequisites manually and transfer them to the air-gapped machine. Install each one, then run the Cerebro installer — the wizard will detect them as already present and proceed 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
# 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 ~/.bashrcWindows — fix PATH in System Settings
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).
where.exe claudeAfter 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 installs to your user directory with
npm install -g(no sudo required 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 --ltsIf your organization's policy blocks all user installs, contact IT and ask them to pre-install Node.js LTS and the Claude Code CLI. Once those are present, Cerebro will detect them and proceed without needing to install 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-related message. AppImages use FUSE to mount themselves — it must be installed.
Install FUSE
# 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 fuse2Alternative — extract and run without FUSE
If you can't install FUSE (no sudo, locked-down distro), you can extract the AppImage and run the binary directly:
chmod +x Cerebro-Installer.AppImage
./Cerebro-Installer.AppImage --appimage-extract
./squashfs-root/AppRunWSL (Windows Subsystem for Linux)
AppImages don't run in WSL2 by default — use the native Windows .exe installer instead. Cerebro Desktop is a GUI app and needs a native OS session.
Still stuck?
If none of the above fixes your issue, check the GitHub issues list or open a new one with your OS version, the exact error message, and what you've already tried.