Build and Run an Autonomous Pentesting Legion with sapper-v2

What is sapper-v2?

sapper-v2 is an autonomous, multi-agent system designed for authorized penetration testing. Instead of relying on one increasingly complex agent, it organizes multiple AIs into a legion that divides work, communicates discoveries, and preserves knowledge across agent replacements.

The project won the online qualifier of the third Tencent Cloud Intelligent Attack-Defense Challenge and received First Prize in the GeekCon 2026 AI Challenge. In the Tencent event, it completed an eight-hour unattended run with a score of 80.18, finding 85 flags while using approximately one billion tokens.

Use sapper-v2 only on systems you own or have explicit permission to test. Review DISCLAIMER.md before installation or operation.

How the system works

The project is built around three foundational capabilities:

• Create: The system opens new AI sessions in tmux, allowing it to create specialist workers as tasks demand.
• Language: Agents communicate by entering messages into one another's input sessions.
• History: Findings are stored in a layered fact-intent graph rather than being left inside one agent's context.

The history system has three layers: title, summary, and evidence document. Agents can read a compact title first, inspect the summary when more context is needed, and open the evidence for detailed verification. This design reduces context consumption and limits the damage caused by an inaccurate fact.

The runtime roles

At runtime, sapper-v2 separates coordination, execution, and availability:

• Commander: Reads the board, evaluates targets, and dispatches work. It does not execute attacks itself.
• Generals: Handle difficult assaults and can recruit their own squads.
• Scouts: Perform short reconnaissance and help determine whether a target needs mass execution or deeper investigation.
• Soldiers: Work in parallel on assigned tasks.
• Signalman: Collects and submits unreported flags from one place, a role that emerged during operation rather than being pre-coded.
• Watchdog: A strategy-free script that keeps the system alive by restarting a crashed commander with --continue, rotating keys, and handling end-of-run wrap-up.

The README describes three visible runtime windows: the commander, the AI legion running in tmux panes, and the watchdog.

Key features

• Parallel division of labor: Scouts, soldiers, generals, and the commander operate with distinct responsibilities.
• Persistent organizational memory: Knowledge survives when an individual agent is replaced.
• Context rotation: Agents whose contexts become saturated can leave written lessons for successors.
• Model tiering: The competition configuration used GLM-5.3 for the commander and generals, and DeepSeek V4.1 Flash for scouts and soldiers.
• Operational resilience: The watchdog can restart the commander, rotate keys, and preserve continuity without making strategic decisions.
• Cross-challenge transfer: The commander can identify structurally similar challenge families and pass successful playbooks to newly assigned agents.
• Fact-intent CLI: The project provides commands and guidance for operating its graph and running multi-challenge workflows.

Install the sapper CLI

The quick-start installer links the sapper CLI into place. According to the README, the CLI uses only the standard library and has no additional dependencies.

From the repository root, run:

bash install.sh

The README does not list additional local prerequisites or platform-specific installation steps. If the command does not make sapper available in your shell, inspect install.sh and confirm that its symlink destination is included in your executable path.

Start an authorized assessment

Create a new assessment with sapper setup. The following example is taken from the project's quick start:

sapper setup --goal "assess http://target" --agents

Replace http://target only with an endpoint covered by your written authorization. The goal should clearly describe the approved scope so that the agents receive an unambiguous mission.

The --agents option starts the agent-oriented workflow shown by the project. After setup, inspect the board and current frontier:

sapper status

The status view is the primary quick-start command for checking how work is progressing. The commander uses the board to judge targets and dispatch specialists rather than performing assessment tasks directly.

A minimal CLI workflow

1. Verify authorization: Document the target, time window, approved techniques, and stop conditions outside the tool.
2. Install the CLI: Run bash install.sh from the cloned repository.
3. Define the goal: Run sapper setup --goal "assess http://target" --agents with an approved target.
4. Monitor the board: Run sapper status to review the board and frontier.
5. Review retained knowledge: Use the fact-intent workflow documented in SKILL.md when you need single-graph operations or multi-challenge sweeps.

