Skip to main content
Shannon works on all major platforms, but each has specific setup requirements.

​
Windows

Windows users have two options: WSL2 (recommended) or Git Bash (native). WSL2 provides the best experience for running Shannon on Windows.
1

Ensure WSL 2 is installed

wsl --install
wsl --set-default-version 2
2

Check installed distributions

wsl --list --verbose
3

Install a distribution (if needed)

# List available distributions
wsl --list --online

# Install Ubuntu 24.04 (recommended)
wsl --install Ubuntu-24.04
4

Convert to WSL 2 (if needed)

If your distribution shows VERSION 1, convert it:
wsl --set-version <distro-name> 2
5

Install Docker Desktop

  1. Download and install Docker Desktop for Windows
  2. Open Docker Desktop settings
  3. Navigate to Settings > General
  4. Enable “Use the WSL 2 based engine”
  5. Apply and restart
6

Clone and run Shannon inside WSL

Open a WSL terminal by typing wsl -d <distro-name> in PowerShell or CMD:
# Inside WSL terminal
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
cp .env.example .env  # Edit with your API key
./shannon start URL=https://your-app.com REPO=your-repo
7

Access Temporal Web UI

To access the Temporal Web UI from Windows:
  1. Run ip addr inside WSL to find your WSL IP address
  2. Navigate to http://<wsl-ip>:8233 in your Windows browser
See WSL basic commands for reference.

​
Git Bash (Native)

For a native Windows experience without WSL:
1

Install Git for Windows

Download and install Git for Windows
2

Install Docker Desktop

Download and install Docker Desktop for Windows
3

Run Shannon from Git Bash

Open Git Bash and run:
git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
cp .env.example .env
./shannon start URL=https://your-app.com REPO=your-repo

​
Windows Antivirus False Positives

Windows Defender may flag files in xben-benchmark-results/ or deliverables/ as malware. These are false positives caused by exploit code in the reports.
Solutions:
  1. Add an exclusion for the Shannon directory in Windows Defender
  2. Use Docker/WSL2 for better isolation
  3. Manually restore quarantined files from Windows Security

​
Linux

Linux users can run Shannon natively with Docker installed.
1

Install Docker

Follow the official Docker installation guide for Linux
2

Configure Docker permissions (if needed)

You may need to run commands with sudo or add your user to the docker group:
sudo usermod -aG docker $USER
newgrp docker
3

Clone and run Shannon

git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
cp .env.example .env
./shannon start URL=https://your-app.com REPO=your-repo

​
Permission Issues

If you encounter permission issues with output files:
  1. Option A: Add your user to the docker group (recommended) 
    sudo usermod -aG docker $USER
newgrp docker
  2. Option B: Run Shannon with sudo 
    sudo ./shannon start URL=https://example.com REPO=repo-name
  3. Option C: Fix permissions on output directories 
    sudo chown -R $USER:$USER audit-logs/

​
macOS

macOS provides the smoothest experience with Docker Desktop.
1

Install Docker Desktop

Download and install Docker Desktop for Mac
2

Clone and run Shannon

git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
cp .env.example .env
./shannon start URL=https://your-app.com REPO=your-repo
macOS works out of the box with Docker Desktop installed. No additional configuration needed.

​
Platform Comparison

PlatformSetup ComplexityPerformanceRecommended
macOS⭐ EasyExcellent✅ Yes
Windows (WSL2)⭐⭐ ModerateVery Good✅ Yes
Linux⭐ EasyExcellent✅ Yes
Windows (Git Bash)⭐⭐ ModerateGood⚠️ WSL2 preferred

​
Testing Local Applications

All platforms support testing local applications using host.docker.internal: 
./shannon start URL=http://host.docker.internal:3000 REPO=repo-name
See Testing Local Applications for detailed instructions.

Build docs developers (and LLMs) love

Get started for freeTalk to us