Installing TigerMole on Linux
Ubuntu 20.04+, Debian 11+, and any distribution with glibc ≥ 2.31. For servers with no desktop environment, use the CLI wizard below.
Download
• tigermole-proxy-X.X.X-amd64.deb — recommended for Ubuntu / Debian
• tigermole-proxy-X.X.X-linux-x86_64.tar.gz — other distributions
Verify the SHA-256 checksum before installing:
sha256sum -c tigermole-proxy-X.X.X-amd64.deb.sha256
Install via .deb (Ubuntu / Debian — recommended)
sudo dpkg -i tigermole-proxy-X.X.X-amd64.deb
This places the binary at /usr/bin/tigermole-proxy. It does not start anything or register autostart — TigerMole needs a license to run, so the .deb leaves activation to the next step:
tigermole-proxy install
Runtime dependencies (installed automatically by dpkg): libgtk-3-0 and libayatana-appindicator3-1. If either is missing on a minimal system:
sudo apt-get install -y libgtk-3-0 libayatana-appindicator3-1
Install via tarball (other distributions)
tar -xzf tigermole-proxy-X.X.X-linux-x86_64.tar.gz
./tigermole-proxy install
The installation wizard
tigermole-proxy install detects your environment and launches the right wizard: Zenity GUI if DISPLAY/WAYLAND_DISPLAY is set and zenity is available, or the CLI wizard otherwise (servers, SSH, WSL).
Step 1 — License Agreement
A dialog (or CLI prompt) shows the EULA. Accept to continue; cancelling aborts the installation.
Step 2 — License Activation (required)
The wizard prompts for your key and does not let you continue until activation succeeds (or you cancel). The format is key/<base64url-payload>.<base64url-signature>.
The backend is contacted with: your key, a machine fingerprint (v1:SHA256(/etc/machine-id | primary MAC)), an optional owner label, and the platform identifier (linux-x64).
The activated license is encrypted with AES-256-GCM using a key at ~/.local/share/TigerMole/.masterkey (mode 0600).
CLI wizard example
License key (or type 'cancel' to abort): key/AAAA....BBBB
Owner / machine label (optional, Enter to skip): my-laptop
Validating key … OK
✓ License: Team (2/5 seats)
Step 3 — Options
Start automatically at login: if you accept, an XDG entry is written at ~/.config/autostart/tigermole.desktop — your desktop environment launches TigerMole automatically.
Audit encryption key (Team/Custom) — required: if your license is Team or Custom, the wizard requires an X25519 public key to encrypt logs; this step is not skippable. Accepted formats: 32 raw bytes, 64 hex characters, or Base64 of 32 bytes.
Step 4 — Installation
The wizard copies the binary, registers autostart (if requested), configures ANTHROPIC_BASE_URL in ~/.claude/settings.json, activates the license, imports the audit key (if provided), and launches the tray in the background.
Step 5 — Summary
Confirms success and shows the license tier, seat count, the installed binary's path, and how to uninstall.
Non-interactive (scripted) install
To skip the wizard entirely (CI, provisioning), chain the subcommands — this never blocks on a prompt:
set -euo pipefail
sudo dpkg -i tigermole-proxy-X.X.X-amd64.deb
# Activate (REQUIRED — the proxy blocks traffic without it)
tigermole-proxy activate "$TIGERMOLE_LICENSE_KEY"
# Point Claude at the proxy
tigermole-proxy configure
# Team only: import the audit encryption public key
tigermole-proxy import-audit-key /path/to/team.pub
# Start the proxy
tigermole-proxy run &
Don't pipe canned answers into tigermole-proxy install — the wizard insists on the license/key prompts, so a wrong value with closed stdin would hang forever. The explicit activate + configure sequence above is deterministic.
systemd service (recommended for servers)
For long-running processes with no graphical session, register TigerMole as a systemd user service instead of the XDG autostart entry. See the full headless deployment reference for the .service file.
Verifying the installation
tigermole-proxy doctor
tigermole-proxy status
tigermole-proxy license
Expected doctor output:
TigerMole — Installation Health Check
✓ Admin token file
✓ Viewer token file
✓ Proxy reachable on port 9800
✓ ANTHROPIC_BASE_URL in settings.json
✓ Audit directory writable
✓ All checks passed. TigerMole is correctly installed.
Uninstalling
tigermole-proxy uninstall # releases the seat + cleans ~/.local and settings
sudo dpkg -r tigermole-proxy # removes the package (.deb installs)
Troubleshooting
The tray icon does not appear
Make sure your desktop environment supports the StatusNotifierItem / AppIndicator protocol (GNOME Shell may need the AppIndicator extension). Check the process with pgrep -a tigermole-proxy and start it manually with tigermole-proxy tray & if needed.
zenity not found — wizard falls back to CLI
Install zenity for the graphical wizard (sudo apt-get install -y zenity) and re-run tigermole-proxy install.
License activation fails with "Seat limit"
On another machine that has TigerMole installed, run tigermole-proxy deactivate, then retry on the new machine.