Platforms & Networking

This guide covers platform-specific notes and Docker networking behavior.

Windows

Shannon on Windows is supported through WSL2. Native Windows, including Git Bash, is not supported: the CLI refuses to start there and points you to this guide. WSL2 is unaffected.

Ensure WSL2

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

# Check installed distros.
wsl --list --verbose

# If you do not have a distro, install one.
wsl --list --online
wsl --install Ubuntu-24.04

# If your distro shows VERSION 1, convert it to WSL2.
wsl --set-version <distro-name> 2

Install Docker Desktop on Windows and enable the WSL2 backend under Settings > General > Use the WSL 2 based engine.

Run Shannon inside WSL:

npx (recommended)

npx @keygraph/shannon setup
npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo

Build from source

git clone https://github.com/KeygraphHQ/shannon.git
cd shannon
cp .env.example .env
pnpm install
pnpm build
./shannon start -u https://your-app.com -r /path/to/your-repo

To open the Temporal Web UI, navigate to http://localhost:8233 in your Windows browser. Shannon publishes the UI on the loopback address only, so use localhost rather than your WSL IP address.

Note

Windows Defender may flag exploit code in reports as false positives. Add an exclusion for the Shannon directory or use Docker/WSL2 isolation.

Linux

Linux works with native Docker. Depending on your Docker setup, you may need sudo. If output files have permission issues, ensure your user has access to the Docker socket and workspace directory.

macOS

macOS works with Docker Desktop installed.

Testing local applications

Docker containers cannot reach localhost on your host machine. Use host.docker.internal instead. The same applies to a local model server such as Ollama, LM Studio, or vLLM:

npx (recommended)

npx @keygraph/shannon start -u http://host.docker.internal:3000 -r /path/to/repo

Build from source

./shannon start -u http://host.docker.internal:3000 -r /path/to/repo

Custom hostnames

If your local stack uses custom hostnames mapped in /etc/hosts, Shannon forwards those entries into the worker container at scan start.

To disable forwarding:

export SHANNON_FORWARD_HOSTS=false

In source-build mode, you can also add this to .env:

SHANNON_FORWARD_HOSTS=false