Get started

A first swarm in five minutes, a first case after that.

Everything below runs on your own machine, free, under the GNU AGPL. The first run costs a few cents on a cloud model or nothing on a local one. Nothing here needs an account with us.

Get the source The same guide in the repository

The route

1What you needthree tools, all of them free
2A first swarmabout five minutes
3Your first caseyour own evidence

Every command on this page is in the repository's quick start, and it is what the published cases were started with.

What you need

Three things, all of them free.

Nothing here is bundled and nothing here is ours to license. Install the three, check each one with the line under it, and the harness runs as it is.

1The runtime

Node 22.6 or newer, with zsh, jq, python3 and curl. The scripts run as they are, with no build step.

Checknode --version && zsh --version && jq --version

2The panes and the agent

Herdr gives each agent a terminal pane. Pi is the agent inside it. Each installs with one line.

Checkherdr --version && pi --version

3A model

An API key, a Claude or ChatGPT subscription logged into Pi once with pi /login, or a model served from this machine. The harness passes no credential to the panes.

Checkpi auth check --model provider/id

On this host

Held by the kernel on both platforms, with one exception.

The columns name the mechanism, so you can go and check it. The exception is the egress allowlist on macOS: there the guard is a proxy the panes are pointed at, and a process that ignores it reaches the network. The kickoff line and the report both name it.

GuardmacOSLinux

Evidence read-only--inputs, --inputs-bind

sandbox-exec holds the copy read-only in every pane.

A read-only bind inside the namespace, or a Landlock rule on the resolved path.

Quarantine--quarantine

Nothing extracted from the evidence can execute.

Mounted noexec, or the execute right withheld under Landlock.

Write allowlist--rw

An agent writes where the run says it may, and nowhere else.

Landlock inside a user namespace. Bubblewrap adds a read-only root when present.

Clean room for a re-run--no-read

A previous run's findings on the same evidence stay unreadable.

A tmpfs over the directory, or Landlock denies the reads.

Egress allowlistthe model providers, and what a case adds

AdvisoryA proxy the panes are pointed at. A process that ignores it reaches the network.

No route at all except the proxy's socket, so there is nothing to ignore.

Terminal socket seal--no-socket

The multiplexer that owns the other panes is out of reach.

Masked inside a user namespace. Without one the record says it was unenforced.

The record says what your host could holdThe kickoff measures this machine once, prints one line per guard, and writes the answer into the run record and the report's custody section. A host that lacks a guard still runs, and the record names what it lacked rather than claiming the seal. There is nothing to configure and nothing to install for any of it.

The first five minutes

Install, prove the protocol, run two agents, open the console.

Install

# Herdr, with its Pi integration
curl -fsSL https://herdr.dev/install.sh | sh
herdr integration install pi

# Pi
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# DFIR Swarm
git clone https://github.com/halilozturkci/dfirswarm && cd dfirswarm
npm install

Log Pi into a provider once with pi /login. The harness reads Pi's own store and never hands a key to a pane.

Prove the protocol with no model, no key, no network

# two scripted workers: a claim conflict, a blocked write,
# a detected shell write, the sentinel
npm test

# the finish line's certification, the reaper, the egress guard,
# the guards this host can enforce
npm run test:bash

The guard suites skip themselves with a message on a host that cannot enforce a guard, so what passes here is what your machine can hold.

Run two agents on the hello goal

# Herdr must be running: open the app, or `herdr server` in another terminal
scripts/swarm.sh start --model deepseek/deepseek-v4-pro --cap-usd 1 --n 2 \
  --goal-file prompts/goals/hello.md

The goal is a markdown file with its own ## Definition of done and ## Checks; a goal without one does not start. The kickoff prints the run id, the sandbox path, the three commands to watch, check and stop, and one line per guard saying what this host could enforce. A two-agent hello run costs a few cents on a cloud model and finishes in a minute or two.

scripts/swarm.sh status <id>
scripts/swarm.sh stop <id>

Free instead: a model on your own machine, with a token cap in place of the dollar cap and --local-only to shut the network to everything but it. The runs that proved it are in the repository's verified-runs page.

Open the console

# http://<this-machine>:43173, on the LAN by design
scripts/swarm.sh ui

Watching is open to anyone on the LAN; starting, stopping and restoring need the token the server prints at startup. The New swarm form starts a run the same way the command line does, with the goal document first and its finish line read back before a model is chosen.

The goal tab of a run: the command it was started with, the frame it ran under, and the goal document with its checks — How a run was started, as the console keeps it: the command, the evidence and sandbox paths, the frame it ran under, and the goal with its checks.

Or start it from the console

The same kickoff, as a form.

Everything the command line takes, the console's New swarm form takes too, and it runs the same swarm.sh start underneath. The screens below are the console on a first case, filled in the order the form asks.

The console overview with the New swarm button in the header — **1 · Open the console and press New swarm.** The overview lists every run in this registry with its finish line, its spend against the cap and how long it took; the button in the header opens the kickoff form.

The kickoff form: the goal library, the goal document, and the finish line read back beside it — **2 · Write the goal, or load a saved one.** The goal is the contract: it becomes `SWARM.md` and the agents cannot rewrite it. As you type, the panel beside it reads the finish line back: definition of done present, the checks it found, whether they read `work/`. A goal without a finish line is refused here as well as at kickoff.

