# Netdryrun: full documentation

> Netdryrun is an open-source tool that tests network changes in a real virtual lab before they reach production. It boots the topology with containerlab, waits for convergence, checks BGP sessions, prefixes, routes and reachability, and returns a pass/fail verdict with evidence. It runs locally, in GitHub Actions, or as an MCP server for AI agents.

Install: `pip install netdryrun` · Source: https://github.com/netdryrun/netdryrun · Docs: https://netdryrun.com/



---
Source: https://netdryrun.com/

# Fail CI on routing mistakes before they reach production

To test a network change in CI, keep the changed configs and a containerlab topology in Git, describe the expected behavior in a `netdryrun.yml` file, and run `netdryrun run` (or the GitHub Action) on every pull request. Netdryrun™ deploys the lab, waits for BGP to converge, checks sessions, prefix counts, routes and pings, then destroys the lab. Any failed check exits non-zero and fails the job, with a JSON evidence file showing every command and its raw output.

[Try it in your browser](https://codespaces.new/netdryrun/netdryrun?quickstart=1){ .md-button .md-button--primary } [View the source on GitHub](https://github.com/netdryrun/netdryrun){ .md-button }

The browser trial runs in GitHub Codespaces: it needs a free GitHub account, takes a few minutes to start, and then `bash examples/agent-demo/demo.sh` shows a bad change rejected and the fix accepted. Nothing to install.

!!! abstract "What Netdryrun is"
    Netdryrun is an open-source tool that tests network changes in a real virtual lab before they reach production. It boots the topology with containerlab, waits for convergence, checks BGP sessions, prefixes, routes and reachability, and returns a pass/fail verdict with evidence. It runs locally, in GitHub Actions, or as an MCP server for AI agents.

## Watch the demo

<figure class="ndr-video">
<video controls preload="none" playsinline width="1920" height="1080" poster="/assets/video/netdryrun-demo-poster.jpg" aria-label="Netdryrun demo video, about 90 seconds, captions burned in">
<source src="/assets/video/netdryrun-demo.mp4" type="video/mp4">
<track kind="captions" srclang="en" label="English (text)" src="/assets/video/netdryrun-demo.vtt">
<a href="/assets/video/netdryrun-demo.mp4">Download the video (MP4)</a>
</video>
<figcaption>About 90 seconds, captions on screen, no sound. A leaked default route that ping and session checks miss, an AI agent's tempting change rejected and the two-line fix passed (a scripted replay), a real agent run, and the verdict corpus with its losses. Every terminal line comes from a real run. <a href="/assets/video/netdryrun-demo.vtt">Captions as text</a>.</figcaption>
</figure>

## A failing run

This is the bundled `frr-bgp-broken` example. Router r2 has a bad change: it sends r1 a default route.


```text
$ netdryrun run examples/frr-bgp-broken
Deploying lab ndr-frr-broken (3 nodes)...
  [PASS] r1: BGP session to 10.0.12.2 is established -- state is established (6.3s)
  [PASS] r1: ping 192.168.3.1 from 192.168.1.1 expects success -- 3/3 replies (2.3s)
  ... (3 more passing checks trimmed)
  [FAIL] r1: route 0.0.0.0/0 via bgp is absent -- unexpectedly present via bgp (not selected) (0.1s)
FAILED: 5 passed, 1 failed (6 checks)
```

The leaked default route was *received but not selected*: r1 kept its own default, so traffic still flowed and the ping passed. A ping test or a session check would have missed it. (A static analyzer such as Batfish also catches this particular leak; the [Batfish page](batfish.md) shows one that it misses and the lab catches.) Netdryrun counts a route that is in the routing table but not selected as present, so the "must be absent" check fails.

The check that caught it:

```yaml
- type: route        # nothing should send r1 a default route
  node: r1
  prefix: 0.0.0.0/0
  protocol: bgp
  present: false
```

Checks like this one run only after the network has converged (the positive checks passed and every configured BGP session on the node is up) and must hold for a time window, so they cannot pass just because BGP has not come up yet. See [convergence semantics](reference/config.md#convergence-semantics).

## Run it in GitHub Actions

```yaml title=".github/workflows/network-dryrun.yml"
name: Network dry run
on: pull_request
jobs:
  dryrun:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: network/        # folder containing netdryrun.yml
```

The action installs containerlab, runs the checks, writes a summary to the job page, uploads the JSON and JUnit reports as an artifact, and fails the job if any check fails. Details: [GitHub Action](github-action.md).

## Run it locally

Fastest start on your own topology: `netdryrun record my-lab/topology.clab.yml --deploy` snapshots today's behavior into checks, then `netdryrun run my-lab` tests every change against it.


```bash
pipx install netdryrun          # Ubuntu 24.04+: sudo apt install pipx && pipx ensurepath first
netdryrun run path/to/folder    # the folder containing netdryrun.yml
```

Requirements: Linux or WSL2, Docker, containerlab, Python 3.10+. Walkthrough: [Getting started](getting-started.md).

!!! warning "What a lab cannot prove"
    A pass means the change behaved correctly in a lab built from container router images (FRR, Nokia SR Linux, SONiC, Arista cEOS). That is strong evidence for protocol logic and policy intent. It is not proof of:

    - vendor-specific behavior on the routers you run in production
    - behavior at production scale (full tables, many peers)
    - hardware and ASIC limits
    - timing and convergence at scale

    More on this in [Trust and security](trust.md#what-a-lab-cannot-prove).

## Status


Version 0.3.1, early. Works with FRR, Nokia SR Linux, SONiC and Arista EOS (bring your own cEOS image) on Linux and WSL2. Check types: `bgp_session`, `bgp_prefixes`, `route`, `bgp_route` and `ping` (IPv4/IPv6 unicast BGP sessions, prefix counts, routes, BGP best-path attributes and ping), plus link-down, node-isolation and route-injection (FRR only) failure scenarios. On the [verdict corpus](corpus.md) v1 (30 realistic BGP changes: 19 harmful, 11 safe), Netdryrun judged 24/30 correctly, ping-only checks 20/30 and all-sessions-up checks 15/30. Netdryrun approved 5 of the 19 harmful changes (ping-only checks: 10 of 19) and blocked 1 of the 11 safe ones. On v2 (18 cases written after v1 to target v1's misses): Netdryrun 17/18, ping-only 9/18, all-sessions-up 7/18. Both are small benchmarks the maintainers wrote on one FRR topology, with expected verdicts committed before any run: they compare methods, they are not a production reliability estimate. Provenance: both ran on Netdryrun 0.3.1. Issues and feedback: [github.com/netdryrun/netdryrun](https://github.com/netdryrun/netdryrun/issues).


---
Source: https://netdryrun.com/getting-started/

# Getting started

## Try it in your browser

No install: [open Netdryrun in GitHub Codespaces](https://codespaces.new/netdryrun/netdryrun?quickstart=1) and click **Create codespace**.

GitHub starts a Linux machine with Docker, containerlab 0.81.1 and Netdryrun installed from the repository, and pulls the FRR image the examples use. This takes a few minutes the first time. When the creation log shows `Ready`, run this in the terminal:

```bash
bash examples/agent-demo/demo.sh
```

The [agent demo](https://github.com/netdryrun/netdryrun/tree/main/examples/agent-demo) boots four FRR routers twice, which takes about 65 s. The first change opens the filters to make a ticket work and is rejected by the leak guards; the second adds two prefix-list lines and passes all 14 checks. The run ends with `Demo OK`. The other FRR examples (`netdryrun run examples/frr-bgp`, `examples/frr-bgp-broken`) work the same way.

The codespace runs on the 2-core machine and uses your GitHub account's free Codespaces allowance (GitHub Free includes 120 core-hours and 15 GB of storage a month, so about 60 hours on this machine; Pro includes 180 core-hours). Stop or delete the codespace when you're done ([github.com/codespaces](https://github.com/codespaces)) so it doesn't use more. VM-based nodes (vrnetlab) don't work in Codespaces, which has no nested virtualization.

## Requirements

| Requirement | Notes |
|---|---|
| Linux or WSL2 | containerlab runs on Linux. On Windows, use WSL2. |
| Docker | The lab nodes are containers. |
| [containerlab](https://containerlab.dev/install/) | Netdryrun™ drives the `containerlab` CLI; it must be on `PATH`. |
| Python 3.10+ | |

containerlab needs root (or a user in the right groups) to create the lab. Run Netdryrun the same way you run containerlab on that machine.

!!! note "WSL2 and /mnt/c"
    If your topology lives under `/mnt/...` (a Windows drive), Netdryrun keeps containerlab's lab directory on the Linux filesystem (`~/.cache/netdryrun/labs`) unless you set `CLAB_LABDIR_BASE` yourself. SR Linux cannot save its config on a Windows drive.

## Install

```bash
pipx install netdryrun
netdryrun --version
```

On Ubuntu 24.04 and Debian 12 a plain `pip install` outside a virtualenv is refused ("externally managed environment"), so use pipx: `sudo apt install pipx && pipx ensurepath`, then open a new terminal. `uv tool install netdryrun`, or `pip install netdryrun` inside an activated virtualenv, work too.

The MCP server for AI agents is included: run `netdryrun mcp`. See [AI agents](ai-agents.md).

## Run the examples

The repository ships these example labs. The FRR and SR Linux images are pulled automatically on first use.

```bash
git clone https://github.com/netdryrun/netdryrun && cd netdryrun
netdryrun run examples/frr-bgp          # 3 FRR routers, should pass
netdryrun run examples/srl-frr          # SR Linux + FRR, should pass
netdryrun run examples/frr-bgp-broken   # a bad change, should fail
examples/agent-demo/demo.sh             # replay: a leaky change rejected, the fix accepted
```

`examples/sonic-frr` needs the `docker-sonic-vs` image, which is on no container registry: download it from the SONiC build server and `docker load` it first ([how](guides/sonic-ci.md#1-get-the-image)). Then:

```bash
netdryrun run examples/sonic-frr        # SONiC + FRR, should pass
```

`examples/arista-frr` needs a cEOS image you download from Arista and import yourself; see the [examples page](examples.md#arista-frr).

Each run deploys the lab, runs the checks, prints one line per check and destroys the lab. The first run of an example takes longer while its images are pulled.

### Expected results

The [examples page](examples.md) has every example, what it shows and how long it takes.


| Example | Topology | Checks | Expected | Exit code |
|---|---|---|---|---|
| `examples/frr-bgp` | Triangle of three FRR routers (r1, r2, r3), eBGP | 2 sessions, prefix count 1 to 10, route present via BGP, ping, best-path AS path and next hop, default route absent, and a link-failure scenario (reroute via r3) | `PASSED: 11 passed, 0 failed` | `0` |
| `examples/srl-frr` | Nokia SR Linux (`srl1`) peering eBGP with FRR (`frr1`) | 2 sessions, a BGP route on each side, a ping in each direction, best-path attributes on `srl1` | `PASSED: 7 passed, 0 failed` | `0` |
| `examples/sonic-frr` | SONiC VS (`sonic1`, configured by `setup` commands) peering eBGP with FRR (`frr1`) | a session, a BGP route on each side, a ping, a prefix count, best-path attributes, a port-down scenario | `PASSED` | `0` |
| `examples/frr-bgp-broken` | Same triangle, but r2 adds `default-originate` toward r1 | The first 6 checks of `frr-bgp`, without the scenario | `FAILED: 5 passed, 1 failed`; the default route check fails | `1` |

The broken example is the one shown on the [home page](index.md#a-failing-run). r1 receives the leaked default route but does not select it, so the ping still works. The route check catches it because a received-but-not-selected route counts as present.

SR Linux takes longer to boot, so `examples/srl-frr` sets `timeout: 120`.

## Record a baseline of your own lab (fastest start)

Point `record` at any containerlab topology you already have:

```bash
netdryrun record my-lab/topology.clab.yml --deploy
```

It deploys the lab, waits for BGP to converge, and writes `my-lab/netdryrun.yml` with a check for every established BGP session, every prefix count and every BGP route (up to 50 per node). Then make your change and run:

```bash
netdryrun run my-lab
```

Anything that changed fails, with evidence. Before committing the baseline, remove what is allowed to change and add negative checks for what must never happen (for example `present: false` for a default route at a peer). See the [`record` reference](reference/cli.md#record) and the [tutorial](tutorial.md).

## Write checks for your own lab

Put a `netdryrun.yml` next to your containerlab topology:

```yaml title="netdryrun.yml"
lab: topology.clab.yml      # your containerlab topology
timeout: 90                 # seconds a positive check may wait for convergence

checks:
  - type: bgp_session
    node: r1
    neighbor: 10.0.12.2
  - type: route
    node: r1
    prefix: 192.168.3.0/24
    protocol: bgp
  - type: ping
    node: r1
    source: 192.168.1.1
    target: 192.168.3.1
```

Check the file without starting anything, then run it:

```bash
netdryrun validate .
netdryrun run .
```

To debug a failing run, keep the lab up with `--keep` (or `--keep-on-failure`), inspect the routers, and rerun the checks against the running lab with `netdryrun check .`. Destroy it afterwards with `containerlab destroy -t topology.clab.yml --cleanup`.

Next: the [tutorial](tutorial.md) walks through all of this on a real lab, step by step. Then see the [netdryrun.yml reference](reference/config.md), the [CLI reference](reference/cli.md) and [Troubleshooting](troubleshooting.md).


---
Source: https://netdryrun.com/tutorial/

# Test a change on your own lab

This tutorial takes a containerlab lab you already have and turns it into a test for every change. You will:

1. record a baseline of how the lab behaves today,
2. review and prune it,
3. add checks for things that must never happen,
4. make a change and run the test,
5. read the evidence when it fails,
6. run the same test in GitHub Actions.

It takes about 15 minutes. Every command and output below is from a real run (Netdryrun™ 0.3.0, containerlab 0.81.1, FRR 10.4.1, on WSL2).

## Before you start

You need Netdryrun, Docker and containerlab. See [Getting started](getting-started.md#requirements).

## 1. Your lab

Any containerlab topology works. Here, the bundled `examples/frr-bgp` lab stands in for "your lab": three FRR routers in a triangle, each in its own AS, each announcing one LAN prefix over eBGP.

```bash
git clone https://github.com/netdryrun/netdryrun
mkdir my-lab
cp -r netdryrun/examples/frr-bgp/configs netdryrun/examples/frr-bgp/topology.clab.yml my-lab/
sed -i 's/^name: ndr-frr-bgp/name: my-lab/' my-lab/topology.clab.yml
```

The folder now holds a topology and router configs, and no `netdryrun.yml`:

```text
my-lab/
  topology.clab.yml     # name: my-lab, nodes r1 r2 r3
  configs/
    daemons  r1.conf  r2.conf  r3.conf  vtysh.conf
```

The lab name (`name:` in the topology) must be unique on the machine. See [name collisions](troubleshooting.md#a-lab-named-x-is-already-running).

## 2. Record a baseline

`netdryrun record` deploys the lab, waits for BGP to converge, writes down what it sees, and destroys the lab.

```text
$ netdryrun record my-lab/topology.clab.yml --deploy
Deploying lab my-lab, then waiting 45s for the network to converge...
recording r1 (frr)
recording r2 (frr)
recording r3 (frr)
Recorded 18 checks to /home/user/ndr-docs/my-lab/netdryrun.yml. Review it, then: netdryrun run /home/user/ndr-docs/my-lab
```

This took 51 seconds. The file has one check for every established BGP session, every prefix count and every BGP route. The start of it:

```yaml title="my-lab/netdryrun.yml (recorded)"
# Recorded by netdryrun 0.3.0 record on 2026-10-27T04:38:28+00:00.
# This is a baseline of the network's behavior when it was recorded. Review it before committing:
# remove anything that is allowed to change, and add negative checks (route present: false,
# ping expect: failure) for things that must never happen. Docs: https://netdryrun.com/reference/config/
lab: topology.clab.yml
timeout: 120
checks:
- type: bgp_session
  node: r1
  neighbor: 10.0.12.2
- type: bgp_prefixes
  node: r1
  neighbor: 10.0.12.2
  afi: ipv4-unicast
  exact: 2
- type: bgp_session
  node: r1
  neighbor: 10.0.13.2
# ... 15 more: the same pattern for r2 and r3, plus one route check per learned LAN
```

## 3. Review and prune it

A recorded baseline says "nothing may change". That is rarely what you want. Decide what is allowed to change.

Here is what happens if you skip this step. The change in step 5 adds a LAN on r3, and its first attempt announces it with `redistribute connected`. Run against the raw baseline, the `exact: 2` prefix counts fail, because r1 and r2 now get 6 prefixes:

```text
$ netdryrun run my-lab
Netdryrun 0.3.0: 18 checks from my-lab/netdryrun.yml
Deploying lab my-lab (3 nodes)...
  [PASS] r1: BGP session to 10.0.12.2 is established -- state is established (10.3s)
  ...
Convergence checks done; settling 10s before post-convergence checks...
  [FAIL] r1: prefixes from 10.0.12.2 = 2 -- 6 ipv4-unicast prefixes accepted (0.2s)
  [FAIL] r1: prefixes from 10.0.13.2 = 2 -- 6 ipv4-unicast prefixes accepted (0.2s)
  [FAIL] r2: prefixes from 10.0.12.1 = 2 -- 6 ipv4-unicast prefixes accepted (0.2s)
  [FAIL] r2: prefixes from 10.0.23.2 = 2 -- 6 ipv4-unicast prefixes accepted (0.2s)
  [PASS] r3: prefixes from 10.0.13.1 = 2 -- 2 ipv4-unicast prefixes accepted (held 10s, 5 samples) (10.2s)
  [PASS] r3: prefixes from 10.0.23.1 = 2 -- 2 ipv4-unicast prefixes accepted (held 10s, 5 samples) (10.2s)
Destroying lab...
FAILED: 14 passed, 4 failed (18 checks)
```

The test did its job: something changed. But adding a LAN is allowed, so the baseline should allow it. Edit the file:

- **Keep** every `bgp_session` check. Sessions must stay up.
- **Turn exact prefix counts into ranges.** `min: 2` keeps today's routes; `max: 10` still catches a leak that floods r1. You can also record ranges from the start with `netdryrun record --min-prefixes`.
- **Keep the route checks you care about.** This tutorial keeps r1's and removes the r2 and r3 copies to keep the file short.

## 4. Add negative checks

`record` only writes down what exists. It cannot know what must never exist. Add those checks yourself. For this lab:

- nobody sends r1 a default route,
- the point-to-point link subnets (`10.0.x.x/30`) stay out of BGP,
- and a ping, so the test proves traffic gets through, not only that routes exist.

The reviewed file:

```yaml title="my-lab/netdryrun.yml (reviewed)"
# Baseline recorded with `netdryrun record`, then reviewed by hand.
lab: topology.clab.yml
timeout: 120
checks:
# Every BGP session stays up (recorded).
- type: bgp_session
  node: r1
  neighbor: 10.0.12.2
- type: bgp_session
  node: r1
  neighbor: 10.0.13.2
- type: bgp_session
  node: r2
  neighbor: 10.0.12.1
- type: bgp_session
  node: r2
  neighbor: 10.0.23.2
- type: bgp_session
  node: r3
  neighbor: 10.0.13.1
- type: bgp_session
  node: r3
  neighbor: 10.0.23.1
# Prefix counts may grow when a site adds a LAN, but not past 10 (recorded as exact: 2, edited).
- type: bgp_prefixes
  node: r1
  neighbor: 10.0.12.2
  min: 2
  max: 10
- type: bgp_prefixes
  node: r1
  neighbor: 10.0.13.2
  min: 2
  max: 10
# Each LAN reaches the others (recorded routes; the r2 and r3 copies were removed to keep the file short).
- type: route
  node: r1
  prefix: 192.168.2.0/24
  protocol: bgp
- type: route
  node: r1
  prefix: 192.168.3.0/24
  protocol: bgp
# Added by hand: traffic gets through, not just routes.
- type: ping
  node: r1
  source: 192.168.1.1
  target: 192.168.3.1
# Added by hand: things that must never happen.
- type: route          # nobody sends r1 a default route
  node: r1
  prefix: 0.0.0.0/0
  protocol: bgp
  present: false
- type: route          # point-to-point link subnets stay out of BGP
  node: r1
  prefix: 10.0.23.0/30
  protocol: bgp
  present: false
```

Check it without starting a lab:

```text
$ netdryrun validate my-lab
OK: my-lab/netdryrun.yml (13 checks, lab /home/user/ndr-docs/my-lab/topology.clab.yml, 3 nodes)
  - [bgp_session] r1: BGP session to 10.0.12.2 is established
  - [bgp_session] r1: BGP session to 10.0.13.2 is established
  - [bgp_session] r2: BGP session to 10.0.12.1 is established
  - [bgp_session] r2: BGP session to 10.0.23.2 is established
  - [bgp_session] r3: BGP session to 10.0.13.1 is established
  - [bgp_session] r3: BGP session to 10.0.23.1 is established
  - [bgp_prefixes] r1: prefixes from 10.0.12.2 >= 2 and <= 10
  - [bgp_prefixes] r1: prefixes from 10.0.13.2 >= 2 and <= 10
  - [route] r1: route 192.168.2.0/24 via bgp is present
  - [route] r1: route 192.168.3.0/24 via bgp is present
  - [ping] r1: ping 192.168.3.1 from 192.168.1.1 expects success
  - [route] r1: route 0.0.0.0/0 via bgp is absent
  - [route] r1: route 10.0.23.0/30 via bgp is absent
```

To check BGP attributes too (communities, AS path, local preference, MED, next hop), add `bgp_route` checks; see the [reference](reference/config.md#check-types).

Negative checks are [post-convergence checks](reference/config.md#convergence-semantics): they run after the positive checks pass and a settle time, and must hold for 10 seconds.

## 5. Make a change and run it

The change: r3 gets a second LAN, 192.168.33.0/24. A first attempt announces it with `redistribute connected`:

```diff title="configs/r3.conf (first attempt)"
 interface lo
  ip address 192.168.3.1/24
+ ip address 192.168.33.1/24
 !
@@
  address-family ipv4 unicast
   network 192.168.3.0/24
+  redistribute connected
```

Run it, and ask for the JSON and Markdown reports:

```text
$ cd my-lab
$ netdryrun run . --json report.json --markdown report.md
Netdryrun 0.3.0: 13 checks from netdryrun.yml
Deploying lab my-lab (3 nodes)...
  [PASS] r1: BGP session to 10.0.12.2 is established -- state is established (14.0s)
  [PASS] r1: BGP session to 10.0.13.2 is established -- state is established (14.0s)
  [PASS] r2: BGP session to 10.0.12.1 is established -- state is established (14.0s)
  [PASS] r2: BGP session to 10.0.23.2 is established -- state is established (14.0s)
  [PASS] r3: BGP session to 10.0.13.1 is established -- state is established (14.0s)
  [PASS] r3: BGP session to 10.0.23.1 is established -- state is established (14.0s)
  [PASS] r1: route 192.168.2.0/24 via bgp is present -- active via bgp (14.0s)
  [PASS] r1: route 192.168.3.0/24 via bgp is present -- active via bgp (14.0s)
  [PASS] r1: ping 192.168.3.1 from 192.168.1.1 expects success -- 3/3 replies (need 2) (14.0s)
Convergence checks done; settling 10s before post-convergence checks...
  [PASS] r1: prefixes from 10.0.12.2 >= 2 and <= 10 -- 6 ipv4-unicast prefixes accepted (held 10s, 5 samples) (10.2s)
  [PASS] r1: prefixes from 10.0.13.2 >= 2 and <= 10 -- 6 ipv4-unicast prefixes accepted (held 10s, 5 samples) (10.2s)
  [PASS] r1: route 0.0.0.0/0 via bgp is absent -- absent (held 10s, 5 samples) (10.2s)
  [FAIL] r1: route 10.0.23.0/30 via bgp is absent -- unexpectedly present via bgp (0.2s)
Destroying lab...
FAILED: 12 passed, 1 failed (13 checks)
  wrote json report: report.json
  wrote markdown report: report.md
```

The run took 37 seconds and exited with code `1`. Sessions are up, the ping works, and the prefix count is inside its range. Only the negative check caught the problem: `redistribute connected` also announces r3's link subnets.

## 6. Read the evidence

### Markdown report

`report.md` is the text the GitHub Action puts on the job page and in the PR comment. Failures come first, and each failure has the raw command output in a collapsed block:

````markdown title="report.md"
### ❌ Netdryrun failed

**12 passed, 1 failed** on lab `my-lab`

| | Check | Result | Time |
|---|---|---|---|
| ❌ | r1: route 10.0.23.0/30 via bgp is absent | unexpectedly present via bgp | 0.2s |
| ✅ | r1: BGP session to 10.0.12.2 is established | state is established | 14.0s |
...
| ✅ | r1: route 0.0.0.0/0 via bgp is absent | absent (held 10s, 5 samples) | 10.2s |

<details><summary>Evidence: r1: route 10.0.23.0/30 via bgp is absent</summary>

`r1$ vtysh -c show ip route 10.0.23.0/30 json`

```
{
  "10.0.23.0/30":[
    {
      "prefix":"10.0.23.0/30",
      "prefixLen":30,
      "protocol":"bgp",
      ...
```

</details>

<sub>netdryrun 0.3.0 · containerlab 0.81.1 · 2026-10-27T04:39:03+00:00 · full evidence in the JSON report</sub>
````

### JSON report

`report.json` has everything ([schema](reference/cli.md#json)). The top level says what ran and where:

```json
{"schema": "netdryrun.report/v1", "status": "failed", "lab": "my-lab", "error": null, "inconclusive_reason": null,
 "summary": {"passed": 12, "failed": 1, "total": 13}}
```

`environment` records the versions and images, so a result can be reproduced:

```json
"environment": {
  "netdryrun": "0.3.0",
  "containerlab": "0.81.1",
  "python": "3.10.12",
  "host": "Linux-6.18.54.1-microsoft-standard-WSL2-x86_64-with-glibc2.35",
  "nodes": {
    "r1": {"kind": "linux", "image": "quay.io/frrouting/frr:10.4.1"},
    "r2": {"kind": "linux", "image": "quay.io/frrouting/frr:10.4.1"},
    "r3": {"kind": "linux", "image": "quay.io/frrouting/frr:10.4.1"}
  }
}
```

The failed check, with its history of samples:

```json
{
  "name": "r1: route 10.0.23.0/30 via bgp is absent",
  "type": "route",
  "params": {"node": "r1", "prefix": "10.0.23.0/30", "protocol": "bgp", "present": false},
  "passed": false,
  "detail": "unexpectedly present via bgp",
  "attempts": 1,
  "duration_s": 0.2,
  "history": [{"t": 0.2, "passed": false, "detail": "unexpectedly present via bgp"}]
}
```

Its `evidence` holds the command and the full output. The interesting part: the route is selected, installed, and points at r3 (`10.0.13.2`):

```json
{
  "10.0.23.0/30":[
    {
      "prefix":"10.0.23.0/30",
      "protocol":"bgp",
      "selected":true,
      "installed":true,
      "nexthops":[
        {"ip":"10.0.13.2", "interfaceName":"eth2", "active":true}
      ]
    }
  ]
}
```

(Shortened; the report keeps every field.)

To look at the routers yourself, rerun with `--keep-on-failure` and run commands with `docker exec clab-my-lab-r1 vtysh -c "..."`, then destroy the lab with the command Netdryrun prints. [Troubleshooting](troubleshooting.md#the-lab-never-converges-timeout) has an example.

## 7. Fix the change and run again

Announce only the new LAN, with a `network` statement:

```diff title="configs/r3.conf (fixed)"
 interface lo
  ip address 192.168.3.1/24
+ ip address 192.168.33.1/24
 !
@@
  address-family ipv4 unicast
   network 192.168.3.0/24
+  network 192.168.33.0/24
```

Add a check that the change did what it should, so the test also proves the new LAN arrives:

```yaml
# Added with the change: the new LAN reaches r1.
- type: route
  node: r1
  prefix: 192.168.33.0/24
  protocol: bgp
```

```text
$ netdryrun run . --json report.json --markdown report.md
Netdryrun 0.3.0: 14 checks from netdryrun.yml
Deploying lab my-lab (3 nodes)...
  [PASS] r1: BGP session to 10.0.12.2 is established -- state is established (13.9s)
  [PASS] r1: BGP session to 10.0.13.2 is established -- state is established (13.9s)
  [PASS] r2: BGP session to 10.0.12.1 is established -- state is established (13.9s)
  [PASS] r2: BGP session to 10.0.23.2 is established -- state is established (13.9s)
  [PASS] r3: BGP session to 10.0.13.1 is established -- state is established (13.9s)
  [PASS] r3: BGP session to 10.0.23.1 is established -- state is established (13.9s)
  [PASS] r1: route 192.168.2.0/24 via bgp is present -- active via bgp (13.9s)
  [PASS] r1: route 192.168.3.0/24 via bgp is present -- active via bgp (13.9s)
  [PASS] r1: ping 192.168.3.1 from 192.168.1.1 expects success -- 3/3 replies (need 2) (13.9s)
  [PASS] r1: route 192.168.33.0/24 via bgp is present -- active via bgp (13.9s)
Convergence checks done; settling 10s before post-convergence checks...
  [PASS] r1: prefixes from 10.0.12.2 >= 2 and <= 10 -- 3 ipv4-unicast prefixes accepted (held 10s, 5 samples) (10.2s)
  [PASS] r1: prefixes from 10.0.13.2 >= 2 and <= 10 -- 3 ipv4-unicast prefixes accepted (held 10s, 5 samples) (10.2s)
  [PASS] r1: route 0.0.0.0/0 via bgp is absent -- absent (held 10s, 5 samples) (10.2s)
  [PASS] r1: route 10.0.23.0/30 via bgp is absent -- absent (held 10s, 5 samples) (10.2s)
Destroying lab...
PASSED: 14 passed, 0 failed (14 checks)
  wrote json report: report.json
  wrote markdown report: report.md
```

38 seconds, exit code `0`. Commit the change and the updated `netdryrun.yml` together.

## 8. Run it on every pull request

Put the lab folder in your repository (here, `network/`) and add a workflow:

```yaml title=".github/workflows/network-dryrun.yml"
name: Network dry run
on:
  pull_request:
    paths:
      - "network/**"
permissions:
  contents: read
  pull-requests: write   # only for pr-comment
jobs:
  dryrun:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: network/
          pr-comment: true
```

Every pull request that touches `network/` now deploys the lab on the runner, runs the checks, posts the Markdown report as a comment, uploads `report.json` as an artifact, and fails if any check fails. Make the job a required status check in your branch protection to block merges on a failure.

On GitHub-hosted runners, the `frr-bgp` example's CI job (install containerlab, pull the FRR image, run its checks including a link-failure scenario; measured on 0.2.0) takes 100 to 107 seconds. Before you open a PR with untrusted contributors, read the [Action security notes](github-action.md#security-notes).

## Next

- [netdryrun.yml reference](reference/config.md): every check type, including `ping` with `expect: failure` and failure scenarios (`link_down`).
- [Troubleshooting](troubleshooting.md): errors you may hit and how to fix them.
- [AI agents](ai-agents.md): let an agent run the same test before it proposes a change.


---
Source: https://netdryrun.com/examples/

# Examples

The repository's [`examples/`](https://github.com/netdryrun/netdryrun/tree/main/examples) folder has one lab per supported network OS, a deliberately broken change, a teaching lab about leaks that ping can't see, the AI agent demo, and a Batfish-then-lab pipeline. Each folder holds a containerlab topology, the router configs and a `netdryrun.yml`.

```bash
git clone https://github.com/netdryrun/netdryrun && cd netdryrun
netdryrun run examples/frr-bgp
```

## At a glance

Times are wall-clock for `netdryrun run` on WSL2 (20 cores, 16 GB) with images already pulled, measured on 2026-10-27 with containerlab 0.81.1 and Netdryrun™ 0.3.0 (`frr-bgp-broken`: 0.2.0, and `agent-demo`: a development build between 0.2.0 and 0.3.0; their checks did not change in 0.3.0. `srl-hidden-leak`: 0.3.0 plus the SR Linux fix that ships in 0.3.1). They include deploying and destroying the lab. The first run of each example also pulls its images.

| Example | Network OS | Shows | Expected | Exit | Time |
|---|---|---|---|---|---|
| [frr-bgp](#frr-bgp) | FRR | Basic checks, best-path attributes, a leak guard, a link-failure scenario | `PASSED: 11 passed, 0 failed` | `0` | 84 s |
| [frr-bgp-broken](#frr-bgp-broken) | FRR | A leaked default route caught | `FAILED: 5 passed, 1 failed` | `1` | 45 s |
| [srl-frr](#srl-frr) | Nokia SR Linux + FRR | Mixed vendors | `PASSED: 7 passed, 0 failed` | `0` | 60 s |
| [srl-hidden-leak](#srl-hidden-leak) | Nokia SR Linux + FRR | A leaked default that ping, sessions and the routing table miss, on both NOSes | `PASSED: 9 passed, 0 failed`; each leak `FAILED: 8 passed, 1 failed` | `0`; `1` | 52 to 84 s |
| [sonic-frr](#sonic-frr) | SONiC VS + FRR | Configuring a NOS after boot, a port-down scenario | `PASSED: 8 passed, 0 failed` | `0` | 90 s |
| [arista-frr](#arista-frr) | Arista cEOS + FRR (your image) | A bring-your-own vendor image | `PASSED: 10 passed, 0 failed` | `0` | 92 s |
| [agent-demo](#agent-demo) `demo.sh` | FRR | An agent's leaky change rejected, the fix accepted | `Demo OK` | `0` | 65 s |
| [batfish-pipeline](#batfish-pipeline) | FRR | Batfish first, then the lab; three bad changes | `PASSED: 10 passed, 0 failed` | `0` | 72 s |

## frr-bgp

[`examples/frr-bgp`](https://github.com/netdryrun/netdryrun/tree/main/examples/frr-bgp): three FRR routers (r1, r2, r3) in a triangle, each in its own AS, each announcing one LAN over eBGP.

**Shows:** the basic check types, a negative check and a failure scenario. r1 checks both BGP sessions, a prefix count between 1 and 10 (a leak guard), a route to r3's LAN, a ping to it, the AS path and next hop of the best path to r2's LAN (a `bgp_route` check), and that no default route arrives. The scenario takes the r1-r2 link down and checks that r2's LAN is still reachable through r3, that the best path now goes through r3 (AS path `65003 65002`), and that the session over the failed link is down.

**Expected:** `PASSED: 11 passed, 0 failed (11 checks)`, exit code `0`.

This is the lab the [tutorial](tutorial.md) uses as "your lab".

To run it on every pull request, see [Test an FRR change in CI](guides/frr-ci.md).

## frr-bgp-broken

[`examples/frr-bgp-broken`](https://github.com/netdryrun/netdryrun/tree/main/examples/frr-bgp-broken): the same triangle, but r2's config (`r2-bad.conf`) adds `default-originate` toward r1.

**Shows:** a bad change being caught. Sessions are up and the ping still works, because r1 receives the leaked default route but does not select it. The negative route check fails anyway: a received-but-not-selected route counts as present.

**Expected:** `FAILED: 5 passed, 1 failed (6 checks)`, exit code `1`. The failing check:

```text
  [FAIL] r1: route 0.0.0.0/0 via bgp is absent -- unexpectedly present via bgp (not selected) (0.1s)
```

CI runs this example on every push and expects it to fail.

## srl-frr

[`examples/srl-frr`](https://github.com/netdryrun/netdryrun/tree/main/examples/srl-frr): a Nokia SR Linux router (`srl1`) peering eBGP with FRR (`frr1`).

**Shows:** a mixed-vendor lab. Both sessions, a BGP route on each side, a ping in each direction, and the best path's AS path, local preference and next hop on `srl1`. SR Linux boots slower, so the file sets `timeout: 120`.

**Expected:** `PASSED: 7 passed, 0 failed (7 checks)`, exit code `0`. The SR Linux image is about 3.2 GB.

## srl-hidden-leak

[`examples/srl-hidden-leak`](https://github.com/netdryrun/netdryrun/tree/main/examples/srl-hidden-leak): "The route leak ping can't see". SR Linux (`srl1`) and FRR (`frr1`) peer eBGP, and each has its own static default route. [`leaks/`](https://github.com/netdryrun/netdryrun/tree/main/examples/srl-hidden-leak/leaks) holds two one-line changes that each leak a default route to the peer: `default-originate` on FRR, and an export statement matching `protocol static` on SR Linux.

**Shows:** a leak that is received but never selected, because it loses to the static. Sessions, ping and the routing table look unchanged. The [README](https://github.com/netdryrun/netdryrun/blob/main/examples/srl-hidden-leak/README.md) teaches how to see it by hand in each CLI (the BGP RIB on SR Linux, a `B` route without `>*` on FRR) and what happens when the static goes away. One `bgp_route` check with `present: false` per router catches each leak. Run `netdryrun run examples/srl-hidden-leak` as is, then copy a file from `leaks/` over `configs/` and run it again.

**Expected:** good configs `PASSED: 9 passed, 0 failed (9 checks)`, exit code `0`. Each leak `FAILED: 8 passed, 1 failed (9 checks)`, exit code `1`, failing only the guard on the receiving router:

```text
  [FAIL] srl1: no BGP path for 0.0.0.0/0 -- unexpectedly in the BGP table (1 path(s); as-path '65020', next hop 10.0.100.2, local-pref 100, MED 0, communities none) (2.4s)
```

Needs Netdryrun 0.3.1 or later: 0.3.0 counts `srl1`'s own static default as a BGP path, so the good configs fail. Its times in the table were measured with that fix (0.3.0 plus the fix), over nine runs on 2026-10-27; the README lists each one.

## sonic-frr

[`examples/sonic-frr`](https://github.com/netdryrun/netdryrun/tree/main/examples/sonic-frr): SONiC VS (`sonic1`, the `docker-sonic-vs` image) peering eBGP with FRR (`frr1`).

**Shows:** a NOS that is configured after boot. SONiC VS has no startup config here; `setup` commands in `netdryrun.yml` wait for its services, set the interface addresses and configure BGP. Checks: the session, a route on each side, a ping, a prefix count, best-path attributes on `sonic1`, and a scenario that takes the SONiC port `Ethernet0` down and checks that the session drops and the route is withdrawn.

**Expected:** `PASSED: 8 passed, 0 failed (8 checks)`, exit code `0`. `setup` waits for SONiC's services before any check runs.

The image comes from the SONiC build server, not a registry. To get it and run the lab on every pull request, see [Test a SONiC change in CI](guides/sonic-ci.md).

## arista-frr

[`examples/arista-frr`](https://github.com/netdryrun/netdryrun/tree/main/examples/arista-frr): an Arista cEOS router (`ceos1`) peering eBGP with FRR (`frr1`).

**Shows:** a vendor image you bring yourself. cEOS-lab is free from arista.com with an account but can't be redistributed, so import it as `ceos:4.36.3M` first (the comment in `topology.clab.yml` shows how). Checks: both sessions, a prefix count, a route on each side, a ping, best-path attributes on `ceos1`, no default route at the Arista, and a scenario that takes the link down from the FRR side.

**Expected:** `PASSED: 10 passed, 0 failed (10 checks)`, exit code `0`. Without the image, the run stops with exit code `2`; see [the cEOS image is missing](troubleshooting.md#the-ceos-image-is-missing).

## agent-demo

[`examples/agent-demo`](https://github.com/netdryrun/netdryrun/tree/main/examples/agent-demo): an edge router (`edge1`, AS 65000) with a customer, an upstream and a peer, a ticket ([`TICKET.md`](https://github.com/netdryrun/netdryrun/blob/main/examples/agent-demo/TICKET.md)) and the network team's 14 checks, including route-leak guards.

**Shows:** how an AI agent's change is judged. `demo.sh` replays two hand-written attempts: removing the prefix-list filters (passes the ticket checks, fails the leak guards) and adding the new block to two prefix lists (passes everything). See [AI agents](ai-agents.md#demo-a-ticket-a-tempting-change-a-verdict) and the [real agent run](ai-agents.md#a-real-agent-run).

**Expected:**

- `examples/agent-demo/demo.sh` exits `0` and ends with:

    ```text
    Demo OK: attempt 1 rejected by 5 leak guards with every other check passing; attempt 2 passed every check.
    ```

    Attempt 1 ends `FAILED: 9 passed, 5 failed (14 checks)`, attempt 2 `PASSED: 14 passed, 0 failed (14 checks)`. The two runs together took about 65 s.

- `netdryrun run examples/agent-demo` shows the starting point, before anyone has worked the ticket: the guards pass and the 3 ticket checks fail, `FAILED: 11 passed, 3 failed (14 checks)`, exit code `1`. It took 119 seconds, because the failing ticket checks wait for their timeout.

## batfish-pipeline

[`examples/batfish-pipeline`](https://github.com/netdryrun/netdryrun/tree/main/examples/batfish-pipeline): the `frr-bgp` triangle behind a two-stage gate. `pipeline.sh` runs Batfish on the configs first (nothing boots), then the lab. It needs a running Batfish service and `pybatfish`.

**Shows:** what each stage catches. Three changes to r2 are in `changes/`: a leaked default route and a route-map typo (Batfish fails them in 2 to 3 seconds of analysis) and a switch to FRR's `traditional` defaults, which Batfish passes but the lab fails. See [Batfish, then Netdryrun](batfish.md) for the measured results.

**Expected:** `pipeline.sh` with no change: Batfish `8 passed, 0 failed`, then `PASSED: 10 passed, 0 failed (10 checks)`, exit code `0`. The time in the table includes both stages, with the Batfish service already running.

## Use an example as a template

Copy a folder, change `name:` in `topology.clab.yml` (lab names must be unique on the machine), replace the configs with yours, and edit the checks. Or start from your own topology with `netdryrun record`, as in the [tutorial](tutorial.md).


---
Source: https://netdryrun.com/guides/frr-ci/

# Test an FRR change in CI

You keep FRR configs in git, one `frr.conf` per router. This guide makes every pull request that touches them boot the routers in containerlab with the changed configs, check how they route, and fail the job if something broke. It uses [`examples/frr-bgp`](https://github.com/netdryrun/netdryrun/tree/main/examples/frr-bgp) and its broken twin [`examples/frr-bgp-broken`](https://github.com/netdryrun/netdryrun/tree/main/examples/frr-bgp-broken); every output below is from a real run.

## 1. The lab: one folder next to your configs

`examples/frr-bgp` is three FRR routers in a triangle, each in its own AS, each announcing one LAN over eBGP. The folder holds:

```text
frr-bgp/
  topology.clab.yml      containerlab topology
  configs/r1.conf        one frr.conf per router (r2.conf, r3.conf)
  configs/daemons        which FRR daemons start
  configs/vtysh.conf     one line: service integrated-vtysh-config
  netdryrun.yml          the checks
```

Each router is a plain `linux` node running the FRR image, with the three files bind-mounted where FRR expects them:

```yaml title="topology.clab.yml"
name: ndr-frr-bgp

topology:
  defaults:
    kind: linux
    image: quay.io/frrouting/frr:10.4.1
  nodes:
    r1:
      binds:
        - configs/daemons:/etc/frr/daemons
        - configs/vtysh.conf:/etc/frr/vtysh.conf
        - configs/r1.conf:/etc/frr/frr.conf
    # r2 and r3 the same, with their own frr.conf
  links:
    - endpoints: ["r1:eth1", "r2:eth1"]
    - endpoints: ["r2:eth2", "r3:eth1"]
    - endpoints: ["r3:eth2", "r1:eth2"]
```

FRR details that matter here:

- **`daemons` decides what runs.** `bgpd=yes` (and `staticd=yes` for static routes) or BGP never starts. Netdryrun then reports the run as `inconclusive` (exit code `3`), not as a failed change, because no node ever returned BGP state.
- **`vtysh.conf` with `service integrated-vtysh-config`** makes `vtysh` read the single `frr.conf`, which is the file your pull request changes.
- **`eth0` is containerlab's management interface.** Your links start at `eth1`, and `frr.conf` should name those.
- **Pin the image** to the FRR version you run, not `latest`. Behavior and defaults change between releases.

## 2. The checks that matter for FRR

```yaml title="netdryrun.yml"
lab: topology.clab.yml
timeout: 90   # seconds each positive check may wait for convergence

checks:
  - type: bgp_session
    node: r1
    neighbor: 10.0.12.2
  - type: bgp_session
    node: r1
    neighbor: 10.0.13.2
  - type: bgp_prefixes
    node: r1
    neighbor: 10.0.12.2
    min: 1
    max: 10          # guards against a route leak flooding r1
  - type: route
    node: r1
    prefix: 192.168.3.0/24
    protocol: bgp
  - type: ping
    node: r1
    source: 192.168.1.1
    target: 192.168.3.1
  - type: bgp_route    # r1 prefers r2's direct path to r2's LAN over the longer path via r3
    node: r1
    prefix: 192.168.2.0/24
    as_path: "65002"
    next_hop: 10.0.12.2
  - type: route        # nothing should send r1 a default route
    node: r1
    prefix: 0.0.0.0/0
    protocol: bgp
    present: false

scenarios:
  - name: r1-r2 link fails
    link_down: {node: r1, interface: eth1}
    checks:
      - type: route        # r2's LAN is still reachable, now via r3
        node: r1
        prefix: 192.168.2.0/24
        protocol: bgp
      - type: bgp_route    # the best path now goes the long way, through r3
        node: r1
        prefix: 192.168.2.0/24
        as_path: "65003 65002"
        next_hop: 10.0.13.2
      - type: ping
        node: r1
        source: 192.168.1.1
        target: 192.168.2.1
      - type: bgp_session  # and the session over the failed link is really down
        node: r1
        neighbor: 10.0.12.2
        state: down        # any state except established
```

On FRR, each check type reads a different part of the router, and the differences are where changes go wrong:

| Check | Reads | Why it matters on FRR |
|---|---|---|
| `bgp_session` | `show bgp neighbors json` | An `Established` session can still carry nothing. Never use it alone |
| `bgp_prefixes` | `acceptedPrefixCounter` in `show bgp neighbors json` | Counts prefixes after your inbound policy. A filter that drops everything shows here first. `max` is a cheap leak guard |
| `route` | `show ip route <prefix> json` (zebra) | Selected and installed. zebra keeps the losing entries too, so `present: false` also fails on a route that was received but lost |
| `bgp_route` | `show bgp ipv4 unicast <prefix> json` (bgpd) | The best path's AS path, next hop, local preference, MED, communities. Catches a change that still delivers the route, but the long way |
| `ping` | `ping -I <source>` in the container | The data plane, from the source address you give |

BGP's best path and zebra's selected route are not the same thing. A default route leaked by a peer is `*>` (best) in `show bgp ipv4 unicast`, because the static it loses to isn't a BGP path, and it is not selected in `show ip route`. Read the table that answers your question: `bgp_route` for "which path does BGP prefer", `route` for "what does the router forward with". The [hidden leak lab](https://github.com/netdryrun/netdryrun/tree/main/examples/srl-hidden-leak) shows both side by side.

## 3. Run it locally

```bash
pip install netdryrun
netdryrun run examples/frr-bgp
```

```text
Netdryrun 0.3.0: 7 checks from examples/frr-bgp/netdryrun.yml
Deploying lab ndr-frr-bgp (3 nodes); this usually takes 30-90 s, longer the first time images are pulled...
  [PASS] r1: BGP session to 10.0.12.2 is established -- state is established (13.4s)
  [PASS] r1: BGP session to 10.0.13.2 is established -- state is established (13.4s)
  [PASS] r1: route 192.168.3.0/24 via bgp is present -- active via bgp (13.4s)
  [PASS] r1: ping 192.168.3.1 from 192.168.1.1 expects success -- 3/3 replies (need 2) (13.4s)
  [PASS] r1: BGP best path for 192.168.2.0/24 has as-path '65002', next hop 10.0.12.2 -- best path: as-path '65002', next hop 10.0.12.2, local-pref 100, MED 0, communities none (13.4s)
Convergence checks done; settling 10s before post-convergence checks...
  [PASS] r1: prefixes from 10.0.12.2 >= 1 and <= 10 -- 2 ipv4-unicast prefixes accepted (held 10s, 5 samples) (10.1s)
  [PASS] r1: route 0.0.0.0/0 via bgp is absent -- absent (held 10s, 5 samples) (10.1s)
Scenario: r1-r2 link fails
  [PASS] [r1-r2 link fails] r1: route 192.168.2.0/24 via bgp is present -- active via bgp (8.2s)
  [PASS] [r1-r2 link fails] r1: ping 192.168.2.1 from 192.168.1.1 expects success -- 3/3 replies (need 2) (8.2s)
  [PASS] [r1-r2 link fails] r1: BGP best path for 192.168.2.0/24 has as-path '65003 65002', next hop 10.0.13.2 -- best path: as-path '65003 65002', next hop 10.0.13.2, local-pref 100, MED 0, communities none (11.3s)
  [PASS] [r1-r2 link fails] r1: BGP session to 10.0.12.2 is down -- state is active (held 10s, 5 samples) (10.1s)
Restored 1 link(s) and 0 route injection(s); settling 10s
Destroying lab...
PASSED: 11 passed, 0 failed (11 checks)
```

Now the broken change. `frr-bgp-broken` is the same triangle, but r2's config adds one line, `neighbor 10.0.12.1 default-originate`, toward r1:

```bash
netdryrun run examples/frr-bgp-broken
```

```text
Netdryrun 0.3.0: 6 checks from examples/frr-bgp-broken/netdryrun.yml
Deploying lab ndr-frr-broken (3 nodes); this usually takes 30-90 s, longer the first time images are pulled...
  [PASS] r1: BGP session to 10.0.12.2 is established -- state is established (13.5s)
  [PASS] r1: BGP session to 10.0.13.2 is established -- state is established (13.5s)
  [PASS] r1: route 192.168.3.0/24 via bgp is present -- active via bgp (13.5s)
  [PASS] r1: ping 192.168.3.1 from 192.168.1.1 expects success -- 3/3 replies (need 2) (13.5s)
Convergence checks done; settling 10s before post-convergence checks...
  [PASS] r1: prefixes from 10.0.12.2 >= 1 and <= 10 -- 3 ipv4-unicast prefixes accepted (held 10s, 5 samples) (10.1s)
  [FAIL] r1: route 0.0.0.0/0 via bgp is absent -- unexpectedly present via bgp (not selected) (0.1s)
Destroying lab...
FAILED: 5 passed, 1 failed (6 checks)
```

Sessions are up, the prefix count is within its limit, and the ping works: the LANs have more specific routes, so a default route changes nothing for them. r1 doesn't even select the leaked default, because in this lab it loses to containerlab's management default route (see [Gotchas](#gotchas)). The `present: false` check fails anyway, because zebra still holds the losing BGP entry, and the run exits with `1`.

## 4. Run it on every pull request

```yaml title=".github/workflows/network-dryrun.yml"
name: Network dry run
on:
  pull_request:
    paths:
      - "network/**"
permissions:
  contents: read
  pull-requests: write   # for pr-comment
jobs:
  dryrun:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: network/        # the folder with netdryrun.yml
          pr-comment: true
```

The job installs containerlab and Netdryrun, pulls the FRR image, runs the checks, uploads the JSON and JUnit reports, and fails if a check fails. With `pr-comment: true` it also posts the verdict and the evidence for each failed check on the pull request. See [GitHub Action](../github-action.md) for every input, and the security notes before running labs from forks.

**Other CI systems:** any Linux runner that can start privileged Docker containers works. The steps are the same three commands. `env "PATH=$PATH"` keeps the `netdryrun` that `pip` installed on the path under `sudo`:

```bash
bash -c "$(curl -sL https://get.containerlab.dev)" -- -v 0.81.1
pip install netdryrun
sudo env "PATH=$PATH" netdryrun run network/ --junit netdryrun-junit.xml --json netdryrun-report.json
```

Exit codes: `0` passed, `1` a check failed, `2` a setup problem (bad YAML, the lab didn't start), `3` inconclusive (the lab never reached a testable state; rerun it).

## Times

Wall-clock for `netdryrun run`, including deploying and destroying the lab, with images already pulled. Measured on 2026-10-27 on WSL2 (20 cores, 16 GB), containerlab 0.81.1, Netdryrun 0.3.0, from copies of the example folders with their own lab names:

| Run | Result | Exit | Time |
|---|---|---|---|
| `examples/frr-bgp` (7 checks and a link-failure scenario) | `PASSED: 11 passed, 0 failed` | `0` | 88 s |
| `examples/frr-bgp-broken` | `FAILED: 5 passed, 1 failed` | `1` | 38 s |

The failing run is shorter because it has no failure scenario. The [examples page](../examples.md) shows 84 s and 45 s for the same two labs from earlier runs on the same machine and date; runs differ by several seconds. On GitHub-hosted `ubuntu-latest` runners, the whole job (installing containerlab and Netdryrun, pulling FRR, running) took 100 to 107 s for `frr-bgp` and 54 to 66 s for `frr-bgp-broken`, over three CI runs on `main` on 2026-10-27, before the 0.3.0 release added a `bgp_route` check to `frr-bgp`; see [the FAQ](../faq.md#how-long-does-a-run-take-and-what-does-ci-cost). On a private repository, jobs are billed by the minute, rounded up: the `frr-bgp` job uses 2.

## Gotchas

- **eBGP without a policy may exchange nothing.** Under FRR's default `traditional` profile, `bgp ebgp-requires-policy` is on (RFC 8212): an eBGP neighbor with no route-map in or out reaches `Established` and accepts and sends nothing. Under `frr defaults datacenter`, which the examples use, it's off. On FRR 10.4.1 with no route-maps, the `traditional` side shows:

    ```text
    Neighbor        V         AS   MsgRcvd   MsgSent   TblVer  InQ OutQ  Up/Down State/PfxRcd   PfxSnt Desc
    10.9.0.2        4      65002        12        11        1    0    0 00:00:24     (Policy) (Policy) FRRouting/10.4.1_git
    ```

    A `bgp_session` check passes either way; `bgp_prefixes` and `route` checks catch it. Keep the same `frr defaults` line in the lab as in production.
- **containerlab gives `linux` nodes a default route** via the management network. FRR sees it as a kernel route with distance 0, which beats a static or BGP default. If your change or your checks involve the default route, delete it with `exec: ["ip route del default"]` on the node, as the [hidden leak lab](https://github.com/netdryrun/netdryrun/tree/main/examples/srl-hidden-leak) does.
- **Lab names are global on a machine.** Two jobs on one self-hosted runner, or two copies of a folder, must use different `name:` values in `topology.clab.yml`.
- **`frr.conf` is read at boot.** Netdryrun deploys a fresh lab on every run, so the pull request's file is always the one tested. If you poke at a lab kept with `--keep`, changes you make in `vtysh` are not in the file.


---
Source: https://netdryrun.com/guides/sonic-ci/

# Test a SONiC change in CI

SONiC is different from most network OSes in a lab: the virtual switch image boots with no configuration, and its services come up one by one after the container starts. This guide shows how to get the image, configure the switch once it's ready, and check its routing on every pull request. It uses [`examples/sonic-frr`](https://github.com/netdryrun/netdryrun/tree/main/examples/sonic-frr): a SONiC VS switch peering eBGP with an FRR router. Every output below is from a real run.

## 1. Get the image

`docker-sonic-vs` is the virtual switch the SONiC project builds for its own tests. It is not on a container registry: the SONiC build server publishes it as a compressed file. Download it and load it into Docker:

```bash
curl -L -o docker-sonic-vs.gz \
  "https://sonic-build.azurewebsites.net/api/sonic/artifacts?branchName=master&platform=vs&target=target/docker-sonic-vs.gz"
docker load -i docker-sonic-vs.gz      # creates docker-sonic-vs:latest
```

The file is about 230 MB (232,075,139 bytes for the build used on this page, downloaded on 2026-10-27). Loaded, the image is 1.92 GB.

`branchName=master` is the latest build, so it changes over time. For repeatable CI, keep the file you tested with (as a release asset or in a cache) instead of downloading `master` on every run.

## 2. The lab

```yaml title="topology.clab.yml"
name: ndr-sonic-frr

topology:
  nodes:
    sonic1:
      kind: sonic-vs
      image: docker-sonic-vs:latest
    frr1:
      kind: linux
      image: quay.io/frrouting/frr:10.4.1
      binds:
        - configs/daemons:/etc/frr/daemons
        - configs/vtysh.conf:/etc/frr/vtysh.conf
        - configs/frr1.conf:/etc/frr/frr.conf
  links:
    - endpoints: ["sonic1:eth1", "frr1:eth1"]
```

In `kind: sonic-vs`, the container's `eth1` is the SONiC port `Ethernet0`. The topology names `eth1`; SONiC commands and checks use `Ethernet0`.

## 3. Configure SONiC after boot: `setup`

There's no startup config. Instead, `netdryrun.yml` lists `setup` commands that Netdryrun runs inside the node after deploying the lab and before any check:

```yaml title="netdryrun.yml"
lab: topology.clab.yml
timeout: 180

nodes:
  sonic1:
    setup:
      - supervisorctl status orchagent | grep -q RUNNING && supervisorctl status bgpd | grep -q RUNNING
      - config interface ip add Ethernet0 10.0.40.1/30 && config interface startup Ethernet0
      - config loopback add Loopback0; config interface ip add Loopback0 192.168.40.1/32
      - >-
        vtysh -c "conf t" -c "router bgp 65040" -c "bgp router-id 40.40.40.40" -c "no bgp ebgp-requires-policy"
        -c "neighbor 10.0.40.2 remote-as 65020" -c "address-family ipv4 unicast" -c "network 192.168.40.1/32"
```

Line by line:

1. **Wait for the services.** The container is "running" long before SONiC is. `orchagent` (which programs the switch) and `bgpd` (FRR inside SONiC) have to be `RUNNING` before `config` commands and `vtysh` work. This line fails until they are.
2. **Address and enable the port** with SONiC's `config` CLI, which writes to CONFIG_DB like on a real switch.
3. **A loopback** for the announced prefix.
4. **BGP**, configured in the FRR that runs inside SONiC, through `vtysh`.

Each line is retried every 5 seconds until it succeeds, within a shared budget of 300 seconds. A line runs again from the start if any part of it fails, so put the part that can fail first (as line 1 does), and keep lines that change state safe to run twice.

## 4. The checks that matter for SONiC

```yaml
checks:
  - type: bgp_session
    node: sonic1
    neighbor: 10.0.40.2
  - type: route
    node: sonic1
    prefix: 192.168.20.0/24
    protocol: bgp
  - type: route
    node: frr1
    prefix: 192.168.40.1/32
    protocol: bgp
  - type: ping
    node: sonic1
    source: 192.168.40.1
    target: 192.168.20.1
  - type: bgp_prefixes
    node: frr1
    neighbor: 10.0.40.1
    min: 1
    max: 5
  - type: bgp_route
    node: sonic1
    prefix: 192.168.20.0/24
    as_path: "65020"
    local_pref: 100
    next_hop: 10.0.40.2

scenarios:
  - name: SONiC port Ethernet0 goes down
    link_down: {node: sonic1, interface: Ethernet0}
    checks:
      - {type: bgp_session, node: frr1, neighbor: 10.0.40.1, state: down}
      - {type: route, node: frr1, prefix: 192.168.40.1/32, protocol: bgp, present: false}
```

What to know about these on SONiC:

- **Routing state comes from the FRR inside SONiC.** The `sonic` driver reads sessions, routes and BGP paths through `vtysh`, exactly as on FRR. A route check says what SONiC's routing stack selected. It does not read what `orchagent` programmed (APPL_DB, ASIC_DB).
- **`ping` covers the data path.** It runs from the switch with the loopback as source, so it only passes if the port, its address and the route all work. Keep at least one ping per change.
- **Check from the other side too.** `route` and `bgp_prefixes` on `frr1` prove what SONiC actually announces, which is what a policy change on the switch affects.
- **A port-down scenario uses the SONiC name.** `link_down` on `Ethernet0` takes the port down inside the switch. The scenario then checks that the peer sees the session drop and the route withdrawn, and Netdryrun brings the port back afterwards.
- **Give it time.** `timeout: 180` covers the slow boot; the `setup` budget is separate.

## 5. Run it locally

```bash
pip install netdryrun
netdryrun run examples/sonic-frr
```

```text
Netdryrun 0.3.0: 6 checks from examples/sonic-frr/netdryrun.yml
Deploying lab ndr-sonic-frr (2 nodes); this usually takes 30-90 s, longer the first time images are pulled...
Running setup on sonic1...
setup done on sonic1 (4 commands)
  [PASS] sonic1: BGP session to 10.0.40.2 is established -- state is established (13.5s)
  [PASS] sonic1: route 192.168.20.0/24 via bgp is present -- active via bgp (13.5s)
  [PASS] frr1: route 192.168.40.1/32 via bgp is present -- active via bgp (13.5s)
  [PASS] sonic1: ping 192.168.20.1 from 192.168.40.1 expects success -- 3/3 replies (need 2) (13.5s)
  [PASS] sonic1: BGP best path for 192.168.20.0/24 has as-path '65020', local-pref 100, next hop 10.0.40.2 -- best path: as-path '65020', next hop 10.0.40.2, local-pref 100, MED 0, communities none (13.5s)
Convergence checks done; settling 10s before post-convergence checks...
  [PASS] frr1: prefixes from 10.0.40.1 >= 1 and <= 5 -- 1 ipv4-unicast prefixes accepted (held 10s, 5 samples) (10.2s)
Scenario: SONiC port Ethernet0 goes down
  [PASS] [SONiC port Ethernet0 goes down] frr1: BGP session to 10.0.40.1 is down -- state is connect (held 10s, 5 samples) (10.1s)
  [PASS] [SONiC port Ethernet0 goes down] frr1: route 192.168.40.1/32 via bgp is absent -- absent (held 10s, 5 samples) (10.1s)
Restored 1 link(s) and 0 route injection(s); settling 10s
Destroying lab...
PASSED: 8 passed, 0 failed (8 checks)
```

## 6. Run it on every pull request

The workflow is the usual one with one extra step: load the image before Netdryrun deploys the lab. containerlab only pulls images that are missing, so the loaded `docker-sonic-vs:latest` is used as is.

```yaml title=".github/workflows/sonic-dryrun.yml"
name: SONiC dry run
on:
  pull_request:
    paths:
      - "network/sonic/**"
jobs:
  dryrun:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Load docker-sonic-vs
        run: |
          curl -fsSL -o docker-sonic-vs.gz \
            "https://sonic-build.azurewebsites.net/api/sonic/artifacts?branchName=master&platform=vs&target=target/docker-sonic-vs.gz"
          docker load -i docker-sonic-vs.gz
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: network/sonic/
```

On other CI systems: load the image the same way, then install containerlab and Netdryrun and run `sudo env "PATH=$PATH" netdryrun run <folder>`, as in the [FRR guide](frr-ci.md#4-run-it-on-every-pull-request).

This workflow is a recipe, not something Netdryrun's own CI runs yet: SONiC isn't in the project's CI, and the workflow hasn't been run on a hosted runner. The runs on this page are local.

## Times

Wall-clock for `netdryrun run`, including deploying the lab, the `setup` lines, the checks, the port-down scenario and destroying the lab, with both images already loaded. Measured on 2026-10-27 on WSL2 (20 cores, 16 GB), containerlab 0.81.1, Netdryrun 0.3.0, from a copy of the example folder with its own lab name:

| Run | Result | Exit | Time |
|---|---|---|---|
| `examples/sonic-frr` (6 checks and a port-down scenario) | `PASSED: 8 passed, 0 failed` | `0` | 97 s |

The checks passed 13.5 s after `setup` finished. The [examples page](../examples.md) shows 90 s from an earlier run on the same machine and date; runs differ by a few seconds. In CI, add the time to download the 230 MB image, which depends on the runner's network; caching the file avoids it.

## Gotchas

- **"Running" isn't ready.** The container is up long before SONiC's services are, and `config` and `vtysh` don't work until they are. Make the first `setup` line a readiness check, so every later line starts on a ready switch.
- **`no bgp ebgp-requires-policy`.** With it on (RFC 8212, FRR's default profile), an eBGP neighbor with no route-map comes up and exchanges nothing; see the [FRR guide's gotchas](frr-ci.md#gotchas). The example turns it off to stay short. With real policies, attach route-maps instead.
- **The image is big and not on a registry.** About 230 MB to download and 1.92 GB once loaded. Cache it in CI.
- **Port names differ between the topology and the switch:** `eth1` in `topology.clab.yml`, `Ethernet0` in SONiC commands, checks and scenarios.
- **Memory:** about 300 MiB for the SONiC VS node once up ([FAQ](../faq.md#how-much-memory-and-cpu-does-it-need)).


---
Source: https://netdryrun.com/reference/config/

# netdryrun.yml reference

`netdryrun.yml` describes one lab and the behavior you expect from it. Commands accept either the file or the folder that contains it (`netdryrun run network/` reads `network/netdryrun.yml`).

```yaml title="netdryrun.yml"
lab: topology.clab.yml
timeout: 90
nodes:
  r1:
    driver: frr
checks:
  - type: bgp_session
    node: r1
    neighbor: 10.0.12.2
  - type: route
    node: r1
    prefix: 0.0.0.0/0
    protocol: bgp
    present: false
```

Validation is strict, and every problem is an error (exit code `2`) before anything is deployed. Run `netdryrun validate` to check a file without starting a lab. From 0.3.1:

- **Unknown keys are errors at every level**: the top level, `nodes.<node>`, checks, scenarios, `link_down`, `node_isolated` and `inject_routes`. A misspelled key gets a suggestion: `unknown keys ['presnt'] for type route; did you mean 'present'?`. Before 0.3.1, a misspelled key at the top level, under `nodes` or inside a fault was ignored, so a misspelled block of checks never ran (keys inside a check or a scenario were already refused).
- **Duplicate keys are errors**, at any depth: `duplicate key 'present' (first defined on line 12)`. Plain YAML keeps the last one silently. The topology file is read the same way. YAML merge keys (`<<: *anchor`) are allowed.
- **Malformed YAML** is reported on one line, with its position: `netdryrun.yml: not valid YAML at line 7, column 3: ...`.
- **Booleans must be real booleans**: `present` and `active` take unquoted `true` or `false`. A quoted `"false"`, `0`, `null` or an empty value is refused instead of being read as something else.
- **Values come from fixed lists** where the drivers only understand certain values: `type`, `state`, `afi`, `protocol`, `expect` and `nodes.<node>.driver`. A near miss gets a suggestion (`afi: ipv4` → `did you mean 'ipv4-unicast'?`).
- **Numbers are range-checked**: see the tables below. Required keys missing, IP addresses that don't parse, and keys that make no sense together (`min_replies` with `expect: failure`, `hold` on a check where it has no effect) are errors too.

## Top-level keys

| Key | Required | Default | Meaning |
|---|---|---|---|
| `lab` | yes | | Path to the containerlab topology file, relative to `netdryrun.yml`. The topology must have a `name`. |
| `timeout` | no | `120` | Seconds a check may wait (see [convergence semantics](#convergence-semantics)). A positive number, at most `86400`. Each check can override it. |
| `checks` | yes | | List of checks. At least one is required. |
| `nodes` | no | | A mapping of node name to settings. Each node accepts only `driver` and `setup`. |
| `nodes.<node>.driver` | no | detected | Force the driver for a node: `frr`, `srlinux`, `eos` or `sonic`. See [drivers](#drivers). |
| `nodes.<node>.setup` | no | | Shell commands run inside the node after deploy, before any check. Each is retried every 5 s until it succeeds (the NOS may still be booting), within a shared 300 s budget. For NOSes that are configured after boot, such as SONiC. |
| `scenarios` | no | | A non-empty list of [failure scenarios](#failure-scenarios). |

No other top-level key is accepted.

## Keys every check accepts

| Key | Default | Meaning |
|---|---|---|
| `type` | required | `bgp_session`, `bgp_prefixes`, `route`, `bgp_route` or `ping` |
| `node` | required | Node name from the topology (for example `r1`) |
| `name` | generated | Label used in reports. The default describes the check, for example `r1: BGP session to 10.0.12.2 is established`. |
| `timeout` | top-level `timeout` | Seconds this check may wait to pass. A positive number, at most `86400`. |
| `hold` | `--hold` (10) | Seconds a [post-convergence check](#convergence-semantics) must hold. A positive number, at most `86400`. Only allowed on post-convergence checks: on any other check it would have no effect, so it is an error. |
| `vrf` | `default` | VRF (FRR, SONiC, Arista EOS) or network-instance (SR Linux) to look in. Letters, digits and `. _ : -`, at most 64 characters: the name goes into the device's CLI command, so anything else is refused (0.3.1 and later; 0.3.0 did not check it). `vrf: all` is refused: name one VRF per check. A VRF that doesn't exist on the node is an error on every driver, never "no routes" (see [drivers](#drivers)). |

Each check type accepts only these keys and the ones in its own table.

IP addresses and prefixes are normalized, so `2001:db8:0::1` in YAML matches `2001:db8::1` on the device. Prefixes with host bits set are reduced to the network (`10.0.0.1/24` becomes `10.0.0.0/24`).

## Check types

### bgp_session

A BGP session reaches a state.

| Key | Required | Default | Meaning |
|---|---|---|---|
| `neighbor` | yes | | Neighbor IP address as configured on `node` |
| `state` | no | `established` | One of `idle`, `connect`, `active`, `opensent`, `openconfirm`, `established`, or `down` (any state except established). Case-insensitive |

The check fails if the neighbor is not configured. A `state` other than `established` makes it a post-convergence check.

```yaml
- type: bgp_session
  node: r1
  neighbor: 10.0.12.2
```

### bgp_prefixes

The number of prefixes accepted from a neighbor is within a range. Accepted means received minus rejected by import policy.

| Key | Required | Default | Meaning |
|---|---|---|---|
| `neighbor` | yes | | Neighbor IP address |
| `min` | one of `min`, `max`, `exact` | | Lower bound, inclusive |
| `max` | one of `min`, `max`, `exact` | | Upper bound, inclusive |
| `exact` | one of `min`, `max`, `exact` | | Exact count |
| `afi` | no | `ipv4-unicast` | Address family: exactly one of `ipv4-unicast`, `ipv6-unicast` or `evpn` (case-insensitive). `evpn` is supported on FRR and SONiC only, not on SR Linux or Arista EOS |

Rules:

- At least one of `min`, `max` or `exact` is required.
- `exact` cannot be combined with `min` or `max`.
- `min` must not be greater than `max`.
- All three are non-negative integers.
- `min: 0` on its own is refused: it always passes. Use `min: 1` or more, or add `max`.
- Any other `afi` is refused (from 0.3.1). An address family the drivers don't report would read as 0 prefixes, which passes `max` and `exact: 0`.
- `afi: evpn` on an SR Linux or Arista EOS node is refused before the lab deploys (exit code `2`): those drivers read only the IPv4 and IPv6 unicast counts (SR Linux has no received-routes counter for EVPN), so an EVPN count would always read 0. SR Linux refuses it from 0.3.1; before, the count read 0 and passed `max`.
- The session must be `established`. Counters reset to 0 when a session drops, so a count from a down session would satisfy `max` by accident; Netdryrun fails the check instead.
- If the session is established but the address family reports nothing, the count is 0.
- A check with `max` or `exact` is a post-convergence check. A check with only `min` is a positive check.

```yaml
- type: bgp_prefixes
  node: r1
  neighbor: 10.0.12.2
  min: 1
  max: 10          # guards against a route leak flooding r1
```

### route

A route is present in (or absent from) the routing table.

| Key | Required | Default | Meaning |
|---|---|---|---|
| `prefix` | yes | | IPv4 or IPv6 prefix |
| `present` | no | `true` | `false` means the route must be absent. Unquoted `true` or `false` only |
| `protocol` | no | any | Only count routes from this protocol: one of the names in [protocol names](#protocol-names). Case-insensitive |
| `vrf` | no | `default` | VRF or network-instance |
| `active` | no | `true` | With `present: true`: `false` also accepts a route that is in the table but not selected (for example a BGP default losing to a local one). Unquoted `true` or `false` only; not allowed with `present: false` |

- **Present** means an *active* route matches: selected and installed on FRR, `active` on SR Linux.
- **Absent** means no matching route at all, active or not. A BGP path that was received from a neighbor still counts as present, valid or not, selected or not (for example a leaked default losing to a local one), so `present: false` fails. This is how the [failing example](../index.md#a-failing-run) is caught. Every driver reads the BGP table for this as well as the routing table; there, only paths received from a neighbor count, not the router's own (network statements, redistribution, SR Linux's static and interface routes).
- `protocol` must be a name the drivers report. `ebgp` and `ibgp` are refused: drivers report both as `bgp`. A name outside the list would match nothing and silently pass `present: false`.
- `present: false` makes it a post-convergence check.

```yaml
- type: route
  node: r1
  prefix: 192.168.3.0/24
  protocol: bgp
```

### bgp_route

Attributes of the BGP **best path** for a prefix: communities, AS path, local preference, MED, next hop. Many real policy bugs live here: a route that is still present but lost its community, got the wrong local preference, or now goes the long way. `route` reads the routing table; `bgp_route` reads the BGP table.

| Key | Required | Default | Meaning |
|---|---|---|---|
| `prefix` | yes | | IPv4 or IPv6 prefix, matched exactly |
| `communities` | no | | The best path must carry **all** of these. Standard (`'65000:100'`), large (`'65000:1:2'`) or well-known names (`no-export`, `no-advertise`, `no-peer`, `blackhole`, `graceful-shutdown`, `accept-own`, `llgr-stale`, `no-llgr`, `no-export-subconfed`) |
| `without_communities` | no | | The best path must carry **none** of these. Same forms as `communities` |
| `as_path` | no | | Exact AS path, ASNs separated by spaces: `"65002 65003"`. `""` is the empty path of a locally originated route. AS sets are written `{65004,65005}` |
| `as_path_regex` | no | | Python regular expression searched in the AS path string, for example `"^65002 "` (learned from 65002) or `"(^| )65666( |$)"` (passes through 65666). It runs with no time limit, so avoid nested repeats such as `(\d+ ?)+$` that can backtrack for minutes |
| `local_pref` | no | | Exact local preference |
| `med` | no | | Exact MED. A path without MED counts as `0`, as best-path selection treats it by default |
| `next_hop` | no | | Exact next hop address |
| `present` | no | `true` | `false` means no path at all for the prefix in the BGP table, best or not, valid or not. Unquoted `true` or `false` only |
| `vrf` | no | `default` | VRF or network-instance |

Rules:

- Without attribute keys, the check passes when a best path exists.
- **Quote communities.** YAML reads some unquoted values as numbers (`65000:10` is a base-60 number to YAML 1.1), so an unquoted community that YAML turns into a number is a config error.
- A community can't be in both `communities` and `without_communities`.
- `present: false` can't be combined with attribute keys. To forbid a community on the best path, use `without_communities`.
- The check fails if there is no path, or no best path (for example when the next hop is unreachable). The failure detail shows what the best path actually carries.
- **Local preference** is the effective value: a path without a LOCAL_PREF attribute (eBGP-learned or local) gets the device's default (FRR and SONiC: `bgp default local-preference`; SR Linux: the neighbor's `local-preference`; Arista EOS reports it directly). The exception is a locally originated path on Arista EOS, which reports no local preference; asserting `local_pref` on it fails with "not set".
- **Next hop** is the address the device reports. For an IPv6 path FRR may list only the link-local next hop.
- `present: false`, and any attribute key (`communities`, `without_communities`, `as_path`, `as_path_regex`, `local_pref`, `med`, `next_hop`), make it a post-convergence check. The best path can change when a slower session comes up, so an attribute check could pass on a temporary best path before the real one arrives; it is judged only after every BGP session on the node is up and the settle delay, and must hold (0.3.1 and later; 0.3.0 judged attribute checks other than `without_communities` on 2 early samples). A `bgp_route` with no attribute keys (the best path exists) is a positive check.

```yaml
- type: bgp_route         # customer routes are tagged and preferred
  node: r1
  prefix: 192.168.20.0/24
  communities: ["65000:100", no-export]
  local_pref: 200
  as_path: "65020"

- type: bgp_route         # the internal tag must never reach the peer
  node: peer1
  prefix: 192.168.20.0/24
  without_communities: ["65000:666"]
```

### ping

Reachability from a node.

| Key | Required | Default | Meaning |
|---|---|---|---|
| `target` | yes | | Destination IP address |
| `source` | no | | Source IP address (passed as `ping -I`) |
| `expect` | no | `success` | `success` or `failure` |
| `count` | no | `3` | Packets to send. An integer from 1 to 1000. |
| `min_replies` | no | `count - 1`, at least 1 | Replies needed for `expect: success`: an integer from 1 to `count`. One lost packet is tolerated by default (first-packet ARP). Not allowed with `expect: failure` |
| `vrf` | no | `default` | Runs in the VRF (`ip vrf exec` on FRR) or network-instance namespace (`srbase-<name>` on SR Linux) |

- `expect: failure` passes only with 0 replies, and is a post-convergence check.
- `expect: failure` also passes when ping reports the destination unreachable without sending anything: "Network unreachable" (or "Network is unreachable"), "No route to host" or "Destination unreachable" (0.3.1 and later). With no route at all, ping prints one of these and no statistics.
- If ping did not run at all for any other reason (bad source address, missing VRF), the check fails with an error. It never counts as a successful "failure".

```yaml
- type: ping
  node: r1
  source: 192.168.1.1
  target: 192.168.3.1
```

## Failure scenarios

`scenarios:` runs extra checks while something is wrong, then puts it right. Use it to prove the network survives a failure, for example that traffic reroutes when an uplink dies, or that your max-prefix limit and import filters hold when a neighbor misbehaves.

```yaml
scenarios:
  - name: r1-r2 link fails
    link_down: {node: r1, interface: eth1}   # or a list of links
    checks:
      - {type: route, node: r1, prefix: 192.168.2.0/24, protocol: bgp}   # rerouted via r3
      - {type: ping, node: r1, source: 192.168.1.1, target: 192.168.2.1}
      - {type: bgp_session, node: r1, neighbor: 10.0.12.2, state: down}

  - node_isolated: r2          # all of r2's lab links down
    checks:
      - {type: route, node: r1, prefix: 192.168.2.0/24, present: false}

  - name: customer floods us
    inject_routes: {node: ce1, count: 200, from: 10.100.16.0/24}   # ce1 announces 200 extra /24s
    checks:
      - {type: bgp_prefixes, node: up1, neighbor: 10.0.2.1, max: 51}   # the max-prefix limit holds

  - name: peer announces what it does not own
    inject_routes: {node: peer1, prefixes: [10.100.0.0/25, 8.8.8.0/24], as_path: [65400]}
    checks:
      - {type: bgp_prefixes, node: pe2, neighbor: 10.0.4.2, max: 1}   # the import filter holds
      - {type: route, node: ce1, prefix: 10.100.0.0/25, protocol: bgp, present: false}
```

| Key | Meaning |
|---|---|
| `name` | Label shown before each check (default: generated from the faults) |
| `link_down` | `{node, interface}` or a list of them; no other keys. Interface names as seen inside the node (for example `eth1` on FRR): a Linux interface name of at most 15 letters, digits and `. _ @ -` (checked from 0.3.1). SR Linux links can't be failed yet; fail the FRR or Linux side instead |
| `node_isolated` | A node name, `{node}`, or a list of them: every lab link of that node goes down |
| `inject_routes` | `{node, prefixes}` or `{node, count}` (or a list of them): the node announces extra routes. 0.3.1 and later. See below |
| `checks` | Same check types and keys as the top level. See [scenario timing](#scenario-timing) |

A scenario needs at least one fault and at least one check, and accepts no other keys. Scenarios run after the main checks, one at a time. Links and injected routes are always restored afterwards, even if a check fails, and Netdryrun waits for the network to settle before the next scenario. If the network does not recover, the checks that passed before the scenario are reported as failed `[after <scenario>] recovers: ...` checks, and later scenarios are skipped.

### Scenario timing

A scenario's positive checks ("the route is still there", "ping still works") are already true before the network notices the failure, so Netdryrun makes sure they are never judged on the state from before the fault (0.3.1 and later):

1. Before taking links down, it notes the established BGP sessions that run over them, on both ends of each link (looking through bridges), in the default VRF and the VRFs the scenario's checks use. If that BGP state, or the addresses of the downed interfaces, can't be read, the run stops with exit code `2` naming the node, before any link goes down: "couldn't read it" is never taken for "there are none". A node no driver can read (a Linux host) and a VRF the node doesn't have have no sessions to note.
2. After applying the faults, it waits until every one of those sessions is down **on both ends**: proof that the network saw the fault. The wait is capped at the largest `timeout` of the scenario's checks. If the fault still isn't visible by then, the run stops with exit code `2` and "the fault did not take effect", never a verdict. Without BFD, BGP can take its hold time (up to 180 s) to notice a failure: raise the checks' `timeout`, or lower the hold timers in the lab.
3. It waits the settle delay (`--settle`), so withdrawals propagate beyond the adjacent routers.
4. Positive checks must pass on 2 consecutive samples **and** keep passing for the hold window (`--hold`; a positive check can't set its own `hold`): a redundancy claim is about the whole failure, not one instant. A check that passes at first and then fails within the window fails.
5. Post-convergence checks then wait for the same [BGP gate](#convergence-semantics) as at the top level: every BGP session on their node up, with unchanged prefix counts on 2 consecutive samples, capped at their `timeout`. Sessions over the downed links don't count (the fault took them down), nor do sessions a `bgp_session` check in the scenario or at the top level expects in another state. If another session on the node stays down, the checks fail as **not evaluated**; a session the fault takes down indirectly (for example iBGP between loopbacks whose only path was the downed link) needs a `bgp_session` check with `state: down` in the scenario. Then the checks must hold, as everywhere else. 0.3.1 and later.

When the state was read and no BGP session runs over the downed links (static routing, a link without BGP, iBGP between loopbacks over an IGP), step 2 has nothing to observe; steps 3 to 5 still apply, so give such scenarios a `--settle` that covers the failure detection time. `inject_routes` faults have no step 2: Netdryrun instead waits until the injected prefixes are in the node's own BGP table. That alone doesn't show they reached the node under test; the BGP gate in step 5 does, for post-convergence checks: their node's prefix counts must stop changing first. The limit: a peer with a long advertisement interval (for example eBGP with a 30-second `advertisement-interval`) can hold the routes back for longer than 2 samples 3 seconds apart, so they can still arrive after the gate. Raise `--settle` above the advertisement interval for such labs.

### Injecting routes

New in 0.3.1: Netdryrun 0.3.0 rejects the key as unknown.

`inject_routes` makes a node announce routes it normally doesn't, so you can test what the rest of the network does with them: a customer leaking more-specifics, a peer announcing someone else's prefix, a flood that should trip a max-prefix limit.

| Key | Required | Meaning |
|---|---|---|
| `node` | yes | The node that announces the routes. It must be an FRR node with `router bgp` in the default VRF |
| `prefixes` | one of | A prefix or list of prefixes, IPv4 or IPv6 |
| `count` | one of | Announce this many consecutive prefixes (1 to 10000), starting at `from` |
| `from` | no | First prefix for `count`; its length is used for all of them. Default `100.64.0.0/24` |
| `as_path` | no | List of AS numbers prepended to the injected routes, so they look learned from those networks |

On the node, Netdryrun adds a blackhole static route and a BGP `network` statement per prefix (with `as_path`, through a route-map named `NDR-INJECT`). It applies them with `vtysh -f` and waits until every prefix is in the node's own BGP table before running the scenario's checks (whose post-convergence checks then wait for the BGP gate on their own node; see [scenario timing](#scenario-timing)). Afterwards it removes exactly what it added and waits until the prefixes are gone. What the node's neighbors do with the routes is up to the policy under test: an outbound filter on the node itself can still stop them.

Limits: only FRR nodes are supported. Any other node is refused before the lab deploys; inject the routes from an FRR neighbor instead. A prefix that is already a `network` statement or a static route on the node is refused, because removing it afterwards would delete real config. IPv6 prefixes need the BGP sessions to carry IPv6 unicast.

## Convergence semantics

Networks need time to converge, and some checks are trivially true before they do. Netdryrun splits checks into two groups.

**Positive checks** (session `established`, prefix count with only `min`, route present, a `bgp_route` best path that exists with no attribute asserted, ping expected to succeed):

- Polled every 3 seconds until they pass on **2 consecutive samples**, or until `timeout` expires.
- A single lucky sample is not enough. If the last sample passed but the streak was too short, the result says "not stable". If the check passed some samples but not consistently, the result says "flapping".

**Post-convergence checks** are the ones that would pass on a network that has not come up yet:

- routes that must be absent (`present: false` on `route` or `bgp_route`)
- best-path attributes (`bgp_route` with any of `communities`, `without_communities`, `as_path`, `as_path_regex`, `local_pref`, `med`, `next_hop`): a best path seen while a slower session is still coming up can be replaced when it arrives
- pings that must fail (`expect: failure`)
- sessions expected in a state other than `established`
- prefix counts with an upper bound (`max` or `exact`), since 0 prefixes satisfies `max: 10` while BGP is still starting

They run in this order:

1. Every positive check has finished.
2. **Every BGP session on the node is up.** Positive checks only prove convergence for the sessions and routes you happened to check, and a leak can arrive later over a session nobody checked. So for each node (and VRF) that carries a post-convergence check, Netdryrun waits until every configured BGP neighbor there is `established`, with unchanged prefix counts, on 2 consecutive samples. Neighbors that a `bgp_session` check expects in another state (for example `state: down`) don't count. The wait is capped at the largest `timeout` of that node's post-convergence checks. If a session there never comes up, those checks fail as **not evaluated**, naming the session: a down session is a finding, as everywhere else. If a session is down on purpose, add a `bgp_session` check with `state: down` for it. (A node that never answers with BGP state, or whose positive checks never got usable state, is not waited for; prefix counts still changing at the cap don't block.) A node that answers with **no BGP neighbors at all** is not converged: that is what a node answers before its BGP config is applied, and a leak can arrive once it is. Netdryrun keeps waiting, up to the cap; if the node still reports no neighbors then, its post-convergence checks run anyway, each with a warning in its result ("reported no BGP neighbors for N s; the check was evaluated without BGP convergence"), and the verdict is unchanged. So a node that doesn't run BGP adds one `timeout` of waiting before its post-convergence checks. 0.3.1 and later.
3. A settle delay (`--settle`, default 10 seconds; at least 30 seconds if the file has no positive checks, because nothing else has shown that the network converged).
4. Each one must then hold for the hold window (`--hold` or the check's `hold`, default 10 seconds), sampled every 3 seconds. A violation at any sample fails the check immediately.

Prefix counts with an upper bound start like this (step 4), because counters ramp up and the BGP gate has already waited for stable counts:

- `max` only: no wait. The count must be within `max` from the first sample of the hold window to the last (0 prefixes is within any `max`).
- `exact: N` (N at least 1) and `min` with `max`: first a short wait, up to 30 seconds (or `timeout` if shorter), for the count to reach at least N (or `min`); a count that never gets there fails. Then the full condition (`exact`, or the whole range) must hold on every sample of the hold window, so a count that overshoots fails.
- `exact: 0`: no wait; it must hold like `max: 0`.

`hold` is accepted only on post-convergence checks. A positive check passes after 2 consecutive passing samples, so a `hold` on it would be ignored; that is an error rather than a silent no-op. (Inside a scenario, positive checks do hold for `--hold`; see [scenario timing](#scenario-timing).)

Results are reported in the order the checks appear in the file.

## Drivers

A driver turns device state into a common shape. Netdryrun detects it from the topology:

- `kind: nokia_srlinux` or `kind: srl` uses `srlinux`
- `kind: arista_ceos` or `kind: ceos` uses `eos`
- `kind: sonic-vs`, or an image whose name contains `sonic`, uses `sonic`
- an image whose name contains `frr` uses `frr`
- anything else is an error unless you set `nodes.<node>.driver`

| Check | FRR | SR Linux | Arista EOS | SONiC |
|---|---|---|---|---|
| `bgp_session` | yes | yes | yes | yes |
| `bgp_prefixes` (accepted = received minus rejected by policy) | yes | yes | yes | yes |
| `route` present / absent | yes | yes | yes | yes |
| `bgp_route`: communities (standard, large, well-known), AS path, local preference, MED, next hop, absent | yes | yes | yes | yes |
| `ping` success / failure | yes | yes | yes | yes |
| Failure scenarios on the node's own links | yes | not yet (fail the FRR/Linux side instead) | yes | yes |
| `inject_routes` on the node | yes | not yet (inject from an FRR neighbor) | not yet | not yet |
| Tested on a live lab in CI | yes, on every push | yes, on every push | no: parsers tested against output captured from live labs | no: parsers tested against output captured from live labs |

**Received paths count as present on every driver:** a BGP route that lost to a static or local route, or that has an unresolvable next hop, may live only in the BGP table, not the routing table. Every driver reads the BGP table too, so a path received from a neighbor counts as present for `present: false`, valid or not, selected or not. The router's own paths (network statements, redistribution, and on SR Linux its static and interface routes listed in the BGP RIB) don't count as received.

**Errors are never "nothing":** from 0.3.1, a failed command or output a driver doesn't recognize is an error on that sample (the check fails with `error: ...`), never read as "no routes" or "no sessions", which would pass `present: false` or `max`. A VRF that doesn't exist on the node is an error too, on every driver: FRR and SONiC confirm the VRF with `show vrf`, SR Linux reads the network-instance's oper-state, and Arista EOS requires the VRF in the `vrfs` map of its answer. `vrf: all` and other names that mean "every VRF" are refused.

**SONiC:** `docker-sonic-vs` routes with FRR inside the container, so the `sonic` driver reads state through `vtysh` like the FRR driver. The image boots unconfigured; put interface IPs (`config interface ip add ...`) and BGP (`vtysh -c ...`) in `nodes.<node>.setup`. See `examples/sonic-frr`.

**Arista EOS:** cEOS-lab is free from arista.com (account required) and can't be redistributed. Download it yourself, then `docker import cEOS-lab-<version>.tar ceos:<version>`, and use `kind: arista_ceos` with that image.

| Driver | Source of state |
|---|---|
| FRR | `vtysh -c "show ... json"`; accepted prefixes from `acceptedPrefixCounter`; `bgp_route` from `show bgp <afi> unicast <prefix> json` |
| SR Linux | `sr_cli --output-format json "info from state ..."`; accepted = `received-routes` minus `rejected-routes`; `bgp_route` from the `bgp-rib` local RIB and its `attr-sets` |
| Arista EOS | `Cli -c "show ... \| json"`; `bgp_route` from `show ip bgp <prefix> vrf <vrf>` (the best path is the `active` one) |
| SONiC | the FRR commands, through `vtysh` inside the container |

If a driver can't read what a check asks for, the run stops before deploying (exit code `2`) instead of guessing: "`<key>` is not supported on `<driver>`" for a `bgp_route` attribute (today every driver reads every attribute), and "afi evpn is not supported on eos" (or `srlinux`) for an EVPN prefix count on Arista EOS or SR Linux.

Every command and its raw output is kept in the [JSON report](cli.md#json).

## Protocol names

`protocol` on a route check is compared in lower case with the protocol the device reports, after normalization:

| Use | FRR reports | SR Linux reports |
|---|---|---|
| `bgp` | `bgp` | `bgp` |
| `static` | `static` | `static` |
| `connected` | `connected` | `local` |
| `local` | `local` | `host` |
| `ospf` | `ospf` | `ospfv2` |
| `ospf6` | `ospf6` | `ospfv3` |
| `isis` | `isis` | `isis` |

`protocol` must be one of these names (case-insensitive): `bgp`, `connected`, `local`, `static`, `kernel`, `ospf`, `ospf6`, `isis`, `rip`, `ripng`, `aggregate`, `eigrp`, `babel`, `nhrp`, `table`, `sharp`, `pbr`, `openfabric`, `bgp-evpn`, `bgp-vpn`, `dhcp`, `arp-nd`, `gribi`. Any other name is a config error with a suggestion where one is close (`direct` → `connected`, `ospfv3` → `ospf6`); `ebgp` and `ibgp` are refused because drivers report both as `bgp`. Before 0.3.1 an unknown name was passed through, matched nothing, and silently passed `present: false`. The failure detail lists the protocols that were seen.


---
Source: https://netdryrun.com/reference/cli/

# CLI and reports

```text
netdryrun run      [path] [options]   deploy the lab, run checks, destroy the lab
netdryrun check    [path] [options]   run checks against an already running lab
netdryrun validate [path]             validate netdryrun.yml without running anything
netdryrun record   topology.clab.yml  snapshot a known-good lab into a netdryrun.yml baseline
netdryrun mcp                         start the MCP server for AI agents (stdio)
netdryrun feedback                    open a short feedback form on GitHub
netdryrun --version
```

`--debug` (before or after the command: `netdryrun --debug run` or `netdryrun run --debug`) prints the Python traceback of an internal error. Setting `NETDRYRUN_DEBUG=1` does the same.

`path` is `netdryrun.yml` or the folder containing it. Default: the current folder.

## Commands

### run

Deploys the containerlab topology (`containerlab deploy --reconfigure`), runs every check, writes reports, and destroys the lab (`containerlab destroy --cleanup`). The lab is destroyed even when checks fail, unless you ask to keep it.

`run` refuses to start (exit code `2`) when a lab with the same name is already running: another Netdryrun run of the same lab, a lab deployed by hand, or one kept with `--keep`. Redeploying it would reconfigure the other lab's containers, and destroying it afterwards would pull them out from under whoever is using it. The error names a container and the command to remove the lab: `containerlab destroy -t <topology> --cleanup`. Two runs of the same lab started at the same moment on one host are also refused, by a lock (`another Netdryrun run is already using lab '<name>' on this host`). `check` doesn't deploy, so it runs against the existing lab.

### check

Runs the checks against a lab that is already up, for example one left running with `--keep`. It does not deploy or destroy anything. It fails with an error if any of the lab's containers are not running.

### validate

Loads and validates `netdryrun.yml` and prints the parsed checks. It does not need Docker or containerlab.

From 0.3.1 it also reads the topology (strictly: malformed YAML and duplicate keys are errors) and checks what `run` checks before deploying: every node a check, fault or `setup` names exists; the driver can read every key the checks use (for example no `afi: evpn` on SR Linux or Arista EOS); and `inject_routes` names an FRR node. It also checks two things `run` finds out only after deploying: every node a check reads has a driver (detected from its kind and image, or set with `nodes.<node>.driver`), and no `link_down` or `node_isolated` fault targets an SR Linux node. Any of these is an error with exit code `2`. What it can't check without containerlab: whether containerlab accepts the topology itself (a misspelled `kind:`, a missing image).

```text
$ netdryrun validate examples/frr-bgp
OK: examples/frr-bgp/netdryrun.yml (7 checks, lab .../examples/frr-bgp/topology.clab.yml, 3 nodes)
  - [bgp_session] r1: BGP session to 10.0.12.2 is established
  ...
```

### record

```bash
netdryrun record path/to/topology.clab.yml --deploy
```

Snapshots a known-good lab into a `netdryrun.yml` baseline: every established BGP session, every prefix count (exact, or minimums with `--min-prefixes`) and up to 50 BGP routes per node. Commit it, and every later change is tested against today's behavior. Review the file before committing: remove what is allowed to change, and add negative checks for what must never happen.

| Option | Meaning |
|---|---|
| `--out FILE` | Where to write (default: `netdryrun.yml` next to the topology) |
| `--deploy` | Deploy the lab first and destroy it afterwards (otherwise the lab must be running) |
| `--wait SECONDS` | With `--deploy`: time for BGP to converge before recording (default 45) |
| `--min-prefixes` | Record prefix counts as minimums instead of exact |
| `--no-routes` | Don't record individual routes |
| `--attributes` | Also record a `bgp_route` check per BGP route, pinning its best path's AS path, local preference and communities (not MED or next hop, which follow the topology) |
| `--force` | Overwrite an existing file |

## Options

`run` and `check`:

| Option | Default | Meaning |
|---|---|---|
| `--json FILE` | | Write the full evidence report as JSON |
| `--markdown FILE` | | Write a Markdown summary (for PR comments) |
| `--junit FILE` | | Write JUnit XML (for CI test reporting) |
| `--settle SECONDS` | `10` | Wait before post-convergence checks, and in a scenario after the fault took effect |
| `--hold SECONDS` | `10` | How long a post-convergence check must hold (a check's own `hold` key overrides it). In a scenario, positive checks must hold this long too |
| `--debug` | | Print the traceback of an internal error |
| `--no-step-summary` | | Do not append the Markdown summary to `$GITHUB_STEP_SUMMARY` |

`run` only:

| Option | Meaning |
|---|---|
| `--keep` | Leave the lab running afterwards, for debugging |
| `--keep-on-failure` | Leave the lab running only if the run did not pass |

When a lab is kept, Netdryrun prints the command to destroy it. See [convergence semantics](config.md#convergence-semantics) for what `--settle` and `--hold` control.

## Exit codes

| Code | Status | Meaning |
|---|---|---|
| `0` | `passed` | Every check passed |
| `1` | `failed` | At least one check failed |
| `2` | `error` | No verdict: the run could not start or could not finish. See below |
| `3` | `inconclusive` | Checks failed, but the lab never reached a state where they mean anything: the result says nothing about the change. Rules below |
| `130` | `error` | Interrupted by SIGINT (Ctrl-C): no verdict |
| `143` | `error` | Interrupted by SIGTERM (for example a cancelled CI job or `docker stop`): no verdict |
| `129` | `error` | Interrupted by SIGHUP (the terminal closed): no verdict |

**Exit code 2** is used for every run that ends without a verdict (0.3.1 and later):

- a config error: bad YAML, an unknown or duplicate key, a bad value (see [validation](config.md));
- a bad topology, an unknown node, or a check a driver can't read;
- a bad option, for example a negative `--settle`;
- a lab problem: containerlab or Docker missing, deploy failed, containers not running, unknown driver, a lab with the same name already running;
- a scenario whose fault did not take effect within the checks' timeout, or whose BGP state or interface addresses could not be read before the fault, so Netdryrun can't tell when it took effect (see [scenario timing](config.md#scenario-timing));
- a link or injected route that could not be restored after a scenario;
- a report that could not be written (`--json`, `--markdown`, `--junit`, or the GitHub Actions step summary), for example a path in a folder that doesn't exist. The verdict line is still printed and every other report is still written, but the evidence you asked for is missing, so the run exits `2`, with one line per report on stderr: `could not write <path>: <reason>; the verdict was <status>` (0.3.1 and later; 0.3.0 reported an internal error). The status inside the reports that were written is the verdict;
- an internal error (a Netdryrun bug). It is reported on one line, never as a bare traceback, and never as exit code `1`, which would read as "the change broke something". Rerun with `--debug` or `NETDRYRUN_DEBUG=1` for the traceback, and please report it.

The message is one line on stderr. With `--json` on `run` or `check`, a report with `status: error` and the message in `error` is written, including for a config error before anything starts and for an interrupted run.

**Interrupted runs** (codes 129, 130, 143): SIGINT, SIGTERM and SIGHUP all clean up the same way. Netdryrun destroys the lab it deployed (unless `--keep` was set; `--keep-on-failure` doesn't apply, since an interrupted run has no verdict), writes the requested reports with `status: error`, and exits with 128 plus the signal number, the shell convention. A second signal during cleanup doesn't cut it short.

### When a run is inconclusive

A run is `inconclusive` instead of `failed` only when **all** of these hold. The rules are deliberately conservative: when in doubt, the run is `failed`.

1. At least one check failed, and there was no lab or config error (that is `error`).
2. No positive check passed on **any** sample, anywhere in the run, scenarios included. One passing sample anywhere shows a working network, so the failures are findings.
3. No post-convergence check failed with readable state. A leaked route, or a session that is up but must be down, proves a working control plane.
4. Every failed check is on a node that never gave usable state. That means every sample of every `bgp_session` and `bgp_prefixes` check on the node was *unready*: the state command failed or its output could not be read (a CLI that isn't up yet), or BGP had no neighbors at all on the node. A node with no session or prefix checks qualifies only if every sample of every check on it was unready.

A configured BGP session that is down (`idle`, `active`, `connect`, ...) is never unready. An ASN typo, a wrong neighbor address or a shutdown look exactly like a slow lab from the outside, so they stay `failed`. A routing table without the route, and a ping with no replies, are findings for the same reason. So a `timeout` that is merely too short for configured sessions to establish gives `failed`, not `inconclusive`; `inconclusive` is for a node whose CLI or BGP never came up at all.

Known limit: a change that deletes a node's entire BGP configuration looks like a NOS that never started BGP, so it is reported `inconclusive`. It is still never `passed`.

What to do: rerun, raise `timeout`, or check that the lab boots (`containerlab inspect`). Don't change the network change because of an inconclusive run.

The JSON report says why in `inconclusive_reason`, and each unready sample in `history` has `"unready": true`.

## GitHub Actions step summary

When the `GITHUB_STEP_SUMMARY` environment variable is set (it is in GitHub Actions), the Markdown summary is appended to the job page automatically. Use `--no-step-summary` to turn this off.

## Report formats

### Console

One line per check as it finishes, then a summary line:

```text
  [FAIL] r1: route 0.0.0.0/0 via bgp is absent -- unexpectedly present via bgp (not selected) (0.1s)
FAILED: 5 passed, 1 failed (6 checks)
```

### JSON

`--json FILE` writes the full evidence. Schema identifier: `netdryrun.report/v1`. Formal definition: [`report-v1.json`](https://netdryrun.com/schemas/report-v1.json), a JSON Schema (draft 2020-12) that the test suite checks real reports against. Within v1 fields are only added, so validate with extra properties allowed (the schema does).

| Field | Type | Meaning |
|---|---|---|
| `schema` | string | Always `netdryrun.report/v1` |
| `status` | string | `passed`, `failed`, `error` or `inconclusive` (new after 0.2.0; a reader should treat any status it does not know as not passed) |
| `lab` | string | containerlab lab name |
| `config` | string | Path of the `netdryrun.yml` that was run |
| `started`, `finished` | string | UTC timestamps (ISO 8601) |
| `error` | string or null | Why the run has no verdict (config, lab or driver error, interruption, internal error); null otherwise |
| `inconclusive_reason` | string or null | Why the run is `inconclusive` ([rules](#when-a-run-is-inconclusive)); null otherwise |
| `environment` | object | `netdryrun`, `containerlab` and `python` versions, `host` platform, and `nodes` (each with `kind` and `image`) |
| `summary` | object | `passed`, `failed`, `total` |
| `checks` | array | One object per check, in file order (below) |

Each entry in `checks`:

| Field | Type | Meaning |
|---|---|---|
| `name` | string | Check name |
| `type` | string | Check type |
| `params` | object | The check's parameters after normalization |
| `passed` | boolean | Result |
| `detail` | string | Human-readable result, for example `3 ipv4-unicast prefixes accepted` |
| `attempts` | integer | Number of samples taken |
| `duration_s` | number | Seconds spent on the check |
| `started` | string | UTC timestamp |
| `history` | array | Every sample (last 50): `t` (seconds since start), `passed`, `detail`, and `unready: true` on a failing sample where the node gave no usable state |
| `evidence` | array | Raw commands from the final sample: `node`, `cmd`, `rc`, `output`, `stderr` |

Long outputs are truncated (the last 20,000 characters of command output are kept).

### Markdown

`--markdown FILE` writes a short summary: a heading (passed, failed, inconclusive, or could not run), the reason when inconclusive, the pass/fail counts and lab name, a table of checks with failures first, and a footer with the Netdryrun and containerlab versions. This is the same text appended to the GitHub Actions step summary.

### JUnit XML

`--junit FILE` writes one `<testsuite name="netdryrun">` with one `<testcase>` per check:

- `classname` is `netdryrun.<type>`, for example `netdryrun.route`
- a failed check has a `<failure>` whose `message` is the detail and whose body is the evidence as JSON
- in an `inconclusive` run, failed checks have an `<error>` instead of a `<failure>` (they could not run meaningfully), and they count as `errors`, not `failures`
- a lab error adds a testcase named `lab` with an `<error>` element


---
Source: https://netdryrun.com/github-action/

# GitHub Action

The action installs containerlab, installs Netdryrun™, runs your checks, writes a summary to the job page, uploads the JSON and JUnit reports as an artifact, and fails the job if any check fails.

```yaml title=".github/workflows/network-dryrun.yml"
name: Network dry run
on: pull_request
jobs:
  dryrun:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: network/        # folder containing netdryrun.yml
```

It needs a Linux runner with Docker. GitHub-hosted `ubuntu-latest` runners work.

## Inputs

| Input | Default | Meaning |
|---|---|---|
| `path` | `.` | `netdryrun.yml` or the folder containing it |
| `containerlab-version` | `0.81.1` | containerlab version to install, pinned for reproducible runs. Empty means latest. If containerlab is already installed, it is used as is, with a warning if the version differs. |
| `json-report` | `netdryrun-report.json` | Path for the JSON evidence report |
| `junit-report` | `netdryrun-junit.xml` | Path for the JUnit XML report |
| `upload-artifact` | `true` | Upload the reports as a workflow artifact |
| `artifact-name` | `netdryrun-report` | Name of the uploaded artifact |
| `settle` | `10` | Seconds to wait before post-convergence checks |
| `hold` | `10` | Seconds a post-convergence check must hold |
| `pr-comment` | `false` | On pull requests, post one comment with the verdict, failures first, and the evidence for each failed check. Updated in place on every push. Needs `permissions: pull-requests: write` |
| `github-token` | `${{ github.token }}` | Token used for the PR comment |
| `cloud` | `false` | Reserved for Netdryrun Cloud, which is **not available yet**. With `true`, the action tries to POST the JSON report to `cloud-url` with a GitHub OIDC token; that address doesn't resolve today, so nothing is uploaded and you only get a warning ("evidence upload failed", or "needs 'permissions: id-token: write'" without that permission). Leave it off |
| `cloud-url` | `https://cloud.netdryrun.com` | Reserved for Netdryrun Cloud (this address does not exist yet) |

## Outputs

| Output | Meaning |
|---|---|
| `status` | `passed`, `failed`, `error` or `inconclusive` (the lab never reached a testable state, so the run says nothing about the change; the job still fails) |
| `inconclusive-reason` | Why the run was inconclusive; empty otherwise |
| `passed` | Number of passed checks |
| `failed` | Number of failed checks |
| `evidence-url` | Reserved for Netdryrun Cloud; always empty today |

## Examples

### Only run when network files change

```yaml
name: Network dry run
on:
  pull_request:
    paths:
      - "network/**"
jobs:
  dryrun:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: network/
```

### Use the outputs in a later step

```yaml
      - uses: netdryrun/netdryrun@v0.3.1
        id: ndr
        with:
          path: network/
      - if: always()
        env:
          NDR_STATUS: ${{ steps.ndr.outputs.status }}
          NDR_PASSED: ${{ steps.ndr.outputs.passed }}
          NDR_FAILED: ${{ steps.ndr.outputs.failed }}
        run: echo "Netdryrun $NDR_STATUS: $NDR_PASSED passed, $NDR_FAILED failed"
```

### Several labs

```yaml
jobs:
  dryrun:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        lab: [network/core, network/edge]
    steps:
      - uses: actions/checkout@v4
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: ${{ matrix.lab }}
          artifact-name: netdryrun-${{ strategy.job-index }}
```

Give each matrix job its own `artifact-name`; artifact names must be unique within a workflow run.

### Comment the verdict on every pull request

```yaml
name: Network dry run
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  dryrun:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: network/
          pr-comment: true
```

## Security notes

- **A lab is code that runs as root on the runner.** containerlab starts privileged containers with access to the host. Netdryrun passes the lab process a minimal environment (no job tokens, not the runner user's home directory), but that only narrows exposure; it is not a security boundary.
- **Run labs from untrusted pull requests (forks) only in jobs with no secrets**, a read-only `GITHUB_TOKEN`, and without `id-token: write`. Never run them under `pull_request_target`.
- `pr-comment` needs `pull-requests: write`. Grant it only when you use it. Don't grant `id-token: write` for the `cloud` input: Netdryrun Cloud is not available yet.
- Uploaded report artifacts contain raw command output from the lab and are kept for 14 days. Don't put real secrets in lab configs.
- **The PR comment cannot be steered by lab text** (0.3.1 and later; 0.3.0 did not escape it). Check names, details, errors and device output are escaped before they are posted: no HTML, links, images, `@mentions` or `#123` references, and device output stays inside its code block. Report files already in the workspace (committed in the PR, or left by an earlier run on a self-hosted runner) are deleted before the run, and the `status` output is `error` unless the report matches the run's own exit code.
- **Pass outputs to a shell through `env:`**, not by pasting `${{ steps.<id>.outputs.inconclusive-reason }}` into a `run:` script. The reason can quote lab output; from 0.3.1 Netdryrun strips quotes, backslashes, `$` and backticks from it, but `env:` is the safe pattern for any action output.


---
Source: https://netdryrun.com/batfish/

# Batfish, then Netdryrun

[Batfish](https://batfish.org) and Netdryrun™ answer different questions. Batfish reads configs and models the network: nothing has to boot, and in the runs below its analysis took 2 to 6 seconds once the Batfish service was running. Netdryrun boots the configs in a containerlab lab and checks what the routing software really does. Run Batfish first on every commit, and boot the lab only when it passes.

This page reports one measured run of that pipeline: four versions of a small FRR network, each tested by both stages. The code is in [`examples/batfish-pipeline`](https://github.com/netdryrun/netdryrun/tree/main/examples/batfish-pipeline).

## The pipeline

The network is the FRR triangle from [`examples/frr-bgp`](examples.md#frr-bgp): three routers, each in its own AS, each announcing one LAN over eBGP.

1. **Batfish** (`batfish_check.py`, 8 checks): every config parses with no parse warnings, no undefined references, all six BGP sessions establish, r1's best paths to the two other LANs, no router learns a default route, a traceroute from r1's LAN to r2's LAN, and the best path after the r1-r2 link fails (a forked snapshot with the interface deactivated).
2. **Netdryrun** (`netdryrun.yml`, 10 checks): r1's two BGP sessions, the prefix count from r2, the route to r2's LAN and its best path, a ping, no default route on r1 or r3, and the same link failure.

The two stages check the same intent with two differences: Batfish checks for a default route on all three routers, while the lab checks r1 and r3 (r2 is the router that would send it), and the lab adds a prefix count and a ping.

```yaml title="examples/batfish-pipeline/github-workflow.yml"
# Example workflow: copy to .github/workflows/ in your repository and adapt the paths.
# Job 1 runs Batfish on every push; nothing boots. Job 2 boots the lab with Netdryrun, only if
# Batfish passed. Not run by this repository's CI.
name: network change gate

on:
  push:
  pull_request:

permissions:
  contents: read

jobs:
  batfish:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    services:
      batfish:
        image: batfish/batfish:2026.08.27.3685
        ports: ["9996:9996", "9997:9997"]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install pybatfish==2026.9.17.3748
      - name: Analyse the configs   # waits up to 60 s for the Batfish service to answer
        run: python examples/batfish-pipeline/batfish_check.py examples/batfish-pipeline/configs

  netdryrun:
    needs: batfish   # boot the lab only if Batfish passed
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: examples/batfish-pipeline
```

The workflow is an example to copy: this repository's CI does not run it, and it has not been timed on GitHub's runners. On top of the analysis, the Batfish job pays for pulling the `batfish/batfish` image (712 MB; `docker pull` took 15 s on the test machine), installing pybatfish (14 s there, the first command of the example's run steps) and starting the service. The measurements below come from the equivalent local script, `pipeline.sh`.

## Results

Measured on 2026-10-27 from a fresh clone of commit f368194 (later commits change only documentation), following the example's [README](https://github.com/netdryrun/netdryrun/tree/main/examples/batfish-pipeline#run-it) word for word, on WSL2 (20 cores, 16 GB) with images already pulled: `batfish/batfish:2026.08.27.3685`, pybatfish 2026.9.17.3748, Netdryrun 0.3.0 from PyPI, containerlab 0.81.1, FRR 10.4.1. The Batfish service was already running. The Batfish stage includes loading the snapshot; the lab stage includes deploying and destroying the lab. Each change below replaces r2's config; the last column is the command that reproduces the row.

| Change to r2 | Batfish | Netdryrun lab | Who caught it | Reproduce |
|---|---|---|---|---|
| None (baseline) | pass, 6 s | pass, 66 s | Both pass | `pipeline.sh` |
| Adds `default-originate` toward r1 | **fail**, 3 s | **fail**, 68 s (2 of 10) | Both; Batfish first | `BOTH=1 pipeline.sh default-leak` |
| Route-map name typo (`ALLOW-AL`) toward r1 | **fail**, 2 s | **fail**, 179 s (2 of 10) | Both; Batfish first, but its route model predicts the wrong outcome | `BOTH=1 pipeline.sh route-map-typo` |
| Switches to `frr defaults traditional` and drops the "allow all" route-maps | pass, 3 s | **fail**, 265 s (6 of 10) | **Only the lab** | `BOTH=1 pipeline.sh no-policy` |

### Caught by Batfish first: a leaked default route

r2 starts sending r1 a default route. In a 3-second run, Batfish reports that r1 learns `0.0.0.0/0` from r2 and passes it on to r3. The lab finds the same leak on r1 and r3 after about a minute. There FRR picks the route as its BGP best path and passes it on, but does not install it as the router's route to 0.0.0.0/0; Netdryrun reports it as "present via bgp (not selected)" and fails the check anyway. Stopping at the Batfish stage saves the lab run.

The route-map typo is also caught first: Batfish's `undefinedReferences` question names the missing `ALLOW-AL` and where it is used, `r2.conf line 20`. (`batfish_check.py` maps lines in the wrapped files it gives Batfish back to the original `frr.conf`.) Its routing model, though, still predicts that r1 uses the direct path to r2. FRR denies everything through a route-map that does not exist, so in the lab r1 receives nothing from r2 and reaches r2's LAN through r3. Ping still works; only the best-path check and the prefix count fail. The gate would fail in both stages, but only the lab shows what the network would really do.

### Seen only by the lab: an FRR default

According to the [FRR documentation](https://docs.frrouting.org/en/latest/bgp.html#clicmd-bgp-ebgp-requires-policy), `bgp ebgp-requires-policy` is on by default under the `traditional` profile and off under `datacenter`. An eBGP neighbor with no inbound and outbound policy then receives nothing and sends nothing, but the session still comes up. In the lab, r2 shows `(Policy) (Policy)` for both neighbors and 0 prefixes each way, and 6 of the 10 checks fail: r2's LAN is unreachable from r1, even after the link-failure scenario.

Batfish passed this change. It accepted `frr defaults traditional` without modelling what that profile implies, and predicted every route as before. When `bgp ebgp-requires-policy` is written out explicitly, Batfish reports it as an unrecognized line rather than applying it.

### Where they agreed

For the r1-r2 link failure, Batfish's forked snapshot predicted the same failover path (AS path `65003 65002` through r3) that the lab measured. In a topology this small, failover did not show any convergence behavior that the model missed.

## What Batfish does that this test does not show

This test uses a small part of Batfish. It also analyses ACLs and firewall rules, searches every packet that could match a rule rather than the few a ping sends, compares two snapshots to report exactly what a change does, scales to networks far larger than a lab can boot, and supports many vendors whose software cannot run in a container. None of that needs a lab, and Netdryrun does none of it.

## How well Batfish parses FRR

Batfish reads FRR configs as part of its Cumulus Linux and SONiC support. Its FRR support is partial, and the way you feed it configs matters:

- **A bare `frr.conf` is detected as Cisco IOS.** On these configs the status was `PARTIALLY_UNRECOGNIZED`: the `frr defaults` line was not recognized, and interfaces were renamed (`eth1` became `Ethernet1`). The BGP answers happened to be right, but FRR syntax was being read with IOS semantics.
- **Cumulus Linux layout.** Wrapped in the "Cumulus concatenated" layout (a hostname line, an interfaces section, a `ports.conf` marker, then `frr.conf`), the same three configs parse as `CUMULUS_CONCATENATED` with status `PASSED`, no warnings, and the lab's interface names. `batfish_check.py` does this wrapping.
- **SONiC layout.** Next to a `config_db.json` with the hostname and interface addresses, the unchanged `frr.conf` files also parse as `SONIC` with status `PASSED` and no warnings. Batfish predicted the same routes as through the Cumulus path, for the baseline and for the `traditional` change.
- **Not every FRR command or default is supported.** In this test, the defaults profile is accepted but not modelled, and `bgp ebgp-requires-policy` is not recognized at all. Make the gate fail on any file that does not parse cleanly or has a parse warning (`fileParseStatus`, `parseWarning`), as the example script does.

The commands that reproduce these findings, and the `(Policy)` output from FRR, are in the example's [README](https://github.com/netdryrun/netdryrun/tree/main/examples/batfish-pipeline#reproduce-the-findings).

These findings cover only BGP with route-maps on three FRR routers. Batfish's support for other vendors (Cisco, Juniper, Arista, Palo Alto and more) is much broader and is not tested here.

## Takeaways

- Put Batfish first. It needs no lab, it failed the two changes it caught in 2 to 3 seconds of analysis, and it pointed at the cause: the file and line of the route-map typo, the routers that learn the leaked default.
- Keep the lab stage. The change that passed Batfish broke every route through r2, because of a vendor default that the model does not know about.
- Watch for disagreements, not only for failures. On the route-map typo, both stages failed, but Batfish's prediction of the outcome was wrong.

See also [When to use what](when-to-use-what.md) for how Batfish, pyATS/Genie, containerlab and Netdryrun compare.


---
Source: https://netdryrun.com/ai-agents/

# AI agents (MCP server)

AI agents are starting to change networks. Netdryrun™ includes an [MCP](https://modelcontextprotocol.io) server that gives an agent a safety gate: it dry-runs the proposed change in a real lab and proceeds only if every check passes.

## Watch the demo

<figure class="ndr-video">
<video controls preload="none" playsinline width="1920" height="1080" poster="/assets/video/netdryrun-demo-poster.jpg" aria-label="Netdryrun demo video, about 90 seconds, captions burned in">
<source src="/assets/video/netdryrun-demo.mp4" type="video/mp4">
<track kind="captions" srclang="en" label="English (text)" src="/assets/video/netdryrun-demo.vtt">
<a href="/assets/video/netdryrun-demo.mp4">Download the video (MP4)</a>
</video>
<figcaption>About 90 seconds, captions on screen, no sound. A leaked default route that ping and session checks miss, an AI agent's tempting change rejected and the two-line fix passed (a scripted replay), a real agent run, and the verdict corpus with its losses. Every terminal line comes from a real run. <a href="/assets/video/netdryrun-demo.vtt">Captions as text</a>.</figcaption>
</figure>

## Set up the MCP server

```bash
pipx install netdryrun   # or uv tool install netdryrun
```

On Ubuntu 24.04 and Debian 12, install pipx with `sudo apt install pipx && pipx ensurepath` and open a new terminal; a plain `pip install` outside a virtualenv is refused there.

The MCP server is built in: `netdryrun mcp` starts it over stdio. The same requirements apply as for the CLI: Linux or WSL2, Docker, containerlab. The server runs labs on the machine where it runs.

### Claude Code

On Linux or inside WSL:

```bash
claude mcp add netdryrun -- netdryrun mcp
```

Add `-s project` to write the server into `.mcp.json` in the current folder, so everyone who works in that repository gets it.

On Windows, with Claude Code running on Windows and Netdryrun installed in WSL, start the server through `wsl.exe` and give the full path to `netdryrun` inside WSL:

```text
$ claude mcp add -s project netdryrun -- wsl.exe -d Ubuntu-22.04 -- /home/user/ndr-docs/bin/netdryrun mcp
Added stdio MCP server netdryrun with command: wsl.exe -d Ubuntu-22.04 -- /home/user/ndr-docs/bin/netdryrun mcp to project config
$ claude mcp get netdryrun
netdryrun:
  Scope: Project config (shared via .mcp.json)
  Status: ✓ Connected
  Type: stdio
  Command: wsl.exe
  Args: -d Ubuntu-22.04 -- /home/user/ndr-docs/bin/netdryrun mcp
```

(Claude Code 2.1.116. Use your own distribution name and path; `which netdryrun` inside WSL prints it.)

From Netdryrun 0.3.1, the tools accept the Windows path of a lab folder (`C:\labs\edge`) as well as the WSL one (`/mnt/c/labs/edge`); with 0.3.0, pass `/mnt/c/...`. That way the agent can pass the path its own file tools use. Before this, an agent on Windows had to translate paths itself, and in the [agent evaluation](#measured-ten-tickets-worked-unattended) a smaller model did not.

`dry_run` takes 30 seconds to several minutes. Start Claude Code with a longer tool timeout, in milliseconds, so it does not give up first:

```bash
MCP_TOOL_TIMEOUT=600000 claude
```

See [MCP tool calls time out](troubleshooting.md#mcp-tool-calls-time-out-in-the-client).

### Other MCP clients

Configure a stdio server with command `netdryrun` and argument `mcp`. Most clients take JSON like this (this is the `.mcp.json` Claude Code wrote above, with the Linux command):

```json
{
  "mcpServers": {
    "netdryrun": {
      "type": "stdio",
      "command": "netdryrun",
      "args": ["mcp"]
    }
  }
}
```

Without installing, use `"command": "uvx", "args": ["netdryrun", "mcp"]`. On Windows, use the `wsl.exe` command and arguments shown above. Set the client's tool-call timeout to at least 5 minutes.

## Workflow

1. The agent writes its proposed change into the lab's configs (in a lab folder with a containerlab topology and a `netdryrun.yml`).
2. It calls `dry_run` on that folder.
3. It applies the change elsewhere only if `status` is `passed`.

## Demo: a ticket, a tempting change, a verdict


[`examples/agent-demo`](https://github.com/netdryrun/netdryrun/tree/main/examples/agent-demo): the customer's new block must reach the upstream and the peer. The tempting change, removing the prefix-list filters, passes every ticket check, session check and ping, but leaks upstream routes and the upstream's default route to the peer, and accepts a prefix the customer doesn't own. The network team's leak guards fail, so the verdict is `DO NOT APPLY THIS CHANGE`. The proper fix, two prefix-list lines, passes the same checks. The checks never change; only the config does. Both attempts are a scripted replay (hand-written diffs, not output from a real agent); `demo.sh` runs them, and CI runs it on pushes to `main` and on pull requests. In a [real run](#a-real-agent-run), a fresh Claude Code agent with only the ticket, the lab and these MCP tools made the correct two-line change on the first try and proposed it with a `passed` verdict.

## Give the agent a ticket (the TICKET.md pattern)

An agent does better with a written task and explicit rules than with a chat message. Put a `TICKET.md` in the lab folder, next to `topology.clab.yml`, `configs/` and `netdryrun.yml`. [`examples/agent-demo/TICKET.md`](https://github.com/netdryrun/netdryrun/blob/main/examples/agent-demo/TICKET.md) is a complete example. A ticket says:

- **The goal, in network terms.** "The customer's new block 10.101.0.0/24 must reach the upstream and the peer." Name the routers, ASes and prefixes.
- **What the agent may change.** "Change only `configs/edge1.conf`." A small allowed surface makes the change easy to review.
- **What it must not change.** "Don't edit `netdryrun.yml`." The checks belong to the network team. An agent that may edit the checks can make any change pass.
- **The gate.** "Before proposing the change, run Netdryrun on this folder (`netdryrun run <folder>`, or the `dry_run` MCP tool) and include the verdict. Propose it only if the status is `passed`."

Then the prompt can stay short. The real run below used: "Work the ticket in TICKET.md in the current folder, following its rules", plus the path the MCP tools use for the folder and a request for the diff and the verdict at the end. Nothing about the solution.

More guidance for the prompt or the agent's instructions file:

- Ask for the verdict and the names of any failed checks in the final answer, so a human can review the evidence instead of the agent's reasoning.
- Tell it what to do on a failure: read `detail` for each failed check, fix the config, run again. Never weaken or delete a check; if it thinks a check is wrong, it should say so and stop.
- Don't show it the answer. In `examples/agent-demo`, the README, `changes/` and `demo.sh` contain the solution, so the real run could only see `TICKET.md`, `netdryrun.yml`, `topology.clab.yml` and `configs/`.
- A pass covers only the checks that exist. Give the agent the network team's standing guards (leak checks, `present: false` routes), not only the ticket's acceptance checks.

The repository's [`AGENTS.md`](https://github.com/netdryrun/netdryrun/blob/main/AGENTS.md) has the same rules written for agents.

## A real agent run

[`AGENT-RUN.md`](https://github.com/netdryrun/netdryrun/blob/main/examples/agent-demo/AGENT-RUN.md) records one real run on `examples/agent-demo`, not the scripted replay:

- **Agent:** Claude Code 2.1.116 in headless mode (`claude -p`). It could read and edit files and call the Netdryrun MCP tools. No shell, no web access, so its only way to test was Netdryrun.
- **What it did:** read the ticket, the router config and `netdryrun.yml`; added the new block to the two prefix lists in `configs/edge1.conf`; called `dry_run`; got `status: passed`, 14 of 14 checks, verdict `SAFE TO PROCEED`; proposed the two-line change with the verdict. 7 turns, 69 seconds.
- **Checked afterwards:** it changed only `configs/edge1.conf`, and a fresh `netdryrun run` on its folder gave `PASSED: 14 passed, 0 failed`.

The agent did not make the tempting leaky change, so this run did not show Netdryrun catching a mistake (`demo.sh` shows that). It shows the workflow end to end: the agent found the tool, ran the network team's checks through MCP, and its proposal came with a verdict from a real lab. It is one run of one model on one ticket.

## Measured: ten tickets worked unattended

One good run is an anecdote, so on 2026-10-27 we measured. [`examples/agent-eval`](https://github.com/netdryrun/netdryrun/tree/main/examples/agent-eval) has ten tickets on the two FRR example labs: changes to make, colleagues' changes to review (some fine, some leaking routes or setting the wrong attribute while sessions and pings stay up), a request that is itself a route leak, and one broken lab. Each has a hidden grader. The expected answers were [pre-registered](https://github.com/netdryrun/netdryrun/blob/main/examples/agent-eval/PREREGISTRATION.md) before anything ran. A fresh headless Claude Code agent worked each ticket alone, with only `AGENTS.md`, this page and the MCP tools: no shell, no project memory, no human.

| Agent (Claude Code 2.1.116) | Netdryrun | Solved | Misses |
|---|---|---|---|
| `claude-opus-4-7`, two runs | 0.3.0 | 10 / 10, 10 / 10 | none |
| `claude-haiku-4-5`, one run (not pre-registered: the prediction covered only the default model) | 0.3.0 | 3 / 10 | 5 ended on a Windows/WSL path mix-up (below); T09, T06 |
| `claude-haiku-4-5`, two runs (not pre-registered) | with the fixes below | 9 / 10 (8 counted strictly, see T07 in RESULTS.md), 8 / 10 | T09 both times; T10 once |

Solved means: finished unattended, the right verdict (safe, harmful or inconclusive), the right decision (apply, don't apply, rerun), no file changed that the ticket forbids, and, for a change it wrote, an independent rerun with extra hidden checks passes.

What failed, and what changed because of it:

- **Paths on Windows.** Claude Code on Windows with the server in WSL is the setup this page documents. The smaller model passed the WSL path (`/mnt/c/...`) to its Windows file tools and was refused, and Netdryrun 0.3.0 refused the Windows path. From 0.3.1 the tools accept both.
- **A pass that covers too little (T09).** A "pure refactor" to `redistribute connected` also announces r1's link subnets. The given checks don't look at that, so Netdryrun says `passed`. The smaller model trusted the pass every time. The larger one caught it by reading the diff, not with Netdryrun. `record_baseline` would have shown it, and no agent used it. `AGENTS.md` now says a "no behavior change" ticket needs a baseline.
- **A broken lab that says `failed` (T10).** With `bgpd` off on every router, the result is `failed`, not `inconclusive`: the inconclusive rule is conservative. From 0.3.1, failed checks that never got usable state carry `"unready": true`. Once, the smaller model turned `bgpd` back on in a file the ticket forbade and said apply.
- **No fix-and-rerun loop.** No agent made a wrong change and then fixed it to a pass: the larger model got every change right first time. So this doesn't measure that loop.
- **A non-deterministic lab.** One wrong-looking change (a bare `network 192.168.0.0/16`) passed 5 of 8 runs. A single `passed` can be luck when the lab itself varies.

The harness set `NETDRYRUN_MCP_ROOT` to the ticket folder, but 0.3.0 ignores that variable, so in the 0.3.0 runs the server was not confined to the folder; the agents had no shell.

Ten small tickets written by the tool's author, two models, at most two runs each: evidence about the docs and the tool surface, not a rate. Full results, transcripts and every miss: [RESULTS.md](https://github.com/netdryrun/netdryrun/blob/main/examples/agent-eval/RESULTS.md).

## Gate agent-made pull requests in CI

An agent's own `dry_run` is a claim. Run the same checks again in CI, where the agent cannot change the result:

```yaml title=".github/workflows/network-dryrun.yml"
name: Network dry run
on:
  pull_request:
    paths:
      - "network/**"
permissions:
  contents: read
  pull-requests: write
jobs:
  dryrun:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: netdryrun/netdryrun@v0.3.1
        with:
          path: network/
          pr-comment: true
```

Then, in the repository settings:

- **Make the job a required status check** on the default branch, so a failed verdict blocks the merge.
- **Protect the checks.** Add a `CODEOWNERS` line such as `network/netdryrun.yml @your-org/network-team` and require code-owner review. A PR that edits the checks then needs a human from the network team, while config-only PRs need only the green check and a normal review.
- **Keep agent PRs away from secrets.** The lab runs as root on the runner. Follow the [Action security notes](github-action.md#security-notes): no secrets in the job, no `pull_request_target`.

The PR comment lists failures first with their evidence, so the reviewer sees what the lab saw. See [GitHub Action](github-action.md) for every input.

## Tools

The server has these tools: `dry_run`, `run_checks`, `record_baseline`, `validate` and `check_types`.


| Tool | Arguments | What it does |
|---|---|---|
| `dry_run` | `path`, `keep_lab` (default `false`) | Deploy the lab, run every check, destroy the lab, return the verdict. Takes 30 seconds to several minutes. |
| `run_checks` | `path` | Run the checks against a lab that is already running (no deploy or destroy) |
| `record_baseline` | `topology`, `deploy` (default `true`), `wait_seconds` (default `45`) | Deploy the lab, snapshot its BGP sessions, prefix counts and routes as `netdryrun.yml` text, destroy the lab. Returns the YAML; nothing is written to disk. Like [`netdryrun record`](reference/cli.md#record) |
| `validate` | `path` | Validate `netdryrun.yml` and its topology without starting a lab: node names, drivers and supported keys, as `dry_run` checks them before deploying (0.3.1 and later) |
| `check_types` | | List supported check types and their keys, to help write `netdryrun.yml` |

The server also exposes the last full JSON report as a resource, `netdryrun://report/{path}`.

## Result and verdict

`dry_run` and `run_checks` return JSON like this:

```json
{
  "status": "failed",
  "passed": 5,
  "failed": 1,
  "error": null,
  "inconclusive_reason": null,
  "lab": "ndr-frr-broken",
  "checks": [
    {"name": "r1: route 0.0.0.0/0 via bgp is absent", "passed": false,
     "detail": "unexpectedly present via bgp (not selected)"}
  ],
  "evidence_file": "/path/to/lab/netdryrun-report.json",
  "verdict": "DO NOT APPLY THIS CHANGE"
}
```

(`checks` is shortened here; the real result lists every check.)

From 0.3.1, a failed check also has `"unready": true` when every sample of it failed for lack of state: the command failed on the device, its output could not be read, or BGP had no neighbors at all. That points at the lab as much as at the change. The [inconclusive rule](reference/cli.md#when-a-run-is-inconclusive) is conservative, so a lab where a daemon never started can still come back `failed` when other nodes' route and ping checks read cleanly. If the `unready` failures and details such as `bgpd is not running` sit on nodes the change doesn't explain, report the lab problem; don't rewrite the change, and don't apply it.

`verdict` is a separate field with one of three values:

- `SAFE TO PROCEED` when `status` is `passed`. It means every check in the file passed in the lab, and nothing more: a change that breaks something no check looks at gets it too (ticket T09 above). For a change that must not change behavior, record a baseline first
- `DO NOT APPLY THIS CHANGE` for `failed` or `error`, including config errors
- `INCONCLUSIVE: the lab did not reach a testable state; this says nothing about your change. Do not apply it until a run passes.` when `status` is `inconclusive`: the lab never came up far enough for the checks to mean anything ([rules](reference/cli.md#when-a-run-is-inconclusive)). `inconclusive_reason` says what was seen. Rerun it, perhaps with a longer `timeout`; don't rewrite the change because of it.

Tell the agent what to do with each verdict: propose the change only on `SAFE TO PROCEED`; on `DO NOT APPLY THIS CHANGE`, read the failed checks, fix the config and run again; on `INCONCLUSIVE`, rerun, and if it stays inconclusive, report that the lab does not come up instead of changing the config. [Troubleshooting](troubleshooting.md#inconclusive-the-lab-never-came-up) shows a real inconclusive run.

The full evidence is written to `netdryrun-report.json` next to `netdryrun.yml`. Its format, `netdryrun.report/v1`, is defined by a JSON Schema: [`report-v1.json`](https://netdryrun.com/schemas/report-v1.json). The test suite validates reports from real lab runs against it.

## Safety model

- **It never touches production.** The server has no tool that pushes config anywhere. It only builds and tests labs.
- **No raw device output in tool results.** Tool results contain normalized check results (name, pass/fail, a short detail), not raw command output; that goes to the JSON report file. A detail or an error can still quote a fragment of lab text, such as a BGP state name or the last line of a failed command, so from 0.3.1 each is flattened to one line and capped at 300 characters (1,000 for errors). The `status` and `verdict` are computed from pass/fail only, never from that text: an agent should act on them and treat `detail` and `error` as data.
- **Labs are code.** containerlab runs privileged containers. Only point the server at topologies you trust, on a machine you would let run Docker. The tools take any path the agent passes, and a `netdryrun.yml` can point at a topology in another folder. To keep an agent to one folder (Netdryrun 0.3.1 and later; 0.3.0 ignores the variable without a warning), set `NETDRYRUN_MCP_ROOT` in the server's environment (several folders separated by `:`, or `;` on Windows): every `netdryrun.yml`, the lab it points to and every topology must then resolve inside it, or the tool refuses. This stops an agent from being steered to a lab elsewhere; it does not make an untrusted lab inside the folder safe, since a topology can still mount host paths.

A pass is evidence from a lab, not a guarantee about production. See [what a lab cannot prove](trust.md#what-a-lab-cannot-prove).


---
Source: https://netdryrun.com/troubleshooting/

# Troubleshooting

Each error below was reproduced on purpose on WSL2 (Ubuntu 22.04) with containerlab 0.81.1, using Netdryrun™ 0.2.0, and 0.3.0 for the inconclusive case. The error messages are copied from those runs; the surrounding lines (the version, the deploy progress line, and no `Destroying lab...` when nothing was deployed) are shown as 0.3.1 prints them. The entries for errors new in 0.3.1 quote the message as the 0.3.1 code writes it.

Exit code `2` means the run has no verdict (a config error, a lab error, a fault that did not take effect, or an internal error; `--debug` shows the traceback of an internal error). Exit code `1` means a check failed. See [exit codes](reference/cli.md#exit-codes).

## Unknown key ... did you mean

```text
$ netdryrun validate my-lab
config error: checks[2]: unknown keys ['presnt'] for type route; did you mean 'present'?; allowed: active, hold, name, node, prefix, present, protocol, timeout, type, vrf
```

Exit code `2`. From 0.3.1, a key Netdryrun doesn't know is an error at every level of the file (top level, `nodes`, checks, scenarios and their faults), not only inside checks. Before 0.3.1, a misspelled key at the top level, under `nodes` or inside a fault was ignored: a whole block of checks under `chekcs:` never ran, and nothing said so. Fix the spelling the message suggests; `allowed:` lists every key that fits there. The same goes for values from a fixed list (`afi`, `protocol`, `state`, `expect`, `driver`), and a key written twice in the same mapping is an error too (`duplicate key 'present' (first defined on line 12)`). Run `netdryrun validate` after upgrading: a file that 0.3.0 accepted can fail here, and every such failure was a check that didn't test what it said.

## containerlab is not installed

```text
$ netdryrun run my-lab
Netdryrun 0.3.1: 14 checks from my-lab/netdryrun.yml
ERROR: 'containerlab' not found on PATH
```

Exit code `2`. Netdryrun drives the `containerlab` CLI and needs it on `PATH`. Install it ([containerlab.dev/install](https://containerlab.dev/install/)) and check with `containerlab version`. The same error names `docker` if Docker is missing. Nothing was deployed, so nothing is destroyed.

## Docker or containerlab permission denied

As a user who is not in the `docker` and `clab_admins` groups:

```text
$ netdryrun run my-lab
Netdryrun 0.3.1: 14 checks from my-lab/netdryrun.yml
Deploying lab my-lab (3 nodes); this usually takes 30-90 s, longer the first time images are pulled...
Destroying lab...
warning: lab cleanup failed: ROR
...
ERROR: containerlab deploy failed:

   ERROR

  User 'ndrtest' is not part of containerlab admin group 'clab_admins', which is required to execute this command.
  To add yourself to this group, run the following command:
      $ sudo usermod -aG clab_admins ndrtest.
```

```text
$ docker ps
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock
```

Fix: add your user to both groups, then start a new login session so the groups apply.

```bash
sudo usermod -aG docker,clab_admins "$USER"
```

On WSL, close the terminal and run `wsl --shutdown` from Windows, then open it again. Check with `id`: both groups must be listed.

```text
$ id
uid=1001(ndrtest) gid=1001(ndrtest) groups=1001(ndrtest),998(clab_admins),999(docker)
```

After this, the same user deployed and ran the lab. Running Netdryrun with `sudo` also works, but then the reports are owned by root.

## A check names a node that is not in the topology

A typo (`r9` instead of `r1`) is caught before anything is deployed:

```text
$ netdryrun run unk
Netdryrun 0.3.1: 14 checks from unk/netdryrun.yml
ERROR: unknown node(s) r9; the topology has r1, r2, r3
```

From 0.3.1, `netdryrun validate` reads the topology too and catches it without starting anything (`lab error: unknown node(s) r9; ...`). Before 0.3.1, `validate` checked only the file itself and printed `OK` for this typo.

Exit code `2`, and nothing is deployed or destroyed: from 0.3.1, a lab you kept running with `--keep` survives a typo like this (0.3.0 and earlier destroyed it). Use the node names from the topology's `nodes:` section (`r1`), not the container names (`clab-my-lab-r1`).

## The lab never converges (timeout)

A positive check waits up to `timeout` seconds (default 120) for the network to converge, then fails. Here r1 has the wrong `remote-as` for r2 and `timeout` is 30:

```text
$ netdryrun run slow
Netdryrun 0.3.1: 14 checks from slow/netdryrun.yml
Deploying lab ndrdocs-slow (3 nodes); this usually takes 30-90 s, longer the first time images are pulled...
  [PASS] r1: BGP session to 10.0.13.2 is established -- state is established (13.8s)
  ...
  [FAIL] r1: BGP session to 10.0.12.2 is established -- state is idle (30.1s)
  [FAIL] r2: BGP session to 10.0.12.1 is established -- state is idle (30.1s)
  [FAIL] r1: route 192.168.33.0/24 via bgp is present -- not active via bgp; seen: nothing (30.1s)
Convergence checks done; settling 10s before post-convergence checks...
  ...
  [FAIL] r1: prefixes from 10.0.12.2 >= 2 and <= 10 -- not evaluated: BGP session(s) on r1 not established: 10.0.12.2 (idle) after waiting 30s. A post-convergence check only means something once every BGP session on its node is up (a leak can arrive over any of them). If a session is down on purpose, add a bgp_session check with state: down for it (30.0s)
Destroying lab...
FAILED: 10 passed, 4 failed (14 checks)
```

A check that fails at exactly its timeout (`30.1s` here) never reached the expected state. Two causes:

- **The change really breaks something.** The `detail` says what the router reported (`state is idle`). This is the test working.
- **The lab is slow to boot.** SR Linux, SONiC and cEOS take longer than FRR. Raise `timeout` at the top of `netdryrun.yml`, or on one check. `examples/srl-frr` uses 120.

To see why, keep the lab and look inside:

```text
$ netdryrun run slow --keep-on-failure
...
Lab ndrdocs-slow left running for debugging; destroy with: containerlab destroy -t /home/user/ndr-docs/slow/topology.clab.yml --cleanup
FAILED: 10 passed, 4 failed (14 checks)
$ docker exec clab-ndrdocs-slow-r1 vtysh -c "show bgp summary"
...
Neighbor        V         AS   MsgRcvd   MsgSent   TblVer  InQ OutQ  Up/Down State/PfxRcd   PfxSnt Desc
10.0.12.2       4      65099         6        12        0    0    0    never         Idle        0 N/A
r3(10.0.13.2)   4      65003        38        40        3    0    0 00:01:17            2        3 FRRouting/10.4.1_git
```

r1 expects AS 65099 at 10.0.12.2, but r2 is AS 65002. Destroy the lab with the command Netdryrun printed.

The prefix check is a post-convergence check (it has `max`), so it reports `not evaluated`; see the next entry.

## Not evaluated (a session on the node never came up)

```text
  [FAIL] r1: prefixes from 10.0.12.2 >= 2 and <= 10 -- not evaluated: BGP session(s) on r1 not established: 10.0.12.2 (idle) after waiting 30s. A post-convergence check only means something once every BGP session on its node is up (a leak can arrive over any of them). If a session is down on purpose, add a bgp_session check with state: down for it
```

Exit code `1`. From 0.3.1, a post-convergence check (a route that must be absent, a ping that must fail, a prefix count with `max` or `exact`, a `bgp_route` attribute) starts only once every configured BGP neighbor on its node is up with stable prefix counts. A leak can arrive over any session, so a check that passed while one was still down would prove nothing. Netdryrun waits up to the largest `timeout` of the node's post-convergence checks; if a session is still down then, those checks fail as `not evaluated` and name the session.

Fix: if the session should be up, it's a finding: look at it as in [the lab never converges](#the-lab-never-converges-timeout), or raise `timeout` for a slow NOS. If it is down on purpose (a shut neighbor, a peer that isn't in the lab), add a check that says so, and the wait leaves it out:

```yaml
- type: bgp_session
  node: r1
  neighbor: 10.0.12.2
  state: down
```

## A node without BGP waits a whole timeout

```text
warning: h1 reported no BGP neighbors for 30s; the check was evaluated without BGP convergence
```

From 0.3.1, a node that answers with no BGP neighbors at all is treated as not converged yet, because that is also what a router answers before its BGP config is applied. Its post-convergence checks (a ping that must fail, for example) wait up to their `timeout`, then run with this warning in their result; the verdict is unchanged. On a node that really doesn't run BGP, lower the `timeout` of those checks to shorten the wait. If the node should have BGP neighbors, its BGP config was never applied: check its startup config or `setup` commands.

## The fault did not take effect

```text
ERROR: scenario 'r1-r2 link fails': the fault did not take effect within 30s: BGP session(s) over the downed links still established (r2 -> 10.0.12.1). Netdryrun won't judge the scenario's checks on the state from before the fault. Without BFD, BGP can take its hold time (up to 180 s) to notice a failure: raise the checks' timeout, or lower the hold timers in the lab
```

Exit code `2`. From 0.3.1, after taking links down a scenario waits until every BGP session that ran over them is down on both ends, so its checks are never judged on the state from before the failure. The wait is capped at the largest `timeout` of the scenario's checks. Here the far end, r2, still had the session up when the time ran out: without BFD, a router notices a dead link only when its BGP hold timer expires (180 s on FRR by default).

Fix: give the scenario's checks a `timeout` above the hold time (for example `timeout: 200` on them, or at the top of the file), lower the hold timers in the lab configs (`timers bgp 3 9` on FRR), or enable BFD. The links are restored and the lab destroyed as usual. See [scenario timing](reference/config.md#scenario-timing).

## Could not read BGP state to find the sessions over the links

```text
ERROR: could not read BGP state on r2 to find the BGP sessions over the links the scenario takes down: unexpected output from `show bgp neighbors json`: no output. Netdryrun won't judge the scenario without knowing when the fault took effect
```

Exit code `2`. From 0.3.1, before a scenario takes links down, Netdryrun reads the BGP state of the nodes on both ends of each link (and the addresses of the downed interfaces) to know which sessions the fault must bring down. If that state can't be read, it can't tell when the fault took effect, so it stops before changing anything instead of judging the scenario on the settle delay alone (0.3.0 read it as "no sessions"). Usually the node's routing daemon is still starting or has crashed: check the node (`docker exec <container> vtysh -c "show bgp summary"`), raise the main checks' `timeout` so the lab is fully up before the scenarios start, and rerun. A node no driver can read (a Linux host) and a VRF the node doesn't have count as "no sessions", as before.

## SR Linux fails on a Windows drive (/mnt/c)

On WSL, files under `/mnt/c` are on the Windows filesystem, which has no Linux permissions. If containerlab's lab directory is there, SR Linux cannot save its config. Running containerlab directly in such a folder:

```text
$ containerlab deploy -t topology.clab.yml
11:07:03 INFO Creating lab directory path=/mnt/c/Users/.../srlmnt/clab-ndrdocs-srlmnt
11:07:03 INFO unable to adjust Labdir file ACLs: operation not supported
...
11:07:32 ERRO node "srl1" post-deploy: command execution error:Error in /system:
    Setting permissions for file '/etc/opt/srlinux/config.tmp' failed with error_code = 1 [Operation not permitted]
Error: Commit failed
```

The SR Linux container keeps running, but without its startup config, so every check fails:

```text
  [FAIL] srl1: BGP session to 10.0.100.2 is established -- neighbor 10.0.100.2 not configured (seen: none) (122.6s)
```

Netdryrun avoids this. When the topology is under `/mnt/`, it puts containerlab's lab directory in `~/.cache/netdryrun/labs` (unless you set `CLAB_LABDIR_BASE` yourself). The same folder with `netdryrun run .`:

```text
$ netdryrun run .
Netdryrun 0.3.1: 6 checks from netdryrun.yml
Deploying lab ndrdocs-srlmnt (2 nodes); this usually takes 30-90 s, longer the first time images are pulled...
  [PASS] srl1: BGP session to 10.0.100.2 is established -- state is established (31.2s)
  ...
PASSED: 6 passed, 0 failed (6 checks)
```

If you deploy with containerlab yourself (for example for `netdryrun check`), either keep the lab on the Linux filesystem (`~/...`) or set `CLAB_LABDIR_BASE` to a Linux path. Keeping labs on the Linux filesystem is also faster.

## The cEOS image is missing

Arista does not allow cEOS to be redistributed, so you import it yourself. If the image named in the topology is not in Docker, Docker tries to pull it from Docker Hub and fails:

```text
$ netdryrun run ceos
Netdryrun 0.3.1: 7 checks from ceos/netdryrun.yml
Deploying lab ndrdocs-ceos (2 nodes); this usually takes 30-90 s, longer the first time images are pulled...
Destroying lab...
ERROR: containerlab deploy failed:
10:57:23 INFO Containerlab started version=0.81.1
10:57:23 INFO Parsing & checking topology file=topology.clab.yml
10:57:23 INFO Removing directory path=/home/user/ndr-docs/ceos/clab-ndrdocs-ceos
10:57:23 INFO Pulling image image=docker.io/library/ceos:4.34.1F
10:57:25 ERRO Failed to pull image image=docker.io/library/ceos:4.34.1F err="Error response from daemon: pull access denied for ceos, repository does not exist or may require 'docker login'"
```

Fix: download cEOS-lab from arista.com (free account) and import it with the exact name and tag the topology uses: `docker import cEOS-lab-<version>.tar ceos:<version>`, as the comment in `examples/arista-frr/topology.clab.yml` says. Then check that Docker has it:

```text
$ docker images ceos
IMAGE          ID             DISK USAGE   CONTENT SIZE   EXTRA
ceos:4.36.3M   94cc1e5462fe       3.55GB          976MB   U
```

`examples/arista-frr` expects `ceos:4.36.3M`. Either import with that tag or change `image:` in the topology to match yours.

## A lab named X is already running

```text
ERROR: a lab named 'my-lab' is already running (3 container(s), e.g. clab-my-lab-r1): another Netdryrun run, or a lab deployed by hand or kept with --keep. Netdryrun won't redeploy or destroy it. Wait for the other run to finish, or remove the lab with: containerlab destroy -t /home/user/my-lab/topology.clab.yml --cleanup
```

Exit code `2`, before anything is deployed. containerlab lab names are global on a machine: containers are named `clab-<lab>-<node>`. From 0.3.1, `netdryrun run` refuses to deploy a lab whose name is already in use, because redeploying would reconfigure the other lab's containers, and destroying it afterwards would remove them from under whoever is using it. Two runs of the same lab started at the same moment on one host get `another Netdryrun run is already using lab 'my-lab' on this host` instead.

Fix: wait for the other run, destroy the old lab with the command in the message (for a lab you kept with `--keep` or `--keep-on-failure`), or give every lab a unique `name:`. On a shared CI runner or machine, put something unique in the name (for example the branch). `netdryrun check` doesn't deploy, so it still runs against the running lab.

Before 0.3.1, Netdryrun deployed with `containerlab deploy --reconfigure` regardless, so a second lab with the same `name:` **replaced** the first one, even from a different folder. Here, on 0.2.0, `my-lab` was left running with `--keep`, then a copy of it in `other-lab` (same `name: my-lab`) was run:

```text
$ netdryrun run other-lab
Netdryrun 0.2.0: 14 checks from other-lab/netdryrun.yml
Deploying lab my-lab (3 nodes)...
...
Destroying lab...
```

The first lab is gone:

```text
$ netdryrun check my-lab
Netdryrun 0.2.0: 14 checks from my-lab/netdryrun.yml
ERROR: lab containers not running: clab-my-lab-r1, clab-my-lab-r2, clab-my-lab-r3
```

Before you run, check what is up with `docker ps` or `containerlab inspect --all`.

## A host port is already in use

If a topology publishes ports on the host (`ports:` on a node), two labs cannot use the same host port:

```text
$ netdryrun run p2
Netdryrun 0.3.1: 14 checks from p2/netdryrun.yml
Deploying lab ndrdocs-p2 (3 nodes); this usually takes 30-90 s, longer the first time images are pulled...
Destroying lab...
ERROR: containerlab deploy failed:
...
11:05:40 ERRO node "r1" deploy: Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint clab-ndrdocs-p2-r1 (40a6a46a...): Bind for 0.0.0.0:18179 failed: port is already allocated
```

Fix: Netdryrun does not need published ports; it runs every command with `docker exec`. Remove `ports:` from the topology, or use different host ports per lab. `docker ps` shows which container holds the port.

## link_down on an SR Linux node

Failure scenarios take links down with `ip link` inside the node, which works on FRR, SONiC and cEOS but not yet on SR Linux. From 0.3.1, `netdryrun validate` refuses the file (exit code `2`). `run` finds out only when the scenario starts, after the main checks:

```text
$ netdryrun run srl-ld
Netdryrun 0.3.1: 6 checks from srl-ld/netdryrun.yml
Deploying lab ndrdocs-srlld (2 nodes); this usually takes 30-90 s, longer the first time images are pulled...
  [PASS] srl1: BGP session to 10.0.100.2 is established -- state is established (16.1s)
  ...
  [PASS] frr1: ping 192.168.10.1 from 192.168.20.1 expects success -- 3/3 replies (need 2) (21.5s)
Scenario: srl1-frr1 link fails
Destroying lab...
ERROR: failure scenarios on SR Linux nodes (srl1) are not supported yet; take the link down on the FRR/Linux side of the link instead
```

Fix: take down the other end of the same link. For `examples/srl-frr`, the link is `srl1:e1-1` to `frr1:eth1`:

```yaml
scenarios:
  - name: srl1-frr1 link fails
    link_down: {node: frr1, interface: eth1}
```

The effect on the network is the same: the link is down for both sides. `node_isolated` on an SR Linux node fails the same way; isolate its neighbors' links instead.

## MCP tool calls time out in the client

`dry_run` deploys a lab, so it takes 30 seconds to several minutes. Many MCP clients give up on a tool call sooner. Reproduced with the Python MCP SDK (mcp 2.3.0) and a 20-second client timeout:

```text
MCPError: Request 'tools/call' timed out
after 20.0s
```

With a 300-second timeout, the same call returned the full result after 143 seconds.

When the client gives up, it usually stops the server, and **the lab is left running**. Right after the timeout above:

```text
$ docker ps --format '{{.Names}} {{.Status}}'
clab-my-lab-r1 Up 27 seconds
clab-my-lab-r2 Up 27 seconds
clab-my-lab-r3 Up 27 seconds
```

The next `dry_run` on the same folder redeploys over it and cleans up, or destroy it yourself with `containerlab destroy -t my-lab/topology.clab.yml --cleanup`.

Fixes:

- **Raise the client's tool timeout** to at least 5 minutes. In Claude Code, set `MCP_TOOL_TIMEOUT` (milliseconds) before starting it, for example `MCP_TOOL_TIMEOUT=600000 claude`. For other clients, look for a tool-call or request timeout setting.
- **Make the lab faster.** Lower `timeout` in `netdryrun.yml` so a broken change fails sooner, and pull images in advance so the first call does not wait on a download.
- **If the client cannot wait that long**, let the agent run `netdryrun run <folder>` in a shell and read `netdryrun-report.json`.

## No PR comment on a big lab

With `pr-comment: true`, the job log says `could not comment on the PR (needs permissions pull-requests: write ...)` even though the permission is set, and the lab has several hundred checks, for example a file `netdryrun record` wrote for a 20-node lab.

GitHub rejects a comment longer than 65,536 characters. Netdryrun 0.3.0 lists every check in the comment, about 90 characters each, so above roughly 700 checks the comment is too long. The verdict, the job status and the reports are not affected. Fixed in 0.3.1: the table stops before the limit, failures first, and says how many checks it left out. On 0.3.0, trim the recorded file to the checks that matter, or split it into several `netdryrun.yml` files run as a [matrix](github-action.md#several-labs).

## Inconclusive: the lab never came up

Exit code `3` means checks failed, but the lab never reached a testable state, so the result says nothing about your change. Reproduced with Netdryrun 0.3.0 by turning off `bgpd` in the FRR `daemons` file of a copy of `examples/frr-bgp` (and `timeout: 30`):

```text
$ netdryrun run . --json report.json
Netdryrun 0.3.1: 7 checks from netdryrun.yml
Deploying lab ndrdocs-nobgp (3 nodes); this usually takes 30-90 s, longer the first time images are pulled...
  [FAIL] r1: BGP session to 10.0.12.2 is established -- error: `vtysh -c show bgp neighbors json` failed on r1 (rc=1): bgpd is not running (33.1s)
  [FAIL] r1: BGP session to 10.0.13.2 is established -- error: `vtysh -c show bgp neighbors json` failed on r1 (rc=1): bgpd is not running (33.1s)
  [FAIL] r1: route 192.168.3.0/24 via bgp is present -- not active via bgp; seen: nothing (33.1s)
  [FAIL] r1: ping 192.168.3.1 from 192.168.1.1 expects success -- 0/3 replies (need 2) (33.1s)
  [FAIL] r1: BGP best path for 192.168.2.0/24 has as-path '65002', next hop 10.0.12.2 -- error: `vtysh -c show bgp ipv4 unicast 192.168.2.0/24 json` failed on r1 (rc=1): bgpd is not running (33.1s)
Convergence checks done; settling 10s before post-convergence checks...
  [FAIL] r1: prefixes from 10.0.12.2 >= 1 and <= 10 -- error: `vtysh -c show bgp neighbors json` failed on r1 (rc=1): bgpd is not running (30.1s)
  [PASS] r1: route 0.0.0.0/0 via bgp is absent -- absent (held 10s, 5 samples) (10.1s)
Destroying lab...
INCONCLUSIVE: the lab did not reach a testable state: r1 never returned usable BGP state (r1: error: `vtysh -c show bgp neighbors json` failed on r1 (rc=1): bgpd is not running), and no check passed on any sample. Rerun with a longer timeout, or check that the lab boots (6 of 7 checks failed; this says nothing about the change)
  wrote json report: report.json
```

The JSON report has the same text in `inconclusive_reason`, and every unready sample in `history` is marked:

```json
{"t": 33.1, "passed": false, "detail": "error: `vtysh -c show bgp neighbors json` failed on r1 (rc=1): bgpd is not running", "unready": true}
```

How it differs from the other results:

- **`error` (exit `2`):** the run could not start or finish: a config error, a missing tool, a failed deploy, a fault that did not take effect.
- **`failed` (exit `1`):** the lab was up and something is wrong. A configured BGP session that is down (an ASN typo, as in [the lab never converges](#the-lab-never-converges-timeout)) is `failed`, not `inconclusive`.
- **`inconclusive` (exit `3`):** no positive check passed on any sample, and every failed check is on a node whose CLI or BGP never answered.

Fix: check that the lab boots (`containerlab inspect`, `docker logs <container>`), that the routing daemon is enabled, and that `timeout` is long enough for slow NOSes, then rerun. One known limit: a change that deletes a node's whole BGP config looks the same and is reported `inconclusive`. It is still never `passed`. See the [full rules](reference/cli.md#when-a-run-is-inconclusive).

## Still stuck

Run with `--keep-on-failure`, look inside the nodes with `docker exec`, and read the JSON report (`--json report.json`): every check keeps the raw commands and output. If it looks like a bug, [open an issue](https://github.com/netdryrun/netdryrun/issues) with the report attached. See [Support](support.md).


---
Source: https://netdryrun.com/faq/

# FAQ

## Does Netdryrun touch my production network?

No. Netdryrun™ only builds labs with containerlab on the machine where it runs, runs commands only inside the lab containers (with `docker exec`), and destroys the lab. Most are read-only show commands; the others take links down and up for failure scenarios, add and remove routes for `inject_routes` scenarios, and run any `setup` commands you write. It has no command, option or MCP tool that connects to a real device or pushes config anywhere. You apply the change to production yourself, with your normal process, after the test passes.

## What does a pass prove?

A pass means every check in your `netdryrun.yml` held in a lab running real routing software: positive checks reached the expected state within the timeout, and negative checks held for the hold time after convergence. It is strong evidence that the change does what you intended at the protocol and policy level.

It does not prove:

- **anything you did not check.** A pass covers the checks that exist. A leak with no negative check for it passes.
- **vendor or version behavior.** FRR, SR Linux, SONiC VS and cEOS are not your production routers or images.
- **scale, hardware or timing.** A lab has a few nodes and small tables, no ASICs, and different convergence times.

See [what a lab cannot prove](trust.md#what-a-lab-cannot-prove). The [verdict corpus](corpus.md) shows where Netdryrun was right and wrong on 30 realistic changes.

## What does "inconclusive" mean?

A run is `inconclusive` (exit code `3`) when checks failed but the lab never reached a state where they mean anything, for example a node whose BGP daemon never started. It says nothing about the change, good or bad: rerun, raise `timeout`, or check that the lab boots. Don't change the network change because of it, and don't apply it either: only `passed` means go.

The rules are conservative. A configured session that is down, a missing route or a failed ping is always `failed`, because an ASN typo looks exactly like a slow lab from the outside. See [when a run is inconclusive](reference/cli.md#when-a-run-is-inconclusive) and [troubleshooting](troubleshooting.md#inconclusive-the-lab-never-came-up).

## How is it different from Batfish or pyATS?

- **Batfish** models configs without booting anything. It is fast, covers many vendors and large networks, and answers broad questions. Netdryrun runs the real routing software, so it sees what the implementation actually does, on fewer nodes.
- **pyATS / Genie** is a full Python test framework with many parsers, for labs and production devices. Netdryrun is a YAML file of checks and a CLI, aimed at one job: a pass/fail gate in CI.

They work together. See [When to use what](when-to-use-what.md) for a longer, neutral comparison.

## Which network operating systems are supported?

FRR, Nokia SR Linux, SONiC (docker-sonic-vs) and Arista EOS (cEOS, bring your own image). Labs can mix them: the examples pair each one with FRR. See [drivers](reference/config.md#drivers) for what each driver supports.

## Why not Cisco or Juniper?

Their lab images are licensed. Netdryrun's CI and examples must run for anyone, so every image they use has to be free to pull: FRR, SR Linux and SONiC VS are. Arista cEOS is free to download with an account but can't be redistributed, so its example needs you to import your own image.

Cisco and Juniper images (for example IOS XRd, Cisco 8000 emulator, cRPD, vJunos) need an account, a license or both, and several are virtual machines that containerlab runs through vrnetlab. Drivers for them are on the roadmap, following the same bring-your-own-image model as cEOS. If you need one, say so in an [issue](https://github.com/netdryrun/netdryrun/issues).

## Does it work on Windows?

Yes, through WSL2. containerlab needs Linux, so install Docker and containerlab inside a WSL2 distribution (Ubuntu 22.04 is what we test on) and run Netdryrun there. Keep labs on the Linux filesystem (`~/...`) rather than under `/mnt/c`: it is faster, and SR Linux cannot save its config on a Windows drive. Netdryrun works around the second problem; see [troubleshooting](troubleshooting.md#sr-linux-fails-on-a-windows-drive-mntc). All the outputs in this documentation were produced on WSL2.

## How much memory and CPU does it need?

Memory used per node once the lab is up, measured with `docker stats` on WSL2 (20 cores, 16 GB):

| Node | Image | Memory |
|---|---|---|
| FRR | `quay.io/frrouting/frr:10.4.1` | 23 to 25 MiB |
| SONiC VS | `docker-sonic-vs:latest` | 302 MiB |
| Arista cEOS | `ceos:4.36.3M` | 903 MiB |
| Nokia SR Linux | `ghcr.io/nokia/srlinux:26.7.2` | 1.9 GB (1,947,377,664 bytes, read from the container's cgroup `memory.current`, because `docker stats` shows 0 for SR Linux) |

CPU is busy only while nodes boot. Once up, FRR and SONiC used about 1% of one core or less; cEOS was using about one full core when measured, shortly after boot.

Plan for the sum of your nodes plus a few hundred MB for Docker and containerlab. A small FRR lab runs on any laptop. A lab with several SR Linux or cEOS nodes needs a machine with 8 GB or more. GitHub-hosted `ubuntu-latest` runners have enough memory for every example.

### A 20-node lab

These numbers come from one-off runs on the maintainer's machine. The topology, the recorded checks and the reports are not published yet, so treat them as a rough guide rather than evidence you can check.

Measured on 2026-10-27 on the same WSL2 machine, images already pulled: a leaf-spine fabric of 4 spines and 16 leaves, all FRR 10.4.1, 64 links, eBGP on every link with ECMP. `netdryrun record` turned the running lab into 560 checks (128 sessions, 128 prefix counts, 304 routes) in 11 seconds. Then `netdryrun run` on those 560 checks:

| Phase | Time |
|---|---|
| Deploy (containerlab, 20 nodes) | 9 s |
| BGP converged everywhere (polled once a second) | 9 s after deploy |
| 432 convergence checks done | 25 s after deploy |
| Settle, then 128 prefix counts held 10 s | 27 s |
| Destroy | 3 s |
| **Total, `netdryrun run`** | **65 s, all 560 passed** |

Two more runs on the same lab:

- **With a failure scenario** (spine1 isolated: 16 links down, 4 checks on leaf1): 128 s, all 564 passed. The scenario took 32 s (its checks, restoring the links, settling 10 s). Proving that all 432 convergence checks recovered afterwards took another 32 s.
- **With a broken change** (leaf16 stops announcing its LAN): 193 s, 83 failed, exactly the expected ones: the 19 routes to that LAN, the 60 leaf prefix counts that dropped from 15 to 14, and the 4 spine prefix counts that dropped from 1 to 0. The prefix counts failed within 31 s. The missing routes failed at 120 s, the `timeout` that `record` writes, so most of a failing run is that wait. Lower `timeout` if your lab converges faster.

Memory: 532 MiB for the 20 nodes at the peak (25 MiB per leaf, up to 58 MiB per spine with 16 BGP sessions), about 1 GB more host memory in use during the run, and 72 MB for Netdryrun itself. Netdryrun used a bit more than one core while polling.

At this size each polling round takes 9 to 12 seconds instead of the nominal 3, because every check is its own `docker exec` and Netdryrun runs 8 at a time. A check therefore needs about 20 seconds to collect its two passing samples even when the network converged sooner, and failure detection is coarser. Timeouts still work as documented: a check is only failed on a failing sample after its timeout. If a big lab's runs are too slow, trim the recorded file to the checks that matter.

## How long does a run take, and what does CI cost?

On GitHub-hosted `ubuntu-latest` runners, measured from three CI runs on `main` on 2026-10-27, before 0.3.0 added a few checks per example:

| CI job | What it does | Time |
|---|---|---|
| `e2e (frr-bgp)` | Install containerlab and Netdryrun, pull FRR, run the checks and a link-failure scenario | 100 to 107 s |
| `e2e (srl-frr)` | The same with SR Linux and FRR (the SR Linux image is 3.2 GB) | 88 to 107 s |
| `catches-bad-change` | Run `frr-bgp-broken` and expect it to fail | 54 to 66 s |
| `agent-demo` | Replay the agent demo: two full runs | 82 to 94 s |

The whole CI workflow, with these jobs in parallel, took 2 minutes 10 seconds to 2 minutes 38 seconds in the last ten successful runs.

GitHub Actions minutes are free on public repositories with standard GitHub-hosted runners. On private repositories, each job uses minutes from your plan, rounded up to the whole minute, so a job like `e2e (frr-bgp)` uses 2 minutes. See [GitHub's billing page](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions) for current prices. Netdryrun itself is free.

Local runs are faster once images are pulled; see the times on the [examples page](examples.md).

## Does it collect any data?

No. The CLI, the GitHub Action and the MCP server have no telemetry and don't phone home. Reports are written only to the files you ask for. The GitHub Action's `cloud` input is reserved for Netdryrun Cloud, a hosted service that is not available yet; setting it today uploads nothing. See [privacy](trust.md#privacy) and the [privacy notice](privacy.md).

## What is the license?

Apache-2.0, for the code. "Netdryrun" and the logo are trademarks: forks are welcome under a different name. See [Trust and security](trust.md#license).

## Where do I get help?

Read [Troubleshooting](troubleshooting.md) first. Then [open an issue](https://github.com/netdryrun/netdryrun/issues) with the JSON report attached. See [Support](support.md).


---
Source: https://netdryrun.com/corpus/

# Network Change Verdict Corpus

How much does a typical "ping after the change" test miss? This corpus answers that with data anyone can rerun.

!!! info "How to read these numbers"
    This is a small benchmark the Netdryrun maintainers wrote: one FRR provider topology, 30 changes in v1 and 18 in v2, each labelled harmful or safe before any run. It compares testing methods on the same changes. It is **not** an independent benchmark and **not** a reliability estimate for production networks: "24/30" does not mean Netdryrun is right 80% of the time on your network. Neither run used a released version. v1 ran on commit `ec23379`, a pre-release build that called itself 0.2.0 (the tagged 0.2.0 added a scenario-recovery fix and the SONiC and EOS drivers). v2 ran on a development build that also called itself 0.2.0 and recorded no commit ("commit `unknown`" below); it included the `inject_routes` fault, which first ships in 0.3.1. A rerun of both on the released 0.3.1 is pending, and these numbers will be replaced by its results. The [changes since](how-its-built.md#every-miss-and-what-it-changed) are listed per miss.

There are two runs. The v1 results below are frozen as first published. [Corpus v2](#corpus-v2) is a second, separately pre-registered run that makes v1's misses testable, including scenarios where a customer or peer misbehaves.

## Method

- **The network:** a small provider (AS65000, two routers) with a customer, an upstream transit and a settlement-free peer, running FRR in containerlab. Its written intent is in [INTENT.md](https://github.com/netdryrun/netdryrun/blob/main/corpus/INTENT.md).
- **The changes:** 30 realistic edits ([cases](https://github.com/netdryrun/netdryrun/tree/main/corpus/cases)): route leaks, filter typos, mass withdrawals, fat-fingered ASNs, latent risks, and safe changes that must not be blocked.
- **Pre-registered verdicts:** each case's expected verdict (would an experienced operator reject it?) was **committed to git before any run**. Verdicts are never edited afterwards; findings after the run are listed separately below.
- **Three strategies, same running lab per case:**
    1. **Ping only:** the customer pings the upstream and the peer.
    2. **All BGP sessions up:** every session established.
    3. **Netdryrun™ intent checks:** one [intent spec](https://github.com/netdryrun/netdryrun/blob/main/corpus/specs/intent.yml), written once and used unchanged for every case, so it can't be tuned to win.
- **Rerun it:** `python corpus/run.py` on any Linux or WSL2 machine with Docker and containerlab. It uses the Netdryrun code in your checkout.
- **Rerun it on GitHub's machines:** fork the repository, then run the [Reproduce corpus](https://github.com/netdryrun/netdryrun/blob/main/.github/workflows/reproduce-corpus.yml) workflow from your fork's Actions tab. It has not been run on GitHub yet, and it covers v1 only. It installs containerlab 0.81.1 and Netdryrun from your checkout (not the build that produced the committed results, so a verdict that differs can come from a code change) on a GitHub-hosted runner, runs every v1 case, uploads `results.json`, `RESULTS.md` and the run log as artifacts, and lists every verdict that differs from the committed [`results.json`](https://github.com/netdryrun/netdryrun/blob/main/corpus/results/results.json) in the run summary.

## Results



Generated 2026-10-27T18:00:53+00:00 with netdryrun 0.3.1, containerlab 0.81.1, FRR quay.io/frrouting/frr:10.4.1, commit `08059de`. Rerun everything with `python corpus/run.py`.

**Conflict of interest:** the Netdryrun maintainers wrote this corpus and the runner. Expected verdicts were committed before any run (see the git history of [`corpus/cases/`](https://github.com/netdryrun/netdryrun/tree/main/corpus/cases)). Losses are kept and shown at the same size as the catches.

## Summary (30 cases: 19 harmful, 11 safe)

| Strategy | Correct | Harmful changes caught | Approved a bad change | Blocked a good change | Errors |
|---|---|---|---|---|---|
| Ping only | **20/30** | 9/19 | 10 | 0 | 0 |
| All BGP sessions up | **15/30** | 4/19 | 15 | 0 | 0 |
| Netdryrun intent checks | **24/30** | 14/19 | 5 | 1 | 0 |

## Every case

| Case | Category | Expected | Ping only | Sessions up | Netdryrun | What Netdryrun flagged |
|---|---|---|---|---|---|---|
| `01-no-change` [No change (control)](corpus/01-no-change.md) | control | safe | ✅ | ✅ | ✅ | nothing |
| `02-med-to-upstream` [Set MED on routes sent to the upstream](corpus/02-med-to-upstream.md) | traffic-engineering | safe | ✅ | ✅ | ✅ | nothing |
| `03-prepend-to-peer` [Prepend our AS twice toward the peer](corpus/03-prepend-to-peer.md) | traffic-engineering | safe | ✅ | ✅ | ✅ | nothing |
| `04-tag-community-upstream` [Tag our aggregate with an informational community toward the upstream](corpus/04-tag-community-upstream.md) | hygiene | safe | ✅ | ✅ | ✅ | nothing |
| `05-description-only` [Change an interface description](corpus/05-description-only.md) | hygiene | safe | ✅ | ✅ | ✅ | nothing |
| `06-customer-adds-prefix` [Customer announces a second allowed /24](corpus/06-customer-adds-prefix.md) | customer-growth | safe | ✅ | ✅ | ⚠️ blocked a good change | I5 upstream receives exactly our 2 prefixes; I5 peer receives exactly our 2 prefixes |
| `07-tighten-max-prefix` [Lower the customer maximum-prefix from 100 to 50](corpus/07-tighten-max-prefix.md) | hygiene | safe | ✅ | ✅ | ✅ | nothing |
| `08-upstream-timers` [Shorten BGP timers toward the upstream](corpus/08-upstream-timers.md) | hygiene | safe | ✅ | ✅ | ✅ | nothing |
| `09-customer-localpref` [Lower customer local-preference from 300 to 250](corpus/09-customer-localpref.md) | traffic-engineering | safe | ✅ | ✅ | ✅ | nothing |
| `10-transit-export-filter-removed` [Upstream export filter replaced with permit-all](corpus/10-transit-export-filter-removed.md) | route-leak | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I4 no peer route leaked to upstream; I5 upstream receives exactly our 2 prefixes |
| `11-peer-export-filter-removed` [Peer export filter replaced with permit-all](corpus/11-peer-export-filter-removed.md) | route-leak | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I4 no upstream route leaked to peer; I4 no default leaked to peer; I5 peer receives exactly our 2 prefixes |
| `12-ibgp-send-community-dropped` [send-community removed on the pe1 to pe2 iBGP session](corpus/12-ibgp-send-community-dropped.md) | policy-bug | unsafe | ❌ approved a bad change | ❌ approved a bad change | ❌ approved a bad change | nothing |
| `13-upstream-asn-typo` [Typo in the upstream's ASN (65020 instead of 65200)](corpus/13-upstream-asn-typo.md) | fat-finger | unsafe | ✅ | ✅ | ✅ | I1 pe1-up1 session up; I2 upstream has customer route; I2 upstream has our aggregate; I3 customer has upstream route; I3 customer has default; I3 customer reaches upstream; I4 no peer route leaked to upstream; I5 upstream receives exactly our 2 prefixes |
| `14-peer-session-shutdown` [Peer session administratively shut down](corpus/14-peer-session-shutdown.md) | fat-finger | unsafe | ✅ | ✅ | ✅ | I1 pe2-peer1 session up; I2 peer has customer route; I2 peer has our aggregate; I3 customer has peer route; I3 customer reaches peer; I4 no upstream route leaked to peer; I4 no default leaked to peer; I5 peer receives exactly our 2 prefixes |
| `15-customer-filter-too-strict` [Customer prefix-list typo rejects the customer's /24](corpus/15-customer-filter-too-strict.md) | policy-bug | unsafe | ✅ | ❌ approved a bad change | ✅ | I2 upstream has customer route; I2 peer has customer route; I3 customer reaches upstream; I3 customer reaches peer; I5 upstream receives exactly our 2 prefixes; I5 peer receives exactly our 2 prefixes |
| `16-mass-withdrawal` [Upstream export policy denies everything](corpus/16-mass-withdrawal.md) | withdrawal | unsafe | ✅ | ❌ approved a bad change | ✅ | I2 upstream has customer route; I2 upstream has our aggregate; I3 customer reaches upstream; I5 upstream receives exactly our 2 prefixes |
| `17-default-leaked-to-peer` [default-originate configured toward the peer](corpus/17-default-leaked-to-peer.md) | route-leak | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I4 no default leaked to peer; I5 peer receives exactly our 2 prefixes |
| `18-redistribute-connected` [redistribute connected added on pe1](corpus/18-redistribute-connected.md) | hygiene | unsafe | ❌ approved a bad change | ❌ approved a bad change | ❌ approved a bad change | nothing |
| `19-nexthop-self-removed` [next-hop-self removed on pe2 toward pe1](corpus/19-nexthop-self-removed.md) | policy-bug | unsafe | ✅ | ❌ approved a bad change | ✅ | I3 customer reaches peer |
| `20-ibgp-shutdown` [iBGP session between pe1 and pe2 shut down](corpus/20-ibgp-shutdown.md) | fat-finger | unsafe | ✅ | ✅ | ✅ | I1 pe1-pe2 iBGP up; I2 peer has customer route; I2 peer has our aggregate; I3 customer has peer route; I3 customer reaches peer; I5 peer receives exactly our 2 prefixes |
| `21-customer-max-prefix-removed` [Customer maximum-prefix safety limit removed](corpus/21-customer-max-prefix-removed.md) | latent-risk | unsafe | ❌ approved a bad change | ❌ approved a bad change | ❌ approved a bad change | nothing |
| `22-customer-leaks-third-party` [Customer announces someone else's prefix; our filter blocks it](corpus/22-customer-leaks-third-party.md) | filter-works | safe | ✅ | ✅ | ✅ | nothing |
| `23-fat-finger-third-party-origin` [pe1 accidentally originates 8.8.8.0/24](corpus/23-fat-finger-third-party-origin.md) | hijack | unsafe | ❌ approved a bad change | ❌ approved a bad change | ❌ approved a bad change | nothing |
| `24-customer-blackholed` [Static discard route for the customer prefix on pe1](corpus/24-customer-blackholed.md) | fat-finger | unsafe | ✅ | ❌ approved a bad change | ✅ | I3 customer reaches upstream; I3 customer reaches peer |
| `25-aggregate-typo` [Aggregate network statement typo (192.0.3.0/24)](corpus/25-aggregate-typo.md) | fat-finger | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I2 upstream has our aggregate; I2 peer has our aggregate; I5 upstream receives exactly our 2 prefixes; I5 peer receives exactly our 2 prefixes |
| `26-route-map-order-bug` [A permit-everything clause inserted before the peer export filter](corpus/26-route-map-order-bug.md) | route-leak | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I4 no upstream route leaked to peer; I4 no default leaked to peer; I5 peer receives exactly our 2 prefixes |
| `27-local-asn-typo` [pe2 configured with the wrong local ASN](corpus/27-local-asn-typo.md) | fat-finger | unsafe | ✅ | ✅ | ✅ | I1 pe1-pe2 iBGP up; I1 pe2-peer1 session up; I2 peer has customer route; I2 peer has our aggregate; I3 customer has peer route; I3 customer reaches peer; I4 no upstream route leaked to peer; I4 no default leaked to peer; I5 peer receives exactly our 2 prefixes |
| `28-customer-import-policy-removed` [Customer inbound route-map removed](corpus/28-customer-import-policy-removed.md) | policy-bug | unsafe | ✅ | ❌ approved a bad change | ✅ | I2 upstream has customer route; I2 peer has customer route; I3 customer reaches upstream; I3 customer reaches peer; I5 upstream receives exactly our 2 prefixes; I5 peer receives exactly our 2 prefixes |
| `29-graceful-restart` [Enable BGP graceful restart on pe1](corpus/29-graceful-restart.md) | hygiene | safe | ✅ | ✅ | ✅ | nothing |
| `30-peer-import-filter-removed` [Peer inbound filter replaced with permit-all](corpus/30-peer-import-filter-removed.md) | latent-risk | unsafe | ❌ approved a bad change | ❌ approved a bad change | ❌ approved a bad change | nothing |

## Netdryrun's losses

- **`06-customer-adds-prefix` Customer announces a second allowed /24** (false block). Normal customer growth inside the registered range.
- **`12-ibgp-send-community-dropped` send-community removed on the pe1 to pe2 iBGP session** (false pass). A common mistake when rebuilding iBGP sessions.
- **`18-redistribute-connected` redistribute connected added on pe1** (false pass). Not covered by the intent spec, which has no check for infrastructure routes at the customer.
- **`21-customer-max-prefix-removed` Customer maximum-prefix safety limit removed** (false pass). Latent risk: no steady-state check can see it until the customer actually leaks. Catching it needs a failure-injection scenario (the customer sends many prefixes), planned for a later release.
- **`23-fat-finger-third-party-origin` pe1 accidentally originates 8.8.8.0/24** (false pass). Not covered by the intent spec, which has no check for unexpected routes at the customer.
- **`30-peer-import-filter-removed` Peer inbound filter replaced with permit-all** (false pass). Latent risk: invisible in steady state until the peer misbehaves. Needs a failure-injection scenario.

## Findings after the run

These findings came after the run. The table above is left exactly as pre-registered; nothing in [`corpus/cases/`](https://github.com/netdryrun/netdryrun/tree/main/corpus/cases) was edited.

**Case 12 was labeled wrong.** The case expected that removing `neighbor 10.0.3.2 send-community` on pe1 stops pe2 from seeing the customer community. In FRR (verified on 10.4.1) communities are sent to every neighbor by default, so deleting the explicit line is a no-op: `show running-config` no longer shows it, but pe1 still advertises `10.100.0.0/24` to pe2 with community `65000:100`, and pe2 still matches it (`show bgp ipv4 unicast community 65000:100` lists the route). Reproduce with `scripts/corpus_case12_verify.sh`. The change is actually safe, so all three strategies answered case 12 correctly. With that one label corrected the scores would be: ping only 21/30, sessions up 16/30, Netdryrun 25/30. The headline numbers stay at the pre-registered values. The mistake would have been real on platforms that do not send communities by default (Cisco IOS, for example); a vendor-specific version of this case belongs in a future corpus.

**Cases 18, 23, 21 and 30 are real misses.** 18 and 23 are gaps in the intent spec (no check for unexpected routes reaching the customer or the upstream). 21 and 30 are latent risks that no steady-state check can see; they need a failure-injection scenario where the customer or peer actually misbehaves. These stay as losses.



## Corpus v2

The v1 results above are frozen. Corpus v2 is a separate, second run with its own pre-registered cases. It turns v1's misses into things a test can see:

- **Unexpected routes** (v1 cases 18 and 23): the v2 intent spec says infrastructure prefixes and a sentinel list of well-known third-party prefixes must never be BGP routes at the customer, the upstream or the peer. These are `route` checks with `present: false`; no new check type is needed.
- **Latent risks** (v1 cases 21 and 30): two failure scenarios use the [`inject_routes`](reference/config.md#injecting-routes) fault, which ships in Netdryrun 0.3.1, to make a neighbor misbehave. The customer floods 200 more-specifics from its own /16, and the peer announces a more-specific of our customer's space and a third-party /24. The checks then verify that the max-prefix limit and the import filter actually hold.
- **Rigid counts** (v1 case 06): announced-prefix counts are a range (2 to 51), so customer growth inside its block is not blocked.
- **Vendor defaults** (v1 case 12): the FRR no-op is labeled safe, and the genuinely harmful variant is a separate case.

v2 changes two lines in the base lab so the customer's max-prefix limit can actually trip: in v1 the customer filter allowed at most 7 prefixes, so a limit of 100 could never be reached. The differences, the written intent (I1 to I9) and the disclosures are in [v2/INTENT.md](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/INTENT.md). The spec is [v2/specs/intent.yml](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/specs/intent.yml).

**Pre-registration:** all 18 cases and their expected verdicts were committed and pushed in [`322cc4e`](https://github.com/netdryrun/netdryrun/commit/322cc4ede21492c3914a0a53b67268bea7abf7d6) (2026-10-27 04:02 UTC), before any v2 case was deployed. Rerun it with `python corpus/run.py --corpus v2`.

Generated 2026-10-27T19:05:43+00:00 with netdryrun 0.3.1, containerlab 0.81.1, FRR quay.io/frrouting/frr:10.4.1, commit `08059de`. Rerun everything with `python corpus/run.py --corpus v2`.

**Conflict of interest:** the Netdryrun maintainers wrote this corpus and the runner. Expected verdicts were committed before any run (see the git history of [`corpus/v2/cases/`](https://github.com/netdryrun/netdryrun/tree/main/corpus/v2/cases)). Losses are kept and shown at the same size as the catches.

### Summary (18 cases: 11 harmful, 7 safe)

| Strategy | Correct | Harmful changes caught | Approved a bad change | Blocked a good change | Errors |
|---|---|---|---|---|---|
| Ping only | **9/18** | 2/11 | 9 | 0 | 0 |
| All BGP sessions up | **7/18** | 0/11 | 11 | 0 | 0 |
| Netdryrun intent checks | **17/18** | 10/11 | 1 | 0 | 0 |

### Every case

| Case | Category | Expected | Ping only | Sessions up | Netdryrun | What Netdryrun flagged |
|---|---|---|---|---|---|---|
| `01-no-change` [No change (control)](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/01-no-change.yml) | control | safe | ✅ | ✅ | ✅ | nothing |
| `02-redistribute-connected-pe2` [redistribute connected added on pe2](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/02-redistribute-connected-pe2.yml) | hygiene | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I6 customer has no BGP route for link 10.0.3.0/30; I6 customer has no BGP route for link 10.0.4.0/30; I6 customer has no BGP route for pe2 loopback |
| `03-test-prefix-left-in-config` [pe1 originates 1.1.1.0/24 left over from a lab test](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/03-test-prefix-left-in-config.yml) | hijack | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I7 customer has no route for 1.1.1.0/24 |
| `04-redundant-aggregate-typo` [Aggregate added on pe2 for redundancy, mistyped as 192.0.12.0/24](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/04-redundant-aggregate-typo.yml) | hijack | unsafe | ❌ approved a bad change | ❌ approved a bad change | ❌ approved a bad change | nothing |
| `05-customer-max-prefix-removed` [Customer maximum-prefix safety limit removed](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/05-customer-max-prefix-removed.yml) | latent-risk | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | [customer floods 200 prefixes] I8 upstream still receives at most 51 prefixes; [customer floods 200 prefixes] I8 peer still receives at most 51 prefixes |
| `06-peer-import-filter-permit-all` [Peer inbound filter replaced with permit-all](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/06-peer-import-filter-permit-all.yml) | latent-risk | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | [peer announces routes it does not own] I9 pe2 accepts only the peer's own prefix; [peer announces routes it does not own] I9 customer gets no hijacking more-specific; [peer announces routes it does not own] I9 pe1 has no third-party route from the peer |
| `07-customer-adds-prefixes` [Customer announces two more /24s from its /16](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/07-customer-adds-prefixes.yml) | customer-growth | safe | ✅ | ✅ | ✅ | nothing |
| `08-customer-announces-aggregate` [Customer also announces its covering /16](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/08-customer-announces-aggregate.yml) | customer-growth | safe | ✅ | ✅ | ✅ | nothing |
| `09-ibgp-send-community-line-removed` [Explicit send-community line removed on the pe1 to pe2 iBGP session](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/09-ibgp-send-community-line-removed.yml) | vendor-default | safe | ✅ | ✅ | ✅ | nothing |
| `10-ibgp-standard-communities-disabled` [Standard communities explicitly disabled on the pe1 to pe2 iBGP session](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/10-ibgp-standard-communities-disabled.yml) | policy-bug | unsafe | ✅ | ❌ approved a bad change | ✅ | I2 peer has customer route; I3 customer reaches peer; I5 peer receives 2 to 51 prefixes from us |
| `11-customer-max-prefix-warning-only` [Customer maximum-prefix changed to warning-only](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/11-customer-max-prefix-warning-only.yml) | latent-risk | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | [customer floods 200 prefixes] I8 upstream still receives at most 51 prefixes; [customer floods 200 prefixes] I8 peer still receives at most 51 prefixes |
| `12-customer-max-prefix-raised` [Customer maximum-prefix raised from 50 to 100](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/12-customer-max-prefix-raised.yml) | hygiene | safe | ✅ | ✅ | ✅ | nothing |
| `13-upstream-routes-tagged-as-customer` [Upstream import policy tags routes with the customer community (copy-paste error)](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/13-upstream-routes-tagged-as-customer.yml) | route-leak | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I4 no upstream route leaked to peer; I4 no default leaked to peer |
| `14-customer-gets-default-only` [Customer export policy restricted to the default route](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/14-customer-gets-default-only.yml) | policy-bug | unsafe | ✅ | ❌ approved a bad change | ✅ | I3 customer has upstream route; I3 customer has peer route; I3 customer reaches upstream; I3 customer reaches peer |
| `15-upstream-default-filtered` [Default route from the upstream filtered on import](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/15-upstream-default-filtered.yml) | policy-bug | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I3 customer has default |
| `16-customer-session-peer-group` [Customer session moved into a CUSTOMERS peer-group](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/16-customer-session-peer-group.yml) | refactor | safe | ✅ | ✅ | ✅ | nothing |
| `17-customer-region-community` [Add an informational region community to customer routes](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/17-customer-region-community.yml) | hygiene | safe | ✅ | ✅ | ✅ | nothing |
| `18-aggregate-discard-route-removed` [Discard route for our aggregate deleted as unused](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/cases/18-aggregate-discard-route-removed.yml) | hygiene | unsafe | ❌ approved a bad change | ❌ approved a bad change | ✅ | I2 upstream has our aggregate; I2 peer has our aggregate; I5 upstream receives 2 to 51 prefixes from us; I5 peer receives 2 to 51 prefixes from us |

### Netdryrun's losses

- **`04-redundant-aggregate-typo` Aggregate added on pe2 for redundancy, mistyped as 192.0.12.0/24** (false pass). Expected to be missed. I7 only spot-checks a few well-known prefixes, and nothing bounds what the customer receives.

### Findings after the run

These findings came after the v2 run. The table above is left exactly as pre-registered in commit `322cc4e`; nothing in [`corpus/v2/cases/`](https://github.com/netdryrun/netdryrun/tree/main/corpus/v2/cases) was edited.

**Run provenance.** `results.json` records the commit as `unknown`: the run used git inside WSL on a Windows git worktree, and that git could not read the worktree. The run started at 04:02:42 UTC, 16 seconds after the pre-registration commit `322cc4e`. `src/` and `corpus/run.py` were not changed during the run. The renderer, the docs and the unit tests were edited during the run, and none of them affect verdicts.

**Case 04 is a real miss, as predicted.** pe2 announced the mistyped 192.0.12.0/24 to pe1 and on to the customer, and no check looked for it. I7 only spot-checks a few well-known prefixes, and nothing bounds what the customer receives. Catching this class needs a check that the customer receives only routes from known origins, or only expected prefixes from our own AS. No such check type exists yet.

**Case 18 is a real miss.** With the discard route deleted, FRR (traditional defaults, no `bgp network import-check`) kept announcing 192.0.2.0/24, so I2 passed. The harm is the routing loop for unused addresses inside the aggregate, which no check probes. A `ping` with `expect: failure` to an unused address in 192.0.2.0/24 from the upstream would not show the loop either, because ping fails both with and without it. Catching it needs a path or traceroute check (TTL exceeded versus a clean discard).

**Ping only's catch of case 14 is partly a lab artifact.** In the lab, the customer's BGP default is not active, because containerlab's management default route outranks it (the spec checks the default with `active: false` for this reason). Once the customer lost its specific routes, its pings had no path at all. A real customer with a working default would still ping, and the ping baseline would pass the change. The result stays as measured.

**Rerun on the released 0.3.1 (2026-10-27, by the release gate):** every verdict matches the first run except case 18 (`18-aggregate-discard-route-removed`). The development build approved it; 0.3.1 rejects it, which is the pre-registered expected verdict, because the upstream and the peer no longer receive the aggregate (checks I2 and I5 fail). 0.3.1 changed how routes are read (received paths count, errors are never read as "no routes"), and this case was one of v2's two misses. Netdryrun is now 17/18 on v2. The cases and the expected verdicts are unchanged.


---
Source: https://netdryrun.com/how-its-built/

# How Netdryrun is built and verified

A tool that approves network changes has to earn trust with evidence, not claims. Most of this page links to something you can inspect or rerun yourself: the test corpus, the CI runs, the commit history and the release pipeline. Where a claim can't be checked yet, the page says so.

## At a glance

| | Evidence |
|---|---|
| Accuracy on realistic BGP changes | Verdict Corpus v1: **24/30** (ping only 20/30, sessions up 15/30). v2: **17/18** (ping only 9/18, sessions up 7/18). Both ran on the released 0.3.1 (the release gate reruns them for every release). [Results](corpus.md) |
| Expected verdicts fixed before any run | Committed first, never edited: [`b4df0b0`](https://github.com/netdryrun/netdryrun/commit/b4df0b0) (v1), [`322cc4e`](https://github.com/netdryrun/netdryrun/commit/322cc4e) (v2) |
| Results you can rerun | One command locally (`python corpus/run.py`, `--corpus v2` for v2). The [Reproduce corpus](https://github.com/netdryrun/netdryrun/blob/main/.github/workflows/reproduce-corpus.yml) workflow reruns v1 from your own fork; it has not been run on GitHub yet |
| Real labs on every change | FRR and Nokia SR Linux labs boot in CI on every push and pull request ([runs](https://github.com/netdryrun/netdryrun/actions/workflows/ci.yml)) |
| What users install is tested too | The released Action and the PyPI package, on every push and weekly ([`published-action.yml`](https://github.com/netdryrun/netdryrun/blob/main/.github/workflows/published-action.yml)) |
| Supply chain | PyPI Trusted Publishing, CodeQL, OpenSSF Scorecard, every Action pinned to a commit |
| Losses | Published next to the wins, never removed |

## Engineering process

Netdryrun is developed by its maintainer, Victor Khen, with AI coding agents doing most of the implementation: code, tests, documentation and this website. The maintainer sets the direction, reviews the results, decides what ships and publishes every release. The [commit history](https://github.com/netdryrun/netdryrun/commits/main) records every change.

We state this plainly because it should shape how you judge the tool: not by who or what wrote it, but by whether it holds up under checks you can run yourself. That is why the claims below come with evidence.

The project is very young. It started in October 2026: the first commit is dated 27 October 2026, and versions 0.1.0, 0.2.0 and 0.3.0 were all released that same day. It has no outside contributors yet.

## Pre-registered accuracy testing

The [Verdict Corpus](corpus.md) measures Netdryrun on realistic BGP changes, each labelled harmful or safe in advance, and compares it with two common checks: "ping still works" and "all BGP sessions are up".

- **Verdicts are committed before anything runs.** v1: all 30 cases with their expected verdicts in [`b4df0b0`](https://github.com/netdryrun/netdryrun/commit/b4df0b0), results later in [`7576298`](https://github.com/netdryrun/netdryrun/commit/7576298). v2: 18 new cases in [`322cc4e`](https://github.com/netdryrun/netdryrun/commit/322cc4e), results later in [`669b30f`](https://github.com/netdryrun/netdryrun/commit/669b30f). No case was edited after a run ([history of `corpus/cases/`](https://github.com/netdryrun/netdryrun/commits/main/corpus/cases)).
- **The tool was run on the corpus during development, and changed before the published runs.** During 0.2.0 development, runs against the v1 cases found a bug (a change that broke a baseline check ended a scenario run as `error`) and showed that the new polling made the corpus 2 to 3 times faster; both are in the [changelog](https://github.com/netdryrun/netdryrun/blob/main/CHANGELOG.md). The expected verdicts were not changed; the v1 intent spec changed by one comment line.
- **Neither published run used a release.** v1 ran on commit `ec23379`, which called itself 0.2.0, before the tagged 0.2.0 (which added a scenario-recovery fix and the SONiC and EOS drivers). v2 ran on a development build that also called itself 0.2.0, recorded no commit, and included the `inject_routes` fault, which first ships in 0.3.1. A rerun of both on the released 0.3.1 is pending.
- **v2 is a harder test, not a friendlier one.** Its cases target the kinds of change v1 missed. It was written after seeing v1's results, which is a limitation to keep in mind.
- **Everything reruns.** The runner ([`corpus/run.py`](https://github.com/netdryrun/netdryrun/blob/main/corpus/run.py)), every case and the raw output ([`results.json`](https://github.com/netdryrun/netdryrun/blob/main/corpus/results/results.json)) are public. `python corpus/run.py` reruns v1 and `--corpus v2` reruns v2, with the code you have checked out (so a different verdict can come from a code change, not only from noise). The GitHub workflow reruns v1 the same way on a hosted runner and lists any verdict that differs; it has not been run on GitHub yet, and it does not cover v2.
- **Limit of this evidence:** git commit dates come from the author's machine. The history proves the order of the commits and that the cases were not changed; it is not an independent timestamp.

## Every miss, and what it changed

A test you always pass tells you nothing. Netdryrun's misses stay in the published results, at the same size as its catches, and each one has driven a specific improvement.


**Verdict Corpus v1: wrong on 6 of 30 cases.** It approved 5 harmful changes and blocked 1 safe one ([RESULTS.md](https://github.com/netdryrun/netdryrun/blob/main/corpus/RESULTS.md)).


**Verdict Corpus v2: wrong on 2 of 18 cases**, both harmful changes approved ([v2 results](https://github.com/netdryrun/netdryrun/blob/main/corpus/v2/RESULTS.md)).

| Case | Outcome | Root cause | What changed | Status |
|---|---|---|---|---|
| v1 [06](corpus/06-customer-adds-prefix.md): customer announces a second allowed /24 | Blocked a safe change | The intent spec pinned exactly 2 prefixes towards the upstream and peer, so normal customer growth looked like a leak | v2 checks a range (2 to 51 prefixes); the growth cases 07 and 08 pass | Fixed |
| v1 [12](corpus/12-ibgp-send-community-dropped.md): send-community removed on iBGP | Approved | **Our label was wrong.** On FRR, communities are sent by default, so the change is a no-op ([AMENDMENTS.md](https://github.com/netdryrun/netdryrun/blob/main/corpus/AMENDMENTS.md), with a reproduction script) | Scored as a loss anyway, never corrected in our favour. v2 case 09 tests the corrected expectation and case 10 the truly harmful variant; both judged correctly | Label error |
| v1 [18](corpus/18-redistribute-connected.md): redistribute connected on pe1 | Approved | Spec gap: nothing checked for infrastructure routes leaving the AS | New intent I6: no link or loopback routes at the customer, upstream or peer. v2 case 02 (the same mistake on pe2) caught | Fixed |
| v1 [23](corpus/23-fat-finger-third-party-origin.md): pe1 originates 8.8.8.0/24 | Approved | Spec gap: nothing checked for third-party space | New intent I7, a sentinel list of well-known prefixes. v2 case 03 caught | Partly fixed (see v2 04) |
| v1 [21](corpus/21-customer-max-prefix-removed.md): customer max-prefix removed | Approved | Latent risk, invisible until the customer misbehaves | New `inject_routes` failure scenario: the customer floods 200 prefixes. v2 cases 05 and 11 caught | Fixed (the scenario ships in 0.3.1) |
| v1 [30](corpus/30-peer-import-filter-removed.md): peer inbound filter replaced with permit-all | Approved | Latent risk, invisible until the peer misbehaves | The same scenario type, with the peer announcing routes it does not own. v2 case 06 caught | Fixed (the scenario ships in 0.3.1) |
| v2 04: redundant aggregate mistyped as 192.0.12.0/24 | Approved | I7 checks only a few well-known prefixes; nothing bounds what the customer receives | Predicted as a likely miss in the case file before the run | Open |
| v2 18: discard route for the aggregate deleted | Approved | Causes a routing loop for unused addresses inside the aggregate; no check sends traffic there | A reachability check towards unused space would catch it | Open |

Two caveats apply. v2 was written after seeing v1's misses, so its improvements are measured on cases designed by the same team. And the corpus runs on FRR only, with one topology.

## Continuous integration with live labs

Every push to `main` and every pull request runs [`ci.yml`](https://github.com/netdryrun/netdryrun/blob/main/.github/workflows/ci.yml) ([runs](https://github.com/netdryrun/netdryrun/actions/workflows/ci.yml)): unit tests on Python 3.10, 3.12 and 3.13, plus three jobs that boot real containerlab labs.

- **`e2e`** runs the GitHub Action on [`examples/frr-bgp`](https://github.com/netdryrun/netdryrun/tree/main/examples/frr-bgp) and [`examples/srl-frr`](https://github.com/netdryrun/netdryrun/tree/main/examples/srl-frr) (FRR and Nokia SR Linux). Both must pass.
- **`catches-bad-change`** runs [`examples/frr-bgp-broken`](https://github.com/netdryrun/netdryrun/tree/main/examples/frr-bgp-broken), a change that leaks a default route. The job succeeds only if Netdryrun rejects it.
- **`agent-demo`** replays [`examples/agent-demo`](https://github.com/netdryrun/netdryrun/tree/main/examples/agent-demo): a route-leaking change must fail on exactly the leak guards, and the proper fix must pass.

A second workflow, [`published-action.yml`](https://github.com/netdryrun/netdryrun/blob/main/.github/workflows/published-action.yml), tests what users install rather than the code on `main`: the released Action by its tag (it must pass a good change and reject a bad one), and `pip install` and `uvx` from PyPI on every supported Python version, including an MCP handshake.

SONiC and Arista EOS are not in CI yet (cEOS is an image each user downloads from Arista). Their unit tests parse output captured from real lab runs ([`tests/fixtures`](https://github.com/netdryrun/netdryrun/tree/main/tests/fixtures)).

Every release also goes through a seven-layer release gate, from linting and mutation testing of the verdict logic to chaos runs on the built package, described in [RELEASING.md](https://github.com/netdryrun/netdryrun/blob/main/RELEASING.md); from the next release on, each release's results are committed in `releases/<version>/GATE.md`.

## Performance on a 20-node fabric

On a 20-node leaf-spine fabric (4 spines, 16 leaves, FRR, 64 links), `netdryrun record` produced 560 checks in 11 seconds, and a full `netdryrun run` (deploy, convergence, all checks, destroy) took 65 seconds. A deliberately broken change failed exactly the 83 checks it should have. Full numbers, memory use and limits are in the [FAQ](faq.md#a-20-node-lab). These come from one-off runs on the maintainer's machine; the topology and the reports are not published yet, so you can't check them the way you can check the corpus.

## Cross-model review (not a human audit)

Before releases 0.1.0 and 0.2.0, the code was also reviewed by AI models from other vendors (OpenAI GPT and xAI Grok); 0.3.0 was not. Separate agent sessions that start without the author's context also review changes. These review outputs are not published. Fixes from these reviews: [`ec23379`](https://github.com/netdryrun/netdryrun/commit/ec23379) (v0.2.0), [`6495759`](https://github.com/netdryrun/netdryrun/commit/6495759) (agent demo) and [`90fe0ae`](https://github.com/netdryrun/netdryrun/commit/90fe0ae): a security review of the MCP server, the GitHub Action and every path where lab output reaches a shell, a device CLI or a PR comment, with 7 findings, each fixed with a regression test.

These reviewers are AI models, not human auditors. No independent human security audit has been done yet. If you are qualified and willing to do one, we would welcome it: see the [security policy](https://github.com/netdryrun/netdryrun/security/policy).

## Defects found by our own testing

Each was found by running Netdryrun against live labs or the corpus, and is recorded in the [changelog](https://github.com/netdryrun/netdryrun/blob/main/CHANGELOG.md).

- **False passes on SR Linux and Arista:** a leaked route that was received but not installed was invisible, so a `present: false` check passed when it should have failed. Fixed in [`77f43d6`](https://github.com/netdryrun/netdryrun/commit/77f43d6), with regression tests on captured output ([`test_drivers.py`](https://github.com/netdryrun/netdryrun/blob/main/tests/test_drivers.py)).
- **Wrong status after a failure scenario:** a change that broke a baseline check ended as `error` instead of `failed`. Found with [`scripts/pack_verify.sh`](https://github.com/netdryrun/netdryrun/blob/main/scripts/pack_verify.sh); fixed in [`f6ea560`](https://github.com/netdryrun/netdryrun/commit/f6ea560).
- **PR comments over GitHub's size limit on large labs:** found by the 20-node scale test. From 0.3.1, the comment is cut to fit GitHub's limit, failures first, and says how many checks it left out; the JSON and JUnit reports keep every check.
- **A mislabeled corpus case:** [case 12](corpus/12-ibgp-send-community-dropped.md), above.

## Supply-chain security

- **Releases** are published to PyPI with Trusted Publishing, so no tokens are stored ([`release.yml`](https://github.com/netdryrun/netdryrun/blob/main/.github/workflows/release.yml)). A release fails if the tag and the package version differ.
- **OpenSSF Scorecard** rates the repository's practices weekly and on every push ([current score](https://scorecard.dev/viewer/?uri=github.com/netdryrun/netdryrun)), including the areas where a young, single-maintainer project scores low.
- **CodeQL** scans the Python code and the workflows ([`codeql.yml`](https://github.com/netdryrun/netdryrun/blob/main/.github/workflows/codeql.yml)).
- **Every third-party GitHub Action is pinned to a commit**, in the workflows and in [`action.yml`](https://github.com/netdryrun/netdryrun/blob/main/action.yml). Dependabot keeps the pins current.

## What we do not claim

- **Not production safety.** A pass means the change behaved correctly in a lab running open-source or lab images of network operating systems. It does not prove the change is safe on your network ([what a lab cannot prove](trust.md#what-a-lab-cannot-prove)).
- **Not Internet scale.** The largest measured lab has 20 nodes and small routing tables. Nothing here is tested with full Internet tables or hundreds of peers.
- **Not vendor parity.** FRR, SR Linux, SONiC and cEOS behave differently from each other and from hardware routers. The corpus runs only on FRR, with one topology and one intent spec per version, all written by the Netdryrun maintainers.
- **Not adoption.** Nothing on this site claims who uses Netdryrun.


---
Source: https://netdryrun.com/when-to-use-what/

# When to use what

Several good open-source tools help you test network changes. They answer different questions and work well together. This page tries to describe each one fairly; if something here is wrong or out of date, please [open an issue](https://github.com/netdryrun/netdryrun/issues).

## The short version

| Tool | Best at | Runs routers? |
|---|---|---|
| [Batfish](https://batfish.org) | Analyzing configs of many vendors without booting anything: reachability, ACLs and firewall rules, routing, differences between two snapshots | No, it models them |
| [pyATS / Genie](https://developer.cisco.com/pyats/) | A full Python test framework with a large library of device parsers, for testing labs and real (including production) devices, with state snapshots and diffs | Works against any reachable device |
| [containerlab](https://containerlab.dev) | Running container-based network labs from a YAML topology, for many network operating systems | Yes, it is the lab |
| Your own scripts | Exactly the checks your team needs, around a lab you already run, with no new dependency | Yes, through containerlab |
| Netdryrun™ | Declarative, convergence-aware checks on a containerlab lab, packaged for CI with a pass/fail verdict and evidence | Yes, through containerlab |

## Batfish

Batfish parses device configs and builds a model of the network's control and data plane. Because nothing has to boot, it is fast, covers large networks, and supports configs from many vendors. It can answer broad questions ("can any host in this subnet reach that server?", "what changed between these two snapshots?") that are hard to test by sending packets.

Use it when you want broad, fast analysis on every commit, especially for ACLs, firewall policy and multi-vendor configs that you cannot run in containers.

A model is not the running software, so behavior that depends on the real implementation (timers, convergence order, bugs) is outside what it sees. That is where a lab helps.

## pyATS / Genie

pyATS is a mature Python test framework from Cisco, and Genie adds a large library of parsers and models that turn CLI output into structured data. It can learn the state of a device, take before and after snapshots, and diff them. It works against lab devices and real ones.

Use it when you need deep, programmable testing, broad parser coverage (especially for Cisco platforms), or pre- and post-change checks on production devices.

Netdryrun is much smaller: a YAML file and a GitHub Action, with no test code to write, and it only runs against labs. If you already have pyATS tests, keep them.

## containerlab

containerlab runs network labs from a YAML topology: container-native network operating systems (such as Nokia SR Linux, Arista cEOS, Juniper cRPD, FRR) and, through vrnetlab, many VM-based ones. It handles wiring, management addresses and lifecycle.

Use it whenever you want a real lab on a laptop or a CI runner. Netdryrun does not replace it; Netdryrun drives it.

## Your own scripts around containerlab

Many teams already run containerlab in CI with a script that deploys the lab, sleeps, runs a few `show` commands or pings, and tears down. That is free, flexible, and needs no new tool. If your checks are few and your lab rarely changes, keep it.

Scripts tend to get harder in the same places, and those are what Netdryrun packages:

- **Timing.** A fixed `sleep` either wastes minutes or fails while BGP is still converging. Netdryrun polls until each check passes twice in a row, and runs "must never happen" checks only after convergence, for a hold window.
- **Routes that hide.** A leaked route that was received but not selected doesn't show in the main routing table output on every network OS. Netdryrun's drivers read where each one keeps it (FRR, SR Linux, SONiC, cEOS).
- **Evidence.** One verdict, an exit code, JUnit, a PR comment, and a JSON file with every command and its raw output, instead of a log to read.
- **Scenarios and agents.** Link-down and node-isolation scenarios with recovery checks, and an MCP server so an AI agent can run the same checks.

The two mix well: keep a script for anything Netdryrun doesn't check, and call `netdryrun check` from it for the rest.

## Netdryrun

Netdryrun adds a test layer on top of a containerlab lab:

- positive checks wait for convergence and must pass twice in a row
- negative checks (absent routes, failing pings, prefix upper bounds) run only after convergence and must hold
- a route that was received but not selected counts as present
- every run produces one pass/fail result, a CI-friendly exit code, and a JSON evidence file


It is early (version 0.3.1). Drivers exist for FRR, Nokia SR Linux, SONiC and Arista EOS (bring your own cEOS image), and checks cover BGP sessions, prefix counts, routes, BGP best-path attributes and ping, with link-down, node-isolation and route-injection (FRR only) failure scenarios.

It does not do static analysis, build labs for you, or test production devices.

## How they combine

A reasonable pipeline uses more than one:

1. **Batfish** on every commit for fast, broad config analysis.
2. A **containerlab** topology that mirrors the change.
3. **Netdryrun** in CI to boot that lab, wait for convergence, and gate the merge on runtime behavior.
4. **pyATS / Genie** (or similar) for pre- and post-change checks on the production devices during the change window.

None of these steps proves the change is safe on its own. Each one removes a different class of mistakes.

[Batfish, then Netdryrun](batfish.md) shows steps 1 and 3 together on a small FRR network, with measured times. In that test, Batfish caught two of three bad changes in seconds, before any lab booted; the third depended on an FRR default that only the running routers showed.


---
Source: https://netdryrun.com/trust/

# Trust and security

## License

Netdryrun™ is open source under the [Apache License 2.0](https://github.com/netdryrun/netdryrun/blob/main/LICENSE). The source is at [github.com/netdryrun/netdryrun](https://github.com/netdryrun/netdryrun).

## How releases are published

- Releases are built and published by a GitHub Actions workflow when a version tag (`v*`) is pushed. The workflow checks that the tag matches the package version before building.
- Packages are uploaded to [PyPI](https://pypi.org/project/netdryrun/) with **Trusted Publishing** (OpenID Connect). No PyPI token or password is stored in the repository or its secrets; PyPI accepts the upload because it comes from that workflow in that repository.
- The same workflow creates a GitHub release with the built files attached.
- The GitHub Action (`netdryrun/netdryrun@v0.3.1`) installs Netdryrun from the action's own source at the tag you reference. Pin a tag or a commit SHA.

## Reporting a security issue

Email **[security@netdryrun.com](mailto:security@netdryrun.com)**. Please do not open a public issue for a vulnerability. Include the version, what you found, and how to reproduce it.

## What a lab cannot prove

A Netdryrun pass means the change behaved correctly in a lab. The lab runs real routing software, so a pass is strong evidence for protocol logic and policy intent: sessions come up, the intended prefixes are accepted, routes land in the routing table, traffic gets through, and unwanted routes stay out. It does not prove:

- **Vendor-specific behavior.** Open-source and container routers (FRR, SR Linux, SONiC VS) are not your vendor's routers, and even Arista cEOS is not the same as EOS on hardware. Defaults, policy evaluation and bugs differ between implementations and versions. For Arista you can bring your own licensed cEOS image.
- **Scale.** A lab has a handful of nodes and small tables, not full Internet tables or hundreds of peers.
- **Hardware and ASIC behavior.** Containers have no forwarding hardware, so TCAM limits, hardware programming and line-rate effects are not tested.
- **Timing at scale.** Convergence time in a small lab says little about convergence time in a large production network.


Version 0.3.1 also covers only BGP (IPv4/IPv6 unicast), routes, BGP best-path attributes and ping, plus link-down, node-isolation and route-injection (FRR only) failure scenarios. OSPF/IS-IS adjacencies and path checks are not covered yet.


## Running untrusted labs

containerlab runs privileged containers, so a topology and its configs are code that runs with root on the host. Only run labs you trust. In CI, see the [GitHub Action security notes](github-action.md#security-notes). For AI agents, see the [MCP safety model](ai-agents.md#safety-model).

What follows from that, by design:

- **`netdryrun.yml` is code too.** `nodes.<node>.setup` commands are shell commands run inside the node, and a `netdryrun.yml` can point at a topology in any folder. Review a `netdryrun.yml` the way you review a topology.
- **Everything else in `netdryrun.yml` is data.** From 0.3.1, VRF and interface names are restricted to letters, digits and a few punctuation marks before they reach a device CLI, and addresses and prefixes must parse as IP. A check can't run a device command it doesn't name.
- **`as_path_regex` runs with no time limit.** A pathological pattern can stall a run until your CI job's timeout; it can't do anything else. Set `timeout-minutes` on the job.
- **Text from a lab is treated as untrusted** wherever it ends up (0.3.1 and later): escaped in PR comments and step summaries, kept to one comment line in a recorded baseline, and flattened and capped in MCP results.

## Privacy

**The tool has no telemetry.** The CLI, the GitHub Action and the MCP server do not phone home or send usage data anywhere. Reports are written only to the files you ask for (and to the GitHub Actions step summary when running in Actions). containerlab and Docker may pull images from registries named in your topology, as they normally would.

The GitHub Action has a `cloud` input reserved for a future hosted service, Netdryrun Cloud. **Netdryrun Cloud is not available yet**: its address doesn't exist, so setting `cloud: true` today uploads nothing and only adds an "evidence upload failed" warning. If it launches, uploading will stay opt-in, and its privacy terms will be published first. Leave `cloud` off.

**No AI inside the tool.** The CLI, the GitHub Action and the MCP server contain no AI model and call no AI service; verdicts come from checks run against your lab. When an AI agent uses the MCP server, the agent sends whatever it chooses to the model provider *you* picked; Netdryrun is not part of that path.

**AI in how we build it.** Development is done with Anthropic's Claude. Releases 0.1.0 and 0.2.0 were also reviewed by OpenAI and xAI models ([how it's built](how-its-built.md)). If you are a [design partner](design-partners.md), the sanitized configs you send us are processed with Anthropic's Claude to build your lab, under terms that don't allow training on them, and with no other AI service. They are deleted within 30 days after delivery unless you ask us to keep them. There are no paid products yet. See the [privacy notice](privacy.md#configs-you-send-us).

**This website** is static documentation hosted on GitHub Pages. It sets no cookies, has no analytics and no forms, and serves its fonts itself, so your browser contacts no third party. GitHub, as the host, receives your IP address and request details to serve the pages.

## Trademarks

"Netdryrun" and the Netdryrun logos are trademarks of the Netdryrun project. The Apache-2.0 license covers the code, not the name: forks are welcome under a different name. See the [trademark policy](https://github.com/netdryrun/netdryrun/blob/main/TRADEMARKS.md).


---
Source: https://netdryrun.com/support/

# Support and versioning policy

## Support

Netdryrun is free open-source software under Apache-2.0, provided as is. Support for free use is best effort through [GitHub issues](https://github.com/netdryrun/netdryrun/issues). Security reports get priority (see [Contact](contact.md)). There is no uptime or response-time guarantee for free use.

Only the latest release gets fixes. Upgrading is the fix for bugs in older releases.

## Version numbers

Netdryrun uses [semantic versioning](https://semver.org). Before 1.0, a minor release (0.2 to 0.3) may contain breaking changes; patch releases (0.2.0 to 0.2.1) never do. Every change is in the [changelog](https://github.com/netdryrun/netdryrun/blob/main/CHANGELOG.md).

## What counts as a breaking change

These are the interfaces other tools and agents rely on:

| Interface | Stable contract |
|---|---|
| CLI | command names, flags, and exit codes (`0` passed, `1` failed, `2` error, `3` inconclusive) |
| `netdryrun.yml` | check types and keys; a file that validated keeps validating |
| JSON report | the `schema` field (`netdryrun.report/v1`); fields are only added within a schema version, never removed or renamed |
| GitHub Action | input and output names and their meaning; pin a tag or a commit SHA |
| MCP server | tool names, their arguments, and the `status` and `verdict` fields |

Removing or renaming any of these, or changing their meaning, is a breaking change. Adding is not: a new check type, a new report field, or a new `status` value (`inconclusive` was added after 0.2.0). Treat any status you don't know as not passed.

## Deprecation

Before something is removed, it keeps working for at least one minor release with a warning that names the replacement, and the changelog says so. After 1.0, removals wait for the next major version.


---
Source: https://netdryrun.com/design-partners/

# Design partners

Netdryrun is young. We'd rather learn from a few real changes than guess. If you have a routing change coming up, we'll help you test it in a lab, for free, in exchange for honest feedback.

## What you get

- A runnable containerlab lab of the relevant part of your network, built with you from your sanitized configs.
- A `netdryrun.yml` with checks for what your change must do and what must never happen (leaks, lost reachability).
- The verdict with evidence, before your change goes anywhere real. You keep everything.
- Help wiring it into your CI, if you want it there.

## What we ask

- One real upcoming change, and sanitized configs for the routers involved: replace public addresses and AS numbers with documentation ranges and remove secrets. We'll help you check.
- Honest feedback: what was useful, what got in the way, how you test changes today.
- Optional: permission to publish an anonymized write-up. Nothing is published without your written OK.

## Fair warning

- A lab is not production. A pass covers the checks in the lab, on the network OSes we support ([FRR, Nokia SR Linux, SONiC, Arista EOS](reference/config.md#drivers)). See [what a lab cannot prove](trust.md#what-a-lab-cannot-prove).
- We never touch your production network and never need access to it.
- This is a small independent project, so we take a few partners at a time.

## How your configs are handled

You send sanitized configs only. They're used for your lab and nothing else and kept private. We build labs with the help of Anthropic's Claude, so your configs are processed by it, under terms that don't allow training on them; no other AI service sees them. They're deleted within 30 days after delivery unless you ask us to keep them. An NDA is available on request. See the [privacy notice](privacy.md#configs-you-send-us).

## Apply

Run `netdryrun feedback` and tick "Design partner", or email [hello@netdryrun.com](mailto:hello@netdryrun.com) with one line about the change you want to test.


---
Source: https://netdryrun.com/contact/

# Contact

| What | Where | Expect an answer |
|---|---|---|
| Feedback after trying it (2 minutes) | run `netdryrun feedback`, or the [feedback form](https://github.com/netdryrun/netdryrun/issues/new?template=feedback.yml) | read by a human |
| Free help testing one real change | [design partners](design-partners.md) | within a few days |
| Bugs, questions, feature requests | [GitHub issues](https://github.com/netdryrun/netdryrun/issues) | best effort, usually within a few days |
| Security vulnerabilities (please don't open a public issue) | [security@netdryrun.com](mailto:security@netdryrun.com) or [GitHub private vulnerability reporting](https://github.com/netdryrun/netdryrun/security/advisories/new) | acknowledgment within 3 days |
| Everything else: trademark permission, paid work, press | [hello@netdryrun.com](mailto:hello@netdryrun.com) | best effort, usually within a few days |

Netdryrun is a small, independent open-source project. There is no phone line and no sales team. Free use comes with best-effort support; see the [support and versioning policy](support.md).

Security researchers: our [security.txt](https://netdryrun.com/.well-known/security.txt) follows RFC 9116, and the [security policy](https://github.com/netdryrun/netdryrun/blob/main/SECURITY.md) explains how reports are handled.


---
Source: https://netdryrun.com/privacy/

# Privacy notice

*Last updated: 27 October 2026*

## Who is responsible

Netdryrun is operated by Victor Khen, Taiwan ("we"). Contact for anything about your data: [hello@netdryrun.com](mailto:hello@netdryrun.com).

## The short version

- **The Netdryrun tool** (CLI, GitHub Action, MCP server) has no telemetry. It sends us nothing. The GitHub Action has a `cloud` input reserved for Netdryrun Cloud, a hosted service that is not available yet; setting it today uploads nothing. Its own privacy terms will be published here before it launches.
- **This website** sets no cookies, has no analytics and no forms, and serves its fonts itself.
- **We see your data only if you email us, interact with the project on GitHub, or send us configs as a design partner.**

## This website

netdryrun.com is static documentation hosted on GitHub Pages. To deliver the pages, GitHub processes your IP address and request details (page, time, browser) under the [GitHub privacy statement](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement). We do not receive these logs. If you switch between light and dark mode, your browser remembers the choice in its local storage; that stays on your device. Search runs entirely in your browser.

## Email

When you write to an @netdryrun.com address, Cloudflare Email Routing forwards the message to our mailbox. We use your address and message only to answer you and keep the conversation for as long as it's useful, then delete it. Security reports may be kept as records of how the issue was handled. Lawful basis: our legitimate interest in answering you.

## Configs you send us

If you are a [design partner](design-partners.md), you send us sanitized configs so we can build a lab of part of your network. We use them only for your lab. We build labs with the help of Anthropic's Claude, so Anthropic processes the configs on our behalf, under commercial terms that don't allow training on them; no other AI service receives them. We delete them within 30 days after delivery unless you ask us to keep them. Lawful basis: your request (the work you asked us to do).

## GitHub and PyPI

Issues, pull requests and discussions on [github.com/netdryrun](https://github.com/netdryrun) are public and governed by GitHub's terms and privacy statement. Downloads from PyPI are handled by the Python Software Foundation under the [PyPI privacy notice](https://policies.python.org/pypi.org/Privacy-Notice/). We don't combine this information with anything else.

## Transfers

GitHub, Cloudflare and Anthropic are based in the United States. Transfers of personal data from the EU or UK rely on the EU-US Data Privacy Framework (and its UK extension) where the company is certified, and on the European Commission's standard contractual clauses otherwise.

## Your rights

You can ask for access to, correction of, or deletion of your personal data, a copy of it, restriction of processing, or object to processing based on legitimate interest. Email [hello@netdryrun.com](mailto:hello@netdryrun.com); we answer within 30 days. You can also complain to your data protection authority.

## Changes

We update this notice when what we do with data changes, for example before Netdryrun Cloud or paid products launch, and change the date at the top.
