Installation

Prerequisites

Before installing Shannon, ensure you have the following prerequisites:

Required

Docker

Shannon runs entirely in Docker containers. Install Docker for your platform:

macOS/Windows: Docker Desktop
Linux: Docker Engine

Verify installation:

docker --version
docker compose version

AI Provider Credentials

Shannon requires access to Claude models. Choose one of the following options:Option 1: Anthropic API (Recommended)

Get your API key from the Anthropic Console
Set ANTHROPIC_API_KEY in your .env file

Option 2: Claude Code OAuth Token

Use your Claude Code OAuth token
Set CLAUDE_CODE_OAUTH_TOKEN in your .env file

Option 3: AWS Bedrock

Configure AWS credentials and Bedrock access
See AWS Bedrock setup below

Option 4: Google Vertex AI

Configure GCP service account with Vertex AI access
See Google Vertex AI setup below

Sufficient Resources

CPU: 4+ cores recommended
RAM: 8GB+ recommended
Disk: 10GB+ free space

Network Access

Internet access for Docker image downloads
Access to target application (can be localhost)
Access to AI provider API endpoints

Installation steps

Clone the repository

Clone Shannon from GitHub:

git clone https://github.com/KeygraphHQ/shannon.git
cd shannon

Configure environment

Create your .env file from the example:

cp .env.example .env

Edit .env and add your credentials:

# Recommended output token configuration
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

# Anthropic API key (recommended)
ANTHROPIC_API_KEY=your-api-key-here

The CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000 setting is recommended for larger tool outputs and better analysis quality.

Prepare repository directory

Create the repos/ directory for target applications:

mkdir -p repos

This is where you’ll clone or symlink the applications you want to test.

Verify installation

Test that Shannon can build and start:

./shannon help

You should see Shannon’s help output with available commands.

Platform-specific instructions

macOS

Install Docker Desktop

Download and install Docker Desktop for Mac.

Configure resources

Open Docker Desktop preferences and allocate:

CPUs: 4 or more
Memory: 8GB or more

Run Shannon

Shannon works out of the box with Docker Desktop installed:

./shannon start URL=https://example.com REPO=your-repo

macOS users can test local applications using host.docker.internal instead of localhost.

Windows

Shannon can run on Windows using either Git Bash or WSL2 (recommended).

WSL2 (Recommended)
Git Bash

Install WSL2

Open PowerShell as Administrator and run:

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

Check installed distributions:

wsl --list --verbose

Install Ubuntu

If you don’t have a distribution installed:

wsl --list --online
wsl --install Ubuntu-24.04

Convert existing WSL1 distributions to WSL2:

wsl --set-version <distro-name> 2

Install Docker Desktop

Download Docker Desktop for Windows
Enable WSL2 backend in Settings > General > “Use the WSL 2 based engine”

Clone and run in WSL

Open WSL terminal:

wsl -d Ubuntu-24.04

Inside WSL:

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

Access Temporal UI

Find your WSL IP address:

ip addr | grep eth0

Navigate to http://<wsl-ip>:8233 in your Windows browser.

Windows Defender may flag exploit code in reports as false positives. Add an exclusion for the Shannon directory in Windows Defender settings.

Install Git for Windows

Download and install Git for Windows which includes Git Bash.

Install Docker Desktop

Download and install Docker Desktop for Windows.

Run Shannon from Git Bash

Open Git Bash and navigate to Shannon:

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

Linux

Install Docker Engine

Follow the official Docker installation guide for your distribution:

Add user to docker group

Avoid needing sudo for Docker commands:

sudo usermod -aG docker $USER
newgrp docker

Verify:

docker run hello-world

Run Shannon

./shannon start URL=https://example.com REPO=your-repo

If you encounter permission issues with output files, ensure your user has access to the Docker socket and is in the docker group.

AI Provider Setup

Anthropic API (Recommended)

The simplest and recommended approach:

Get API key

Sign up at Anthropic Console
Navigate to API Keys
Create a new API key

Configure Shannon

Add to your .env file:

ANTHROPIC_API_KEY=your-api-key
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Rate Limits: Anthropic subscription plans reset usage on a rolling 5-hour window. If you hit rate limits, see the rate limit configuration section.

AWS Bedrock

Route requests through Amazon Bedrock:

Configure AWS credentials

Create a Bedrock bearer token following AWS documentation.

Update .env file

CLAUDE_CODE_USE_BEDROCK=1
AWS_REGION=us-east-1
AWS_BEARER_TOKEN_BEDROCK=your-bearer-token

# Set Bedrock-specific model IDs for your region
ANTHROPIC_SMALL_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0
ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6
ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-6

Run Shannon

./shannon start URL=https://example.com REPO=repo-name

Shannon will automatically use Bedrock for all API calls.

Shannon uses three model tiers: small (Haiku) for summarization, medium (Sonnet) for security analysis, and large (Opus) for deep reasoning. Set model IDs for your specific AWS region.

Google Vertex AI

Route requests through Google Cloud Vertex AI:

Create service account

