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.

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 installation 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: Extract the Archive

Double-click the downloaded archive.

macOS will automatically extract the package into a Whiskers folder.

Step 3: Start Setup

Open the extracted folder and double-click:

Whiskers Setup

You do not need to open Terminal.

Step 4: Enter Your License Key

When prompted, paste the license key from your Lemon Squeezy receipt email.

Step 5: Wait for Installation

The installer automatically:

• Checks Python 3.12+
• Installs uv if needed
• Creates the Whiskers environment
• Installs or builds llama.cpp
• Downloads a starter model
• Activates your license
• Runs diagnostics
• Starts llama-server
• Starts Whiskers

The first installation may take several minutes depending on internet speed and system performance.

Step 6: Start Chatting

Your browser should automatically open to:

http://localhost:8081

If the browser does not open automatically, enter the address manually.

If Something Goes Wrong

Run the setup utility again. Most installation issues are caused by interrupted downloads, missing dependencies, or temporary network problems.

If the problem persists, collect the installer output and open a support request.

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.

Open File Explorer.

Navigate to Downloads.

Note your Windows username.

Then copy and paste the following commands into the Ubuntu terminal. Replace WINDOWS_USERNAME with the name you just found:

cd /mnt/c/Users/<WINDOWS_USERNAME>/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 5: Run the Installer

python3 whiskers_setup.py

The installer will:

• Verify Python
• Install uv if needed
• Create the Whiskers environment
• Install llama.cpp
• Download a starter model
• Activate your license
• Run diagnostics
• Start Whiskers

Step 6: Start Chatting

When installation completes, open:

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

python3 whiskers_setup.py

The installer automatically:

• Checks Python
• Installs uv if needed
• Creates the Whiskers environment
• Installs llama.cpp
• Downloads a starter model
• Activates your license
• Runs diagnostics
• Starts Whiskers

Step 5: Start Chatting

http://localhost:8081

Installation Complete

If your browser opened and you can chat at http://localhost:8081, Whiskers is installed correctly.

Everything below is optional reference material.

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.

What the Installer Does

The installer performs the manual setup steps automatically.

1. Checks for Python 3.12 or newer.
2. Installs uv if needed.
3. Sets up the Whiskers Python environment.
4. Downloads or builds llama.cpp.
5. Downloads a starter GGUF model.
6. Writes a whiskers.env configuration file.
7. Activates the Whiskers license.
8. Runs the Doctor utility.
9. Starts llama-server.
10. Starts the Whiskers proxy.
11. Opens the browser automatically.

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

Starting Whiskers Later

If Whiskers is not already running, open the Whiskers folder and run:

python3 whiskers_setup.py start

Then open:

http://localhost:8081

Advanced Setup

Most users should skip this section.

The installer already performs these steps automatically. These instructions are provided for advanced users who want to verify, customize, or troubleshoot the installation.

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.

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/<WINDOWS_USERNAME>/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:

uv run validate_license.py

Deactivate this machine:

uv run deactivate_license.py

Mobile Access

Whiskers can be accessed securely from an Android phone, iPhone, iPad, or other mobile device using Tailscale.

The mobile device connects to the Whiskers instance running on your computer. The model, Canon files, Contract files, and session log remain on the Whiskers server.

Read the Mobile Access Guide

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.

Canon and Contract Files

Whiskers separates information into two categories: knowledge and behavior.

Canon and Contract files are one of the primary ways to customize Whiskers for a specific project, workflow, or setting.

Canon Files

Canon files contain facts, documentation, project notes, worldbuilding information, character data, and other information Whiskers should remember. It is automatically provided to the AI model every time you give an input.

By default, the canon file is located at /whiskers/injection_files/canon.capsule in the location where you installed Whiskers.

Think of Canon as:

What Whiskers knows.

Contract Files

Contract files contain instructions, preferences, standards, and constraints that influence how Whiskers responds. It is also automatically provided to the AI model every time you give an input.

By default, the contract file is located at /whiskers/injection_files/contract.txt in the location where you installed Whiskers.

Think of Contract as:

How Whiskers behaves.

Which File Should I Use?

Default Location

/whiskers/injection_files

Editing Canon Files

Open the desired Canon file in your preferred text editor, make changes, and save the file. The example file provided during install should give you an idea of how you can format the files.

Canon files are JSON files. JSON is a structured text format used by Whiskers to organize information before it is provided to the model. JSON stores information using key:value pairs. You do not need a special editor. Any text editor such as Notepad, TextEdit, VS Code, Vim, or Nano can edit JSON files.

For example:

    "setting": {
      "location": "Aurora Academy",
      "description": "A modern fantasy prestigious academy where talented students from many backgrounds gather to study, compete, and form social bonds."
  }

Some of the things you might consider putting in the canon file include:

• Project documentation
• Character biographies
• World lore
• Research notes

Editing Contract Files

Open the desired Contract file and update the instructions. Contract files are normal text files and can be edited by any text editor, such as Notepad or TextEdit.

For example:

ROLE
-----
You are the Narrative Engine (Scene Director / GM layer).

You control:
- The world and setting
- NPC characters
- Environmental description
- Social dynamics between characters
- Consequences and reactions
- Scene pacing

Some of the things you might consider putting in the contract file include:

• Coding standards
• Writing style requirements
• Formatting preferences
• Project rules

Applying Changes

Changes are loaded automatically when you submit a new prompt. However, the AI model decides when and how to use the information. A newly added character, fact, or instruction may not appear in the very next response unless it is relevant to the conversation.

You can also start a new conversation after making significant changes so the updated information can be incorporated into the conversation context.

Recommended Workflow

1. Edit Canon or Contract files.
2. Save the files.
3. Submit a new prompt or start a new conversation.
4. Verify the changes were recognized.

Multiple Files

You can have multiple versions of either canon or contract files for different projects. Future versions of Whiskers will allow swapping between them automatically but for v1.x, you will have to manually copy and paste the desired version to the contract.txt or canon.capsule files.

For example, you might maintain:

• work.canon.capsule
• work.contract.txt
• novel.canon.capsule
• novel.contract.txt
• rpg.canon.capsule
• rpg.contract.txt

In Whiskers v1.x, copy the desired file to canon.capsule or contract.txt before starting work on that project.

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 files in the current folder, including the setup utility.

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 whiskers
chmod +x "Whiskers Setup.command"

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