Download & Install

Install Whiskers, connect it to a local llama.cpp server, and open the browser UI. Whiskers is small; the model and llama.cpp server are separate local components.

Get Whiskers

Current Version

v1.x

Platform support: Linux, macOS, Windows with WSL2

Purchased Whiskers?

After installation, activate Whiskers using the license key included in your Lemon Squeezy receipt email.

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

uv run activate_license.py YOUR-LICENSE-KEY

Keep your purchase email for future reinstalls or migrations.

Before You Start

Whiskers is a local Python runtime. It does not include a model by itself. You will also need a local llama.cpp server and a GGUF model file.

If you are new to command-line tools: a terminal is a text window where you type commands. On Linux and macOS, use the Terminal app. On Windows, use Ubuntu through WSL after it is installed.

Copy commands exactly unless the instruction says to replace part of the command.
When you see <YOURNAME>, replace it with your actual Windows username.
When you see a filename like whiskers-v1.x.tar.gz, use the actual file you downloaded.
Do not type Linux commands like sudo apt update into normal Windows Command Prompt unless the instructions specifically say PowerShell or Windows Terminal.

Linux Setup

1. Open a terminal

Open your Terminal app. You should see a text prompt where commands can be typed.

2. Install system packages

sudo apt update
sudo apt install python3 python3-venv python3-pip curl tar -y

3. Download and extract Whiskers

Download the latest Whiskers release package, then move to the folder where it was downloaded. This example assumes the file is in your Downloads folder.

Get Whiskers

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

4. Create the Python environment

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

5. Continue with model setup

Whiskers is installed. Next, start a local llama.cpp server and run the Whiskers proxy. See the Docs for the model and server steps.

macOS Setup

Whiskers runs natively on macOS. For best results, run llama.cpp natively with Metal. Multipass is useful for Linux experiments, but it is not recommended for normal Whiskers use on low-memory Macs.

1. Open Terminal

Open Terminal from Applications → Utilities, or search for Terminal with Spotlight.

2. Check Python

python3 --version

If Python is missing or too old, install the current Python 3 release from python.org.

3. Download and extract Whiskers

Download the latest Whiskers release package, then move to the folder where it was downloaded.

Get Whiskers

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

4. Create the Python environment

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

5. Use native llama.cpp on macOS

Try the official llama.cpp release first. If llama-server fails to launch, build llama.cpp locally instead. Local builds were more reliable during Apple Silicon testing.

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

For 8GB Macs, avoid very aggressive build parallelism. Native Metal worked substantially better than running inference inside a Linux VM.

6. Continue with model setup

Whiskers is installed. Next, start a local llama.cpp server and run the Whiskers proxy. See the Docs for the model and server steps.

Windows Setup Using WSL2

Whiskers runs as a Linux application under WSL2. WSL lets Windows run a real Linux environment. After Ubuntu opens, treat that window as Linux. The commands below go into Ubuntu, not ordinary Windows Command Prompt.

1. Install WSL2 and Ubuntu

Open PowerShell as Administrator. To do that, right-click the Start button, choose Terminal/Admin or PowerShell/Admin, then run:

wsl --install

Restart Windows if asked. After rebooting, open Ubuntu from the Start menu. The first launch may ask you to create a Linux username and password.

2. Confirm you are in Ubuntu

Your prompt should look like a Linux terminal, not a normal Windows path. This command should print Linux system information:

uname -a

3. Install Linux packages inside Ubuntu

sudo apt update
sudo apt install python3 python3-venv python3-pip curl tar -y

4. Download Whiskers

Download the Whiskers release package from the official download link in your Windows browser. If it lands in your Windows Downloads folder, Ubuntu can reach it through /mnt/c/Users/<YOURNAME>/Downloads.

Get Whiskers

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

5. Create the Python environment

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

6. Continue with model setup

Whiskers is installed inside Ubuntu. Next, start a local llama.cpp server and run the Whiskers proxy. See the Docs for the model and server steps.

What Happens Next?

Installing Whiskers only installs the runtime. To actually chat, you still need three pieces running together:

A GGUF model file on your machine.
A local llama.cpp server running that model.
The Whiskers proxy connected to that local server.

When everything is running, you open the browser UI and talk to the model through Whiskers. Your session state and logs stay on your machine.

Read the full installation guide

Common Beginner Mistakes

Typing Linux commands into Windows: On Windows, use Ubuntu/WSL for the Linux commands.
Skipping the virtual environment: Run source venv/bin/activate before installing Python packages.
Wrong folder: Run commands from inside the extracted whiskers folder.
No model server: Whiskers needs llama.cpp running separately.
Wrong port: The model server and Whiskers proxy must use the expected ports shown in the docs.