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.1. Runs on Linux and WSL2, with drivers for FRR, Nokia SR Linux, SONiC (docker-sonic-vs), Arista EOS (cEOS, bring your own image), Juniper cJunosEvolved (beta, bring your own image), Cisco NX-OS (Nexus 9000v, beta, bring your own image) and MikroTik RouterOS 7 (CHR, 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 9 of 17 deterministic cases correct (8 inconclusive, reported as not proven; 0 harmful changes approved), ping-only 8/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.4.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 a fresh Ubuntu: sudo apt install docker.io curl git, then sudo usermod -aG docker $USER and log in again (containerlab's installer needs curl and fails quietly without it). The times in these docs were measured with containerlab 0.81.1; its installer gives you the latest. 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 netdryrun run examples/frr-customer-leak # a customer filter lets a foreign prefix in, 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, its prefix count as a range (today's count up to 20% more) and up to 50 BGP routes per node, plus two guards per BGP node: no default route and no link subnet via BGP. On FRR and SONiC each eBGP neighbor's check also lists the prefixes it sends today (only), so a new prefix from it fails even within the range; on the other drivers the count is recorded exactly instead. 0.3.3 and 0.4.0 wrote the range without that list, and a leaked customer prefix passed (advisory): re-record a baseline made with them. A session that is down today isn't recorded. 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. What record doesn't cover: reachability (a route that stays active via BGP but forwards nowhere passes; in our corpus, removing next-hop-self cut the customer off from the peer and the recorded baseline passed, so add ping checks between the networks that must reach each other), and safety limits that change nothing today (a removed maximum-prefix or import filter passes until a neighbor misbehaves: write a failure scenario where that neighbor announces extra routes with inject_routes, and check the prefixes stay out with bgp_prefixes max or present: false).

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 p