Go to GCP Console IAM
Create a service account with the roles/aiplatform.user role
Download the JSON key file

Place credentials

mkdir -p ./credentials
cp /path/to/your-sa-key.json ./credentials/gcp-sa-key.json

Update .env file

CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
GOOGLE_APPLICATION_CREDENTIALS=./credentials/gcp-sa-key.json

# Set Vertex AI model IDs
ANTHROPIC_SMALL_MODEL=claude-haiku-4-5@20251001
ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6
ANTHROPIC_LARGE_MODEL=claude-opus-4-6

Run Shannon

./shannon start URL=https://example.com REPO=repo-name

Set CLOUD_ML_REGION=global for global endpoints, or a specific region like us-east5. Some models may not be available on global endpoints — check the Vertex AI Model Garden for availability.

Advanced configuration

Handling rate limits

If using an Anthropic subscription plan, configure extended retry backoff:

configs/my-config.yaml

pipeline:
  retry_preset: subscription          # Extends max backoff to 6h, 100 retries
  max_concurrent_pipelines: 2         # Run 2 of 5 pipelines at a time

Add to your start command:

./shannon start URL=https://example.com REPO=repo-name CONFIG=./configs/my-config.yaml

max_concurrent_pipelines controls how many vulnerability pipelines run simultaneously (1-5, default: 5). Lower values reduce API usage spikes but increase wall-clock time.

Experimental router mode

This feature is experimental and unsupported. Shannon is optimized for Anthropic Claude models. Alternative providers may produce inconsistent results.

Test Shannon with GPT or Gemini models:

Configure provider

Add to .env:

OPENAI_API_KEY=sk-your-key
ROUTER_DEFAULT=openai,gpt-5.2

Run with router

./shannon start URL=https://example.com REPO=repo-name ROUTER=true

Troubleshooting

Repository not found

Error: Repository not found: my-repoSolution: The REPO parameter must be a folder name inside ./repos/, not an absolute path.

# Correct
git clone https://github.com/org/repo.git ./repos/my-repo
./shannon start URL=https://example.com REPO=my-repo

# Or symlink
ln -s /path/to/existing/repo ./repos/my-repo

Temporal not ready

Error: Connection errors or “Temporal not ready”Solution: Wait for health check or check logs:

docker compose logs temporal

Temporal can take 30-60 seconds to fully initialize on first start.

Worker not processing

Error: Workflow starts but never progressesSolution: Check container status:

docker compose ps

Ensure the worker container is running. Restart if needed:

./shannon stop
./shannon start URL=https://example.com REPO=repo-name

Local apps unreachable

Error: Cannot connect to localhost:3000Solution: Docker containers can’t reach host’s localhost. Use host.docker.internal:

./shannon start URL=http://host.docker.internal:3000 REPO=repo-name

This works on macOS and Windows. On Linux, configure Docker network or use host network mode.

Permission errors (Linux)

Error: Permission denied errors with Docker or output filesSolution: Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

For output file permissions, ensure proper ownership:

sudo chown -R $USER:$USER audit-logs/

Rate limit errors

Error: 429 Rate Limit errors from AnthropicSolution: Configure extended retry and reduce concurrency:

configs/my-config.yaml

pipeline:
  retry_preset: subscription
  max_concurrent_pipelines: 2

Then run:

./shannon start URL=https://example.com REPO=repo-name CONFIG=./configs/my-config.yaml

Clean state reset

Error: Need to completely reset Shannon stateSolution: Full cleanup removes all containers, volumes, and data:

./shannon stop CLEAN=true

This will delete all workflow data, audit logs, and Docker volumes.

Next steps

Quickstart

Run your first pentest with Shannon

Configuration

Configure authentication, 2FA, and testing parameters

Architecture

Learn how Shannon’s multi-agent system works

CLI Reference

Complete command-line interface documentation

Get Started

Core Concepts

Guides

CLI Reference

Prerequisites

Required

Recommended

Sufficient Resources

Network Access

Installation steps

Platform-specific instructions

macOS

Windows

Linux

AI Provider Setup

Anthropic API (Recommended)

AWS Bedrock

Google Vertex AI

Advanced configuration

Handling rate limits

Experimental router mode

Troubleshooting

Next steps

Quickstart

Configuration

Architecture

CLI Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Reference

​Prerequisites

​Required

​Recommended

Sufficient Resources

Network Access

​Installation steps

​Platform-specific instructions

​macOS

​Windows

​Linux

​AI Provider Setup

​Anthropic API (Recommended)

​AWS Bedrock

​Google Vertex AI

​Advanced configuration

​Handling rate limits

​Experimental router mode

​Troubleshooting

​Next steps

Quickstart

Configuration

Architecture

CLI Reference

Build docs developers (and LLMs) love

Prerequisites

Required

Recommended

Installation steps

Platform-specific instructions

macOS

Windows

Linux

AI Provider Setup

Anthropic API (Recommended)

AWS Bedrock

Google Vertex AI

Advanced configuration

Handling rate limits

Experimental router mode

Troubleshooting

Next steps