Netdryrun

Test network changes before they touch production.

Netdryrun is an open-source (Apache-2.0) tool that dry-runs network changes in a real containerlab lab and returns a pass/fail verdict with evidence. It runs as a CLI, a GitHub Action, and an MCP server for AI agents.

Software teams don't ship code without running its tests. Network changes deserve the same step: run the change in a real lab, check how the network behaves, and ship only on a pass. Netdryrun makes that one command, one CI step, or one tool call for an AI agent.

Already have a containerlab lab? [Add Netdryrun to it in 10 minutes](https://netdryrun.com/guides/your-lab/): record its steady state, add one guard, run it on every pull request.

Netdryrun™ boots your topology as a real virtual network (containerlab), applies your configs, and checks how the network actually *behaves*: BGP sessions, prefix counts, routes, reachability. It catches the mistakes your checks describe, such as a route leak, before the change reaches production, and leaves the commands and raw output for a reviewer to inspect.

$ 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)

That run caught a leaked default route that was *received but not selected*. Ping and session checks alone would miss this example: every session is up and every address answers. (A static analyzer such as Batfish also catches this particular leak; the Batfish page shows one that it misses and a lab catches.)

Status: v0.4.0. Runs on Linux and WSL2, with drivers for FRR, Nokia SR Linux, SONiC (docker-sonic-vs), Arista EOS (cEOS, bring your own image) and Juniper cJunosEvolved (beta, bring your own image). On the verdict corpus 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 16 of 17 deterministic cases correct, ping-only 9/17, all-sessions-up 7/17; case 18 is nondeterministic in this lab and excluded from the score (listed with its reruns). Expected verdicts were committed before any run, on one FRR topology: a comparison of testing methods, not a production reliability estimate. Method, every miss and a one-command rerun are on the corpus page. Provenance: both ran on Netdryrun 0.3.1.

Why

• It tests behavior, not syntax. A config diff shows what changed, not whether BGP comes up or which routes each router ends up with. A real control plane shows what the routing software actually does.
• It's built for CI. One GitHub Action, a pass/fail exit code, a Markdown summary in the job, JUnit XML, and a JSON evidence file with every command and raw output.
• It waits for convergence, with stated rules. A positive check passes after 2 passing samples taken 3 s apart, within its timeout. Negative checks ("this route must be absent") and best-path attribute checks wait until every configured BGP session on their node is up with stable prefix counts (sessions a check expects down don't count), then a 10 s settle, then must hold for 10 s (settle and hold are configurable). If a node still reports no BGP neighbors at the timeout, its checks run anyway and the result says BGP convergence was not seen. In a failure scenario, checks start only once the fault is visible in BGP (or the run ends with exit 2), and positive checks must hold too. Exit 0 passed, 1 checks failed, 2 not tested (config or lab problem), 3 inconclusive. The rules are sample-based; see convergence semantics.

Quick start

Try it in your browser (no install)

The codespace comes with Docker, containerlab and Netdryrun already installed. When the terminal shows Ready, run:

bash examples/agent-demo/demo.sh

A route-leaking change is rejected, then the fix passes every check. It uses your GitHub account's free Codespaces hours (2-core machine). Details.

On your own machine

Requirements: Linux or WSL2, Docker, containerlab, Python 3.10+. 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.

pipx install netdryrun

git clone https://github.com/netdryrun/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

On your own containerlab topology (3 commands)

netdryrun record my-lab/topology.clab.yml --deploy   # snapshot today's behavior into my-lab/netdryrun.yml

...edit your configs (the change you want to test)...

netdryrun run my-lab # re-run the checks in my-lab/netdryrun.yml

record writes checks for every established BGP session, a prefix-count range for each (today's count up to 20% more, at least 2), guards against a default route or a link subnet arriving via BGP, and up to 50 BGP routes per node. A session that is down today isn't recorded.

Advisory (0.3.3 and 0.4.0): that range lets a leak of one or two extra prefixes from a neighbor pass. Until 0.4.1, record with --exact-prefixes and add present: false checks for prefixes that must never arrive. Advisory. Review it (remove what is allowed to change, add negative checks such as present: false), commit it, and every future change runs against it, locally or in CI. A pass means those checks passed, nothing more.

netdryrun.yml

lab: topology.clab.yml      # your containerlab topology

timeout: 90 # seconds a positive check may wait for convergence

checks:

• type: bgp_session # session reaches a state (default: established) node: r1 neighbor: 10.0.12.2
• type: bgp_prefixes # accepted prefix count within a range node: r1 neighbor: 10.0.12.2 min: 1 max: 10
• type: route # route present (or absent), optionally via a protocol node: r1 prefix: 192.168.3.0/24 protocol: bgp
• type: ping # reachability, optionally from a source address node: r1 source: 192.168.1.1 target: 192.168.3.1
• type: route # negative check: must stay absent after convergence node: r1 prefix: 0.0.0.0/0 protocol: bgp present: false

Failure scenarios break something, check the network still behaves, then restore it. They can take links down, or (from 0.3.1) make an FRR neighbor announce routes it shouldn't, to prove a max-prefix limit or an import filter actually holds:

scenarios:

• name: r1-r2 link fails link_down: {node: r1, interface: eth1} checks:
• {type: ping, node: r1, source: 192.168.1.1, target: 192.168.2.1} # rerouted via r3
• {type: bgp_session, node: r1, neighbor: 10.0.12.2, state: down}
• name: customer floods 200 prefixes inject_routes: {node: ce1, count: 200, from: 10.100.16.0/24} checks:
• {type: bgp_prefixes, node: up1, neighbor: 10.0.2.1, max: 51} # the limit stops the flood

Every check also accepts name, timeout and vrf. Ping accepts expect: failure and count. Drivers are detected from the topology; override them with nodes: {r1: {driver: frr}}. Nodes that are configured after boot (SONiC) take setup commands: nodes: {sonic1: {setup: [...]}}.

Commands

Reports: --json FILE (full evidence), --markdown FILE, --junit FILE. Under GitHub Actions, a summary is appended to the job page automatically. Exit codes: 0 passed, 1 a check failed, 2 no verdict (config or lab error, a fault that did not take effect, or an internal error; add --debug for the traceback), 3 inconclusive (the lab never reached a testable state, so the run says nothing about the change), 130/143/129 interrupted by SIGINT/SIGTERM/SIGHUP after cleaning up the lab.

GitHub Action

name: Network dry run

on: pull_request jobs: dryrun: runs-on: ubuntu-latest steps:

• uses: actions/checkout@v4
• uses: netdryrun/Netdryrun@v0.4.0 with: path: network/ # folder containing netdryrun.yml

The action installs containerlab, runs the checks, uploads the JSON and JUnit reports as an artifact, and fails the job if any check fails. Outputs: status, passed, failed, inconclusive-reason.

For AI agents (MCP)

Listed in the official MCP Registry (io.github.netdryrun/netdryrun) and on Glama; the agent skill is also on Smithery.

AI can propose network changes. Netdryrun verifies the outcome. Agents: read [AG