The team card: one model or a mixed team, the agent count, and provider readiness from pi auth check — **3 · Pick the team.** One model for every agent, or a mixed team with a count per model. The list comes from Pi, and the chips underneath are what `pi auth check` answered for each provider right now, so the form defaults to a model that can actually be used.

The caps card: USD cap for the whole swarm, an optional token cap, and the wall clock in minutes — **4 · Set the caps.** A dollar cap for the whole swarm, an optional token cap (required for a team of local models, which bill nothing), and the wall clock. At either cap every agent is steered once; two minutes later the harness writes the stop itself.

The read-only inputs card: an evidence set chosen from the server, with the kernel guard set to auto — **5 · Hand it the evidence.** Sets under `SWARM_INPUTS_ROOT` appear here with their file count and size. The set is copied in at kickoff, hashed, refused by `edit`, `write` and `claim_file`, and held read-only at the kernel in every pane where the host allows; *auto* takes the guard the host has.

The case card: evidence catalog, install, quarantine, the toolbox, a per-agent cap, the case id and the examiner — **6 · The case settings.** The evidence catalog runs the first pass before any agent spends a token; quarantine makes anything extracted unrunnable; the toolbox names the forensic tools the host is missing; a per-agent cap stops one agent without stopping the swarm; the case id and examiner go into the registry, the contract and the summary.

The network card: guarded, guarded plus hosts, open, or local only; and the switches for Playwright, hard kill, tool forging and prepare only — **7 · The network, and the switches.** Guarded is the default: the providers this team needs and nothing else. Add hosts a case needs, or go local-only for a team on your own machine. Below it: browser tools, hard kill, whether the agents may write tools, and *prepare only*, which writes the sandbox and launches nothing, for a look before you spend.

The label field, the swarm.sh start command the form has built, and the Start the swarm button — **8 · Read the command, then start.** The form shows the exact `swarm.sh start` line it will run, so what the console does is never different from what the terminal does. Starting needs the token the server printed at startup; watching never does. The run appears in the overview within seconds and opens to its story, board, trace and ledger.

Your first case

Evidence, a goal, and the tools the case needs.

A case differs from the hello goal in three ways. The flags below are the ones every published case ran with; swarm.sh help start explains each.

scripts/swarm.sh start \
  --models "openai/gpt-5.4=4,deepseek/deepseek-v4-pro=3" --n 7 \
  --goal-file library/windows/host-intrusion.md \
  # copied in, hashed, read-only at the kernel
  --inputs /evidence/case-42 \
  --catalog --toolbox dfir --quarantine \
  # the method, fetched a skill at a time
  --pack computer-forensics-base,windows-forensics \
  --allow-tool-forging \
  --cap-usd 60 --cap-per-agent 12 --wall-clock 90 \
  --case-id CASE-42 --examiner "Your name" --label case-42

Evidence

--inputs DIR copies the directory into the run, hashes every file and holds it read-only in every pane. For evidence too large to copy, --inputs-bind guards the source in place; on macOS --inputs-image case.dmg attaches a disk image read-only. Under --quarantine, nothing extracted from it can execute.

The goal

Forty-five investigations ship with the repository under library/, one for each kind of case: hosts, servers, memory, logs, captures, malware, cloud tenants, phones, and the general work of triage, indicators and timelines. Each carries the questions with the artefacts that answer them, a definition of done that names the report and the ledger, and checks the agents cannot edit. Load one in the console or name the file here, then change what your case asks. The BelkaCTF goal is a worked example of the same shape.

Tools

--toolbox dfir checks the host for Sleuth Kit, libewf, libbde, Volatility, YARA and the parsers a case needs, and names what is missing before the first agent starts. --catalog runs the first pass over the image once. With --allow-tool-forging the agents write the tools the host lacks; swarm.sh tools <id> --save DIR keeps them and --tools-from DIR hands them to the next swarm.

Method

--pack computer-forensics-base,windows-forensics puts an examiner's method in front of the swarm: the agents see a one-line index of every skill and fetch a body only when they reach that artefact family, so a pack the size of a textbook costs a few hundred tokens until it is used. Twelve packs are in the repository under the same licence, for Windows, Linux, macOS, mobile, memory, network, reverse engineering, encrypted containers, cloud, ransomware and triage collections. Install what the case needs with scripts/pack.sh install packs/<name>; the console's Packs tab then says which skills the run read and which it carried and never opened.

The network, and a re-run

Only the model providers are reachable. --allow-host adds a host the case needs; --allow-install lets the agents pip-install into the run, inventoried, and --no-pypi keeps the index off the allowlist. --no-read DIR keeps a previous run's findings on the same evidence unreadable, so a second swarm cannot read the back of the book.

An investigation loaded into the console's kickoff form: the contract in the editor, and the panel that counts its checks — Loading an investigation fills the editor with the contract and the form with what that case usually needs. The panel beside it counts the checks the run will be judged by, and says so when a goal has no finish line at all.

When the sentinel landsswarm.sh report <id> renders the report with its custody section, swarm.sh summary <id> prints what the run cost and what the harness had to do, and swarm.sh package <id> ships the whole run with a SHA-256 manifest. Every published case is that package, pruned of the evidence.

Stuck, or want it run for you?

The repository's troubleshooting page covers the failures we have met. For a case you would rather have worked with you, or a host that has to hold more than yours does, write to us.

Troubleshooting Talk to us