Installation Guide

Contents

Before You Begin

Whiskers is local software. It runs on your computer instead of sending your conversations to a cloud service.

Whiskers uses three pieces:

• The AI model — the downloaded .gguf file. This is the model's brain.
• llama.cpp — the local engine that runs the model.
• Whiskers — the memory, continuity, and browser layer that connects to llama.cpp.

The quick installer sets up those pieces automatically where possible.

What You Need

• A computer running macOS, Windows, or Linux.
• An internet connection for installation, activation, and downloading the starter model.
• Your Whiskers download package.
• Your Lemon Squeezy license key from your receipt email.
• Enough disk space for Whiskers, llama.cpp, and at least one model file.

After activation, Whiskers can run offline. It does not require a recurring online check to keep using an already activated install.

Never Used a Terminal Before?

A terminal is a text window where you type commands. The quick install uses the terminal because Whiskers starts local services on your computer.

When this guide shows a command in a box, copy it exactly, paste it into the terminal, and press Enter.

When this guide uses ~, it means your Home folder. On most keyboards, the ~ key is near the top-left, usually on the same key as `, below Esc.

When this guide says “leave this terminal running,” do not close that window. Open another terminal window or tab for the next command.

Choose Your Operating System

Use one of the sections below. Each operating system section is self-contained.

• macOS Quick Install
• Windows Quick Install
• Linux Quick Install

macOS Quick Install

This is the recommended install path for most Mac users.

Step 1: Download Whiskers

Download the latest Whiskers release package from the official download page:

Get Whiskers

Save the file to your Downloads folder.

Step 2: Open Terminal

1. Press Command + Space.
2. Type Terminal.
3. Press Enter.

A text window will open. This is where you type or paste commands.

Step 3: Open the Whiskers Folder

Copy and paste these commands into Terminal. Press Enter after each line:

cd ~/Downloads
tar -xzf whiskers-portable-v1.x.tar.gz
cd whiskers

Note: replace whiskers-portable-v1.x.tar.gz with the exact filename you downloaded if it is different.

Step 4: Run the Installer

chmod +x install_macos.command
./install_macos.command

The installer may run for several minutes. Do not close the Terminal window.

The installer will check Python, install Whiskers dependencies, get llama.cpp, download a small starter model, and run diagnostics.

Step 5: Wait for Success

When installation completes, you should see:

INSTALL SUCCESSFUL

Step 6: Activate Whiskers

Copy your license key from your Lemon Squeezy receipt email.

./activate.command YOUR-LICENSE-KEY

Replace YOUR-LICENSE-KEY with your actual license key.

Activation requires internet access once. After activation, Whiskers runs offline.

Step 7: Start Whiskers

./start_whiskers.command

Leave this Terminal window running.

Step 8: Open Whiskers in Your Browser

Open your browser and go to:

http://localhost:8081

Whiskers should now be running.

If Something Goes Wrong

If Terminal says it cannot find the file or folder, check where you are:

pwd
ls

You should be inside the whiskers folder. If you are not, go back to your Downloads folder and try again:

cd ~/Downloads
cd whiskers

Windows Quick Install

On Windows, Whiskers runs inside Ubuntu using WSL2. WSL2 gives Windows a Linux environment.

Step 1: Download Whiskers

Download the latest Whiskers release package from the official download page:

Get Whiskers

Save the file to your Downloads folder.

Step 2: Install WSL2

Open PowerShell as Administrator:

1. Click the Start button.
2. Type PowerShell.
3. Right-click Windows PowerShell or PowerShell.
4. Choose Run as administrator.
5. If Windows asks for permission, click Yes.

Run:

wsl --install

Restart Windows if prompted.

Step 3: Open Ubuntu

Open the Start menu and launch Ubuntu.

The first launch may ask you to create a Linux username and password. This does not have to match your Windows username.

From this point forward, type Linux commands into Ubuntu, not normal Windows Command Prompt.

Step 4: Open the Whiskers Folder

Your Windows Downloads folder is available inside Ubuntu under /mnt/c/Users.

Copy and paste these commands into the Ubuntu terminal:

cd /mnt/c/Users/<YOURNAME>/Downloads
tar -xzf whiskers-portable-v1.x.tar.gz
cd whiskers

Replace <YOURNAME> with your Windows username. Replace whiskers-portable-v1.x.tar.gz with the exact filename you downloaded if needed.

Step 5: Run the Installer

chmod +x install_linux.sh
./install_linux.sh

The installer may ask for your Ubuntu password when installing system packages.

Step 6: Wait for Success

When installation completes, you should see:

INSTALL SUCCESSFUL

Step 7: Activate Whiskers

./activate.sh YOUR-LICENSE-KEY

Replace YOUR-LICENSE-KEY with your actual Lemon Squeezy license key.

Step 8: Start Whiskers

./start_whiskers.sh

Leave this Ubuntu window running.

Step 9: Open Whiskers in Your Browser

Open your Windows browser and go to:

http://localhost:8081

Linux Quick Install

Step 1: Download Whiskers

Download the latest Whiskers release package from the official download page:

Get Whiskers

Step 2: Open Terminal

Open your Linux Terminal application.

Step 3: Extract Whiskers

If the release package is in your Downloads folder:

cd ~/Downloads
tar -xzf whiskers-portable-v1.x.tar.gz
cd whiskers

Replace whiskers-portable-v1.x.tar.gz with the exact filename you downloaded if needed.

Step 4: Run the Installer

chmod +x install_linux.sh
./install_linux.sh

The installer may ask for your password when installing system packages.

Step 5: Wait for Success

INSTALL SUCCESSFUL

Step 6: Activate Whiskers

./activate.sh YOUR-LICENSE-KEY

Step 7: Start Whiskers

./start_whiskers.sh

Step 8: Open Whiskers in Your Browser

http://localhost:8081

What the Installer Does

The installer performs the manual setup steps automatically.

1. Checks for Python 3.10 or newer.
2. Installs uv if needed.
3. Sets up the Whiskers Python environment.
4. Tries to download a prebuilt llama.cpp release.
5. If the prebuilt llama.cpp release does not work, builds llama.cpp from source.
6. Creates a ~/models folder.
7. Downloads a small starter GGUF model.
8. Writes a whiskers.env file with paths and ports.
9. Runs the Doctor utility if available.
10. Prints INSTALL SUCCESSFUL when complete.

The starter model is intentionally small. It proves the installation works. You can use a larger model later.

Activation

Whiskers uses a lightweight offline-first activation system.

After purchase, Lemon Squeezy emails you a license key.

Activation requires internet access once. After activation:

• Whiskers runs fully offline.
• No recurring phone-home checks occur.
• Existing activated installs continue functioning after expiration.
• Updates and new activations require an active license.

Activation data is stored locally:

~/.whiskers/license.json

Keep your Lemon Squeezy receipt email for future reinstalls or migrations.

Starting Whiskers

The quick install creates helper scripts that start the local model server and the Whiskers proxy.

macOS

./start_whiskers.command

Linux / Windows WSL

./start_whiskers.sh

When Whiskers is running, open:

http://localhost:8081

Please note: the first prompt may take time to process. After that, output should usually begin faster.

Advanced Setup

This section explains the manual installation path. Most users should use the quick installer above.

Install Python Tools

On Linux or Ubuntu/WSL:

sudo apt update
sudo apt install python3 python3-venv python3-pip curl tar git cmake build-essential -y

Check Python:

python3 --version

What success looks like: You see a Python 3 version number.

Download and Extract Whiskers

Linux/macOS:

cd ~/Downloads
tar -xzf whiskers-portable-v1.x.tar.gz
cd whiskers

Windows / WSL2:

cd /mnt/c/Users/<YOURNAME>/Downloads
tar -xzf whiskers-portable-v1.x.tar.gz
mv whiskers ~/whiskers
cd ~/whiskers

Create the Python Environment

From inside the whiskers folder:

uv sync

What success looks like: uv finishes without errors.

Install llama.cpp Manually

Whiskers connects to a local llama.cpp server. Try a prebuilt release first. If it fails, build from source.

Option A: Use a prebuilt release

Download a matching release for your system from the llama.cpp releases page, extract it, and locate the llama-server executable.

On macOS, prebuilt archives may occasionally fail due to library or Gatekeeper behavior. If llama-server --help does not work, use Option B.

Option B: Build from source

cd ~
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build -j 4

After building, the server executable is usually at:

~/llama.cpp/build/bin/llama-server

Download a GGUF Model

Download a model in GGUF format. Smaller models are easier to run. Larger models need more RAM or VRAM.

Save the model somewhere easy to type, such as ~/models.

mkdir -p ~/models

After downloading the model, note the exact filename.

Start the Model Server Manually

~/llama.cpp/build/bin/llama-server \
  -m ~/models/<MODEL_FILE>.gguf \
  --host 127.0.0.1 \
  --port 8083 \
  -c 4096 \
  -b 256

Leave this terminal running.

On Apple Silicon Macs, you may add -ngl 99 to use Metal acceleration.

Optional: Start a Summarizer Server

Whiskers can use a second local model server for background summaries. Basic chat can still work without it.

~/llama.cpp/build/bin/llama-server \
  -m ~/models/<SUMMARY_MODEL_FILE>.gguf \
  --host 127.0.0.1 \
  --port 8084 \
  -c 2048 \
  -b 256

Start Whiskers Manually

Open another terminal, go back into the Whiskers folder, and start the proxy:

cd ~/whiskers
chmod +x whiskers
./whiskers proxy

What success looks like: Whiskers prints that it is listening on 8081 and forwarding to llama-server on 8083.

Doctor Utility

Whiskers includes a diagnostic utility to verify that the runtime environment is configured correctly.

Run:

uv run doctor.py

The doctor utility checks:

• Python version
• Required Python modules
• Activation status
• llama.cpp server reachability
• Summarizer server reachability
• Required Whiskers files
• Filesystem write permissions

Warnings are informational and do not necessarily prevent Whiskers from running.

License Utilities

Validate the current activation:

./validate_license.sh

Deactivate this machine:

./deactivate.sh

Advanced users can also run the Python utilities directly if included in the release:

uv run validate_license.py
uv run deactivate_license.py

Runtime Commands

Whiskers adds a few commands you can type into the chat box.

• /context — shows estimated context usage.
• /summarize — starts a background summary job using the summarizer server.
• /rewrite <text> — replaces the last pending assistant output before it is committed to the session log.
• /version — shows the Whiskers version.
• /help — shows available commands.

/rewrite is for correcting a bad response immediately. Use it before continuing the conversation.

Output Quality Tips

Local models can still drift, repeat themselves, or choose an awkward continuation. Whiskers helps with continuity, but the model is still the thing generating words.

• Stop a bad response early and regenerate.
• Use short steering prompts such as “Shorter response,” “Stay factual,” or “Avoid repetition.”
• Use /rewrite when the last response needs direct correction.
• Use /context to check whether the active context is getting heavy.

For long sessions, treat correction as normal session maintenance. You are steering a runtime, not praying to a cloud oracle. 🐈‍⬛

Troubleshooting

Before Reporting a Bug

Whiskers operates as a runtime layer on top of llama.cpp. Before reporting a bug, first determine whether the issue exists in vanilla llama.cpp without Whiskers.

Step 1: Reproduce the Issue in Vanilla llama.cpp

Run the same model, prompt, and workflow directly through llama.cpp without Whiskers enabled.

If the Issue Occurs in Vanilla llama.cpp

The issue is outside the Whiskers runtime.

Possible causes include:

• Model behavior or hallucinations
• Prompt design issues
• GGUF model problems
• llama.cpp bugs or limitations
• Context window exhaustion
• Insufficient system resources

Whiskers cannot correct problems that already exist in the underlying model runtime.

If the Issue Only Occurs When Whiskers Is Enabled

Collect the following information before opening a bug report:

• Whiskers version
• Operating system
• Model name
• Relevant logs or screenshots
• Steps required to reproduce the issue
• Whether the problem occurs consistently or intermittently

Installer says “command not found”

You may be in the wrong folder. Run:

pwd
ls

You should see the Whiskers installer scripts listed in the current folder.

Windows says “sudo is not recognized”

You are probably typing Linux commands into normal Windows Command Prompt or PowerShell. Open Ubuntu from the Start menu and run Linux commands there.

Python not found

Use python3, not python. On Linux/WSL, rerun the installer or install Python manually.

Wrong folder

Use pwd to show your current folder and ls to list files. For Whiskers commands, you should be inside the extracted whiskers folder.

llama-server not found

If you used the quick installer, rerun the installer. If you installed manually, check the path to llama-server.

If you built llama.cpp from source, the server is usually at:

~/llama.cpp/build/bin/llama-server

Whiskers cannot connect to llama-server

Make sure the main llama-server is running on port 8083. Test it from another terminal:

curl http://localhost:8083/props

If your model server is on a different port, start Whiskers with LLAMA_PORT set to that port:

LLAMA_PORT=9000 ./whiskers proxy

Port already in use

Default ports are:

• 8083 — main llama.cpp model server
• 8084 — optional summarizer llama.cpp server
• 8081 — Whiskers proxy/browser entry point

To change the Whiskers browser port:

WHISKERS_PORT=8090 ./whiskers proxy

Then open http://localhost:8090.

Permission denied

Make the launcher or script executable:

chmod +x install_linux.sh
chmod +x start_whiskers.sh
chmod +x whiskers

macOS says the binary is blocked

If macOS blocks a downloaded llama-server binary, remove the quarantine attribute from the downloaded llama.cpp folder or binary:

xattr -rd com.apple.quarantine /path/to/llama.cpp-or-binary-folder