Build from source & CLI

This guide covers the source-build workflow, common CLI commands, repository paths, and output locations. For the fastest first run, use the npx workflow in the Quick Start.

Throughout this site, command examples are shown as tabs. Pick npx or Build from source once and your choice is remembered on every page.

Prerequisites

Docker
Node.js 18+
pnpm
AI provider credentials

Clone and build

Use the source-build workflow if you want to run Shannon from a local clone, modify the open-source CLI, or keep the worker image built locally.

Clone Shannon:

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

Configure credentials:
Terminal window
```
cp .env.example .env
```
Install dependencies and build:
Terminal window
```
pnpm install
pnpm build
```

Run a pentest:

./shannon start -u https://your-app.com -r /path/to/your-repo

At minimum, your .env file should include one supported AI provider credential:

ANTHROPIC_API_KEY=your-api-key
CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

Environment variables can also be exported directly:

export ANTHROPIC_API_KEY="your-api-key"
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

See AI Providers for Bedrock, Vertex AI, and custom endpoint setup.

Prepare your repository

Shannon can scan any repository on your machine. Pass an absolute or relative path with -r. The target repository is mounted read-only inside the worker container.

npx (recommended)
Build from source

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

./shannon start -u https://example.com -r ./relative/path

Common commands

Monitor progress:

npx (recommended)
Build from source

npx @keygraph/shannon logs <workspace>
npx @keygraph/shannon status

./shannon logs <workspace>
./shannon status

Open the Temporal Web UI for detailed monitoring:

open http://localhost:8233

Stop Shannon:

npx (recommended)
Build from source

npx @keygraph/shannon stop
npx @keygraph/shannon stop --clean       # confirms first; add --yes (or -y) to skip
npx @keygraph/shannon uninstall          # confirms first; add --yes (or -y) to skip

./shannon stop
./shannon stop --clean                   # confirms first; add --yes (or -y) to skip

# Basic pentest.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo

# With a configuration file.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml

# Custom output directory.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -o ./my-reports

# Named workspace.
npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w q1-audit

# List all workspaces.
npx @keygraph/shannon workspaces

./shannon start -u https://example.com -r /path/to/repo
./shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml
./shannon start -u https://example.com -r /path/to/repo -o ./my-reports
./shannon start -u https://example.com -r /path/to/repo -w q1-audit
./shannon workspaces

# Rebuild the worker image.
./shannon build --no-cache

See the CLI reference for the full list of commands and flags.

Output and results

Results are saved to the workspaces directory:

./workspaces/ in source-build mode
~/.shannon/workspaces/ in npx mode

Use -o <path> to copy deliverables to a custom output directory after a run completes.

Output structure. The run directory’s top level holds only the final report; everything else is nested under a hidden .shannon/ directory:

workspaces/{hostname}_{sessionId}/
|-- Security-Assessment-Report.md   # the final report (the deliverable)
`-- .shannon/                       # internals
    |-- deliverables/               # report source, per-phase analysis, queues
    |-- agents/                     # per-agent logs
    |-- prompts/                    # rendered prompts
    |-- scratchpad/                 # screenshots, scripts
    |-- session.json                # resume state
    `-- workflow.log

For workspace naming and resuming interrupted runs, see Workspaces & Resuming.