Run the full legion with Docker

The repository includes a Dockerfile for the full commander-based legion. Build the image from the repository root:

docker build -f docker/Dockerfile.commander -t sapper:latest .

Before starting the container, configure the model gateways, key pool, and budget environment variables described in docker/ENV.md. These settings are important because the architecture assigns different responsibilities to different model tiers and includes key rotation and budget-aware operation.

The README presents the container launch in schematic form:

docker run -d --name sapper ... sapper:latest

The ellipsis is not a literal ready-to-run argument. Replace it with the required environment variables and other Docker options from the repository's environment documentation. Do not guess production credentials or place secrets directly in shell history when a safer secret-management method is available.

Understand the commander's doctrine

The commander's operational doctrine is stored in docker/commander/SKILL.md. The README highlights several principles:

• Easy-first parallel scheduling: Dispatch work so that tractable targets can be solved concurrently rather than forcing the entire legion through one difficult path.
• Bottleneck-time salvage: Near the end of an operation, revisit partially solved targets where existing evidence may produce results quickly.
• Stop-loss discipline: Avoid spending unlimited time or tokens on work that is not producing progress.
• Role separation: Preserve the commander's attention for board reading, judgment, and dispatch instead of direct execution.

For the formal architecture contract, read docker/commander/SPEC.md. For a retrospective explaining how the system behaved during competition, consult BATTLE-REPORT.md.

Advanced operating tips

Write goals that match the authorized scope

The setup goal becomes the mission agents work toward. State the approved target precisely and avoid broad wording that could be interpreted as permission to explore unrelated hosts or services. External authorization documents remain the source of truth.

Use layered evidence instead of oversized summaries

Keep high-level facts concise while retaining detailed evidence beneath them. The title should communicate the gist, the summary should explain relevance, and the evidence document should support verification. This follows sapper-v2's design and avoids repeatedly loading every detail into agent context.

Preserve lessons during agent rotation

The project measured soldier context saturation at roughly 260,000 tokens during its campaign. Its response was to recycle the worker while leaving a playbook for the successor. When reviewing operation output, favor explicit handover notes containing verified findings, attempted approaches, unresolved questions, and reusable procedures.

Separate strategy from availability

The watchdog deliberately has no strategic role. Keep recovery behavior, key rotation, and process restarts distinct from decisions about targets and tactics. This makes it easier to understand whether an action came from the commander or from keep-alive automation.

Control token and model costs

sapper-v2's competition architecture assigned stronger models to high-level decision-making and lighter models to high-volume reconnaissance and execution. If you reproduce the documented configuration, set gateways, key pools, and budgets through the Docker environment guidance and monitor consumption throughout the authorized run.

Inspect evidence before trusting transferred knowledge

Cross-challenge transfer can accelerate work when targets share a structure, but similarities should not replace verification. Use the layered graph to inspect summaries and supporting evidence before applying an inherited playbook to another challenge.

Safety and responsible use

sapper-v2 is an offensive security tool and must not be used for unauthorized access. Its README explicitly warns that AI can amplify the harm caused by offensive tooling. Follow applicable law, obtain explicit permission, constrain the target scope, establish budget and stop conditions, and retain human oversight appropriate to the environment.

The project also proposes a future taggant mechanism: markings coupled to an offensive harness that could leak identifying information to victims during illegal intrusions and support attribution. The README presents this as a proposal requiring cryptographic and community design, not as an existing protection that users can rely on today.

Conclusion

sapper-v2 demonstrates a cooperative approach to autonomous security assessment: a commander delegates work, specialists operate in parallel, a watchdog maintains continuity, and a layered fact graph preserves organizational knowledge. Start with the lightweight CLI, monitor the board with sapper status, and use the Docker setup when you need the full legion. Always keep every run within explicit authorization and the project's disclaimer.