Installation

Prerequisites

Run red-run in a dedicated VM, not on your daily driver. red-run is designed so Claude never needs sudo, but it still runs offensive tools, opens listeners, and makes network connections to targets — you want that happening in an isolated environment. A standard pentesting VM (Kali, Parrot, or a minimal Debian/Ubuntu with your tools) works fine.

red-run requires the following installed:

Requirement	Purpose	Install
Claude Code	CLI host for skills, agents, and MCP servers	See Claude Code install docs
uv	Python package manager for MCP servers	See uv install docs
Docker	Containerized nmap and pentest toolbox	See Docker install docs

Optional: C2 Framework

red-run works out of the box with shell-server (raw TCP reverse shells + interactive processes). For C2 integration, install the framework separately:

C2	Components	Install
Sliver	Server + Client	See below

Sliver install — two deployment models depending on whether the Sliver server runs on the same box as red-run or on a dedicated C2 host.

Local (server + client on the same box)

Step 1 — Download binaries:

# Server (~260MB) — runs the daemon, generates operator configs
curl -L https://github.com/BishopFox/sliver/releases/latest/download/sliver-server_linux-amd64 \
  -o ~/.local/bin/sliver-server && chmod +x ~/.local/bin/sliver-server

# Client (~38MB) — implant generation, interactive console
curl -L https://github.com/BishopFox/sliver/releases/latest/download/sliver-client_linux-amd64 \
  -o ~/.local/bin/sliver && chmod +x ~/.local/bin/sliver

Step 2 — Unpack assets (downloads Go toolchain + implant templates, ~1–2 min on first run):

sliver-server unpack --force

Step 3 — Start the daemon:

sliver-server daemon &

Wait a few seconds for it to initialize. Verify with pgrep -f "sliver-server daemon".

Step 4 — Run config.sh and select sliver as the shell backend:

cd /path/to/red-run
./config.sh

It will prompt you to generate an operator config (how the red-run MCP server authenticates to the daemon). If the daemon is running, it handles everything.

Remote (server on a dedicated C2 host)

Only the sliver client is needed on the red-run box. The server runs elsewhere.

On the red-run box — install the client:

curl -L https://github.com/BishopFox/sliver/releases/latest/download/sliver-client_linux-amd64 \
  -o ~/.local/bin/sliver && chmod +x ~/.local/bin/sliver

On the C2 host — generate an operator config for red-run:

sliver-server operator --name red-run --lhost <C2_IP> \
  --permissions all --save red-run.cfg

Copy red-run.cfg to the red-run box as engagement/sliver.cfg, then run ./config.sh.

Notes

Both setups need the sliver client on the red-run box for implant generation. The sliver-server binary is only needed where the daemon runs. config.sh detects engagement/sliver.cfg automatically — no manual config edits needed.

More C2 frameworks (Mythic, Havoc) planned. Custom C2 integration is supported via operator-provided MCP servers and reference docs.

Install

git clone https://github.com/blacklanternsecurity/red-run.git
cd red-run
./install.sh

What install.sh does

The installer runs five steps:

1. Native skills — Installs orchestrator skills to ~/.claude/skills/red-run-ctf/ (agent teams, default) and ~/.claude/skills/red-run-legacy/ (subagent-based). All other skills (67 discovery + technique skills) are served on-demand via the MCP skill-router.

2. Teammate templates — Teammate spawn prompts live in teammates/ in the repo (not installed globally). The legacy subagent definitions in agents/ are only installed with --legacy.

3. MCP server dependencies — Runs uv sync for all 6 MCP servers (skill-router, nmap-server, shell-server, state-server, browser-server, rdp-server) to install Python dependencies into isolated .venv/ directories.

4. Docker images — Builds two Docker images:

• red-run-nmap:latest — Alpine + nmap for containerized scanning
• red-run-shell:latest — Tools that need persistent sessions or raw sockets (evil-winrm, impacket, chisel, ligolo-ng, socat, Responder, mitm6, tcpdump)

