Installation

Installation

🇫🇷 Version française : Installation (FR)

macOS (Apple Silicon) — recommended

1. Download Snitch-1.0.0-macos-arm64.zip (212 MB) from the releases page.
2. Unzip and drag Snitch.app to /Applications.
3. The build is unsigned (no Apple Developer certificate). macOS will block it on first open:
   • Right-click the app → Open → confirm Open in the dialog, or
   • System Settings → Privacy & Security → Open Anyway.
4. Live packet capture needs elevated privileges — the app asks for your password (sudo) once when capture starts. This is inherent to libpcap/BPF, same as Wireshark or Little Snitch.

Just want a look? Snitch has a demo mode (SNITCH_DEMO=1) with synthetic traffic — no root required. See Usage Guide.

Linux — Docker

The Docker deployment is for Linux: capture works via network_mode: host, so the container sees real host traffic.

git clone https://github.com/aixisstudio/Snitch.git snitch
cd snitch
sudo docker compose up --build

Then get the API token (printed once in the backend logs, or cat data/api_token.txt) and open http://localhost:8000/?token=TOKEN in your browser.

Background mode: sudo docker compose up -d --build

Docker limitations

• Process attribution is limited to container processes (host PIDs are not shared by default).
• The LAN scanner may be unavailable on some network configurations.
• ⚠️ Docker Desktop on macOS/Windows runs inside a VM and cannot capture host traffic — use the native app on those platforms.

Windows — build from source

Requirements: Python 3.11+, Node.js 18+, Npcap installed, and an Administrator terminal (raw packet capture needs it).

# Backend — API at http://127.0.0.1:8000
cd backend
pip install -r requirements.txt
python run_backend.py   # prints the API token once

# Frontend (separate terminal) — UI at http://localhost:5173/?token=TOKEN
cd frontend
npm install
npm run dev

# Electron (optional, admin terminal) — token injected automatically
cd electron
npm install
set VITE_DEV=1
npx electron .

Build the macOS installer yourself

# 1 — Compile the backend (PyInstaller)
cd backend
pip install pyinstaller
pyinstaller backend.spec --distpath ../dist/backend

# 2 — Build the frontend
cd frontend
npm run build

# 3 — Build the Electron app
cd electron
npm run build:dir

Output: dist/installer/mac-arm64/Snitch.app.

Where your data lives

Path	Contents
~/Library/Application Support/Snitch/ (macOS) or data/	SQLite DB (snitch.db), logs, api_token.txt, extracted GeoIP DBs

Everything stays on your machine — see Security & Privacy.