Skip to main content
Shannon is designed to work across multiple platforms. This guide covers platform-specific setup instructions and considerations.

​
Windows

Windows users have two options for running Shannon: native Git Bash or WSL2 (recommended).

​
Option 1: Native (Git Bash)

1

Install Git for Windows

Download and install Git for Windows.
2

Install Docker Desktop

Download and install Docker Desktop for Windows.
3

Run from Git Bash

Open Git Bash and navigate to the Shannon directory:
cd /path/to/shannon
./shannon start URL=https://example.com REPO=repo-name
WSL2 provides better performance and compatibility for Shannon.
1

Ensure WSL 2 is installed

Open PowerShell as Administrator and run:
wsl --install
wsl --set-default-version 2
Check installed distributions:
wsl --list --verbose
2

Install a Linux distribution

If you don’t have a distribution installed, install Ubuntu 24.04 (recommended):
wsl --list --online
wsl --install Ubuntu-24.04
If your existing distribution shows VERSION 1, convert it to WSL 2:
wsl --set-version <distro-name> 2
See WSL basic commands for reference.
3

Install Docker Desktop

Install Docker Desktop on Windows and enable the WSL2 backend:
  1. Go to Settings > General
  2. Enable Use the WSL 2 based engine
4

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
5

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

​
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.
Solution: Add an exclusion for the Shannon directory in Windows Defender:
  1. Open Windows Security
  2. Go to Virus & threat protection > Manage settings
  3. Under Exclusions, click Add or remove exclusions
  4. Add the Shannon directory as an exclusion
Alternatively, run Shannon inside Docker/WSL2 to isolate the files from Windows Defender.

​
Linux

Shannon works natively on Linux with Docker installed.
1

Install Docker

Follow the Docker installation guide for your Linux distribution.
2

Configure Docker permissions (optional)

You may need to run commands with sudo depending on your Docker setup. To avoid using sudo, add your user to the docker group:
sudo usermod -aG docker $USER
Log out and back in for the changes to take effect.
3

Run Shannon

git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
cp .env.example .env  # Edit with your API key
./shannon start URL=https://example.com REPO=repo-name
If you encounter permission issues with output files, ensure your user has access to the Docker socket and the necessary file permissions.

​
macOS

macOS works out of the box with Docker Desktop installed.
1

Install Docker Desktop

Download and install Docker Desktop for Mac.
2

Run Shannon

git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
cp .env.example .env  # Edit with your API key
./shannon start URL=https://example.com REPO=repo-name

​
Testing Local Applications

When testing applications running on your local machine, Docker containers cannot reach localhost directly.
Solution: Use host.docker.internal in place of localhost in your URLs.

​
Example

If your application runs on http://localhost:3000, use: 
./shannon start URL=http://host.docker.internal:3000 REPO=repo-name
This applies to all platforms (Windows, Linux, macOS) when using Docker.

​
Platform Summary

PlatformRecommended SetupDocker Access
WindowsWSL2 + Docker DesktopNative in WSL2
LinuxNative DockerNative or sudo
macOSDocker DesktopNative
All platforms support the host.docker.internal hostname for accessing local applications.

Build docs developers (and LLMs) love

Get started for freeTalk to us