5. Skill indexing — Runs the ChromaDB indexer to embed all skills for semantic search. Downloads the all-MiniLM-L6-v2 embedding model (~80MB) on first run.

6. Browser setup — Installs Chromium via Playwright (~150MB) for headless browser automation.

7. Config verification — Checks that .mcp.json and .claude/settings.json are properly configured.

Attackbox dependencies

The installer sets up red-run itself, but skills also depend on standard pentesting tools installed on the attackbox (nmap, ffuf, sqlmap, hashcat, impacket, git-dumper, etc.). After installing, run the preflight check:

bash preflight.sh

Preflight verifies that required tools are in $PATH and reports missing ones with install commands. See dependencies for the full list organized by category.

Symlink vs copy mode

./install.sh          # Default: symlinks (edits in repo reflect immediately)
./install.sh --copy   # Copies (snapshots skills and agents into ~/.claude/)

Symlink mode is recommended — changes to skills and agents in the repo take effect immediately without re-running the installer. Copy mode snapshots the files, so you need to re-run the installer to pick up changes.

Both modes require the repo directory to stay in place. MCP servers run from tools/ and the skill-router reads skill files from skills/ at runtime.

Hardening with permission denies

red-run is designed so Claude never needs sudo — nmap and Responder run inside Docker containers, and system changes like /etc/hosts are hard stops that require operator action. You can enforce this by denying sudo in ~/.claude/settings.json:

{
  "permissions": {
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf *)",
      "Bash(rm -fr *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

The Bash(sudo *) rule makes Claude Code refuse any Bash command starting with sudo. The other rules block common destructive commands. See the Trail of Bits Claude Code hardening guide for the full recommended configuration.

Running

Quick start (shell-server only)

cd red-run
./run.sh

run.sh starts shell-server, launches Claude Code, and auto-triggers /red-run-ctf. The orchestrator asks config questions (scan type, proxy, etc.) on first run. Give it a target IP to begin.

With C2 (Sliver or custom)

cd red-run
bash config.sh             # config wizard — picks C2 backend, patches .mcp.json
./run.sh                   # starts C2 daemon + MCP, launches Claude Code

config.sh is optional if you're using shell-server only. Required if you want a C2 backend — it generates operator configs, registers the C2 MCP server, and writes engagement/config.yaml so the orchestrator skips its built-in wizard.

Flags

./run.sh --lead=legacy  # use /red-run-legacy instead
./run.sh --yolo         # skip permission prompts

If shell-server has active sessions from a previous run, run.sh prompts to keep, clear, or restart them.

Uninstall

./uninstall.sh

This removes:

• Native skills from ~/.claude/skills/red-run-*/
• Legacy subagents from ~/.claude/agents/ (if installed)
• ChromaDB index (tools/skill-router/.chromadb/)
• Python venvs (tools/*/. venv/)
• Docker images (red-run-nmap:latest, red-run-shell:latest)

It does not remove .mcp.json or .claude/settings.json (project config), and it does not touch the engagement/ directory.

Troubleshooting

Docker not available

WARNING: Docker required for nmap MCP server but not available.

Install Docker and ensure the daemon is running. The nmap-server and shell-server privileged mode require Docker. The rest of the toolkit works without it.

Broken symlinks

ERROR: Broken skill: ~/.claude/skills/red-run-ctf/SKILL.md -> unknown

The repo directory was moved or deleted after install. Either move it back or re-run ./install.sh.

Missing uv

ERROR: uv is required but not found.

See uv install docs.

Embedding model download fails

The skill-router downloads all-MiniLM-L6-v2 on first run. If your VM lacks internet access, download the model elsewhere and set HF_HUB_OFFLINE=1 (already set in .mcp.json for runtime). For initial indexing, internet access is required.

Chromium install fails

If playwright install chromium fails behind a proxy, download Chromium manually. See Playwright docs for proxy configuration.

MCP servers not starting

Verify .mcp.json exists in the repo root and .claude/settings.json has enableAllProjectMcpServers: true. Check server logs with:

uv run --directory tools/skill-router python server.py  # Should start without errors