Hammerhead docs

What you need to judge Hammerhead before you talk to us: how it installs, a five-minute run, all 76 commands, the Python SDK, the REST API and CI. The output on this page is real, from hammerhead 0.1.0 on the labs that ship with it.

Hammerhead 0.1.0 · page updated September 2026

Access

Hammerhead is private. There is no public download, package, container or self-serve trial. We send binaries to teams we have given access. These docs are public so you can decide whether it is worth asking.

Install

Hammerhead is one executable, hammerhead. It needs no JVM, Python runtime, database or server. Each release archive also carries hammerhead-api, the optional REST server.

Analysis of a directory of config files works the same on every platform. The last column only matters if you want Hammerhead to fetch configs itself (see how configs get in). A linux/amd64 container image is also available to teams with access.

# after download: check, unpack, run
shasum -a 256 -c hammerhead-<version>-x86_64-unknown-linux-gnu.tar.gz.sha256
tar xzf hammerhead-<version>-x86_64-unknown-linux-gnu.tar.gz
./hammerhead --version
hammerhead 0.1.0

Quickstart

Five steps. The first four use a three-router OSPF lab that the binary can write for you; the fifth checks a change on a four-router spine-leaf.

1. Point it at a config directory

init scans a directory of configs (one file per device), says what it found and suggests next commands. --example seeds the lab first.

$ hammerhead init ./configs --example
  ✓  Seeded ./configs with R1/R2/R3 OSPF triangle (2196 bytes)
  ✓  Found 3 config files (3 cisco_ios)
  ✓  Discovered 3 devices, 9 interfaces, 3 L3 links
  ✓  Simulated 18 FIB entries across all devices
  ✓  Protocols: OSPF (area 0)
  ✓  Completed in 3ms

On your own configs, read the vendor counts init prints. A file it cannot identify is parsed as Cisco IOS, so a surprising count usually means a file it did not recognize.

2. Build the model

$ hammerhead simulate ./configs
== R1 ==
RIB: 6 entries (3 connected, 0 static, 3 ospf, 0 bgp, 0 eigrp, 0 isis)
FIB: 6 entries
OSPF: 2 adjacencies, 3 LSAs across area(s) 0
… R2 and R3 follow

3. Ask a reachability question

$ hammerhead reachability ./configs --from R1 --src 1.1.1.1 --dst 3.3.3.3
Reachable: yes

4. Trace the packet

$ hammerhead traceroute ./configs --from R1 --src 1.1.1.1 --dst 3.3.3.3
Traceroute from R1 (1.1.1.1) to 3.3.3.3 [tcp dst-port 80]
  1  R1         - -> GigabitEthernet0/1 (R3 GigabitEthernet0/0)   forwarded
Disposition: Delivered

5. Check a change before you push it

preflight compares a before and an after directory. Here the candidate moves LEAF-2 into OSPF area 2. Output trimmed.

$ hammerhead preflight ./before ./after
  routes changed:   15 (20.0% of FIB entries)
  devices impacted: 4 (100.0% of estate) — LEAF-1, LEAF-2, SPINE-1, SPINE-2
  flows lost:       6 (of 4 of 4 endpoint(s) probed, 0 gained)
    probed per pair:  tcp/80 http, tcp/22 ssh, tcp/179 bgp, udp/53 dns, icmp echo
    ✗ LEAF-1(10.255.1.1) → LEAF-2(10.255.1.2)
    …
VERDICT: FAIL
  ✗ blast radius 100.0% of devices exceeds --max-blast-radius 5%
  ✗ routing adjacencies: 2 lost between devices that are both still present — OSPF LEAF-2 <-> SPINE-1, OSPF LEAF-2 <-> SPINE-2
  ✗ reachability regression: 6 endpoint pair(s) delivered before are not delivered after
$ echo $?
2

A candidate that changes no routes and loses no flows returns VERDICT: PASS and exit 0. The exit code is the contract CI relies on:

CLI reference

All 76 subcommands, grouped by job. Each summary is the command's own --help text, with internal references removed. hammerhead help <command> prints every flag.

Global options: --format text|json|csv|dot (JSON is stable for scripting; CSV suits tabular output such as fib, rib, reachability; DOT suits traceroute) and -v/-vv/-vvv for logging.

Python SDK

The hammerhead Python package (Python 3.9+, uses pandas) comes with access as a source distribution. It is not on PyPI.

pip install ./hammerhead-python

The SDK drives the hammerhead binary and reads its JSON output, so a notebook and the CLI always give the same answer. It finds the binary on your PATH, or you pass Hammerhead(binary="/path/to/hammerhead").

from hammerhead import Hammerhead

hh = Hammerhead().load_snapshot("configs/")
hh.reachability("R1", "1.1.1.1", "3.3.3.3")   # True
hh.traceroute("R1", "1.1.1.1", "3.3.3.3")     # TracerouteResult: Delivered, 1 hop
hh.routes(device="R1")                         # DataFrame: device, prefix, protocol, next_hop_ip, egress_interface

Methods: load_snapshot, simulate, routes, traceroute, reachability, diff, diff_routes, loops, failure_analysis, spof_scan, policy_check, nqe_routes, nqe_devices, nqe_paths, acl_audit.

Jupyter tutorials

Nine notebooks come with the SDK: Getting started · Pandas essentials for network analysis · Route analysis · BGP analysis · Traceroute and reachability · Change validation · Detecting configuration drift · ACL and firewall analysis · SDK cookbook.

REST API

hammerhead-api serves the same engine over HTTP. It binds to 127.0.0.1:8080 by default and will not start until you name the config directories it may read (HAMMERHEAD_API_ALLOWED_ROOTS). Request bodies are capped at 2 MB.

Authentication

Protected routes take a bearer JWT from your identity provider. Configure the issuer and audience (HAMMERHEAD_AUTH_JWT_ISSUER, HAMMERHEAD_AUTH_JWT_AUDIENCE) and exactly one key source: an HS256 secret, an RS256 public key file, or a JWKS URL. Tokens map to three roles, viewer < operator < admin. With no JWT settings, every protected route returns 401. There is no OIDC discovery and no native SAML or SCIM; use an identity bridge such as Keycloak or Auth0 for those.

Routes

56 routes. Analysis routes are rate-limited.

The UI routes serve the built-in operator console. The streaming routes check a single-use ticket (from POST /stream/ticket) or a bearer token themselves.

CI integration

Hammerhead gates a pipeline through exit codes, so it works in any CI that can run a binary. Keep the base branch's configs in one directory and the proposed ones in another, run preflight, and let a non-zero exit fail the job.

# any CI: fail the job unless the change passes
git worktree add ../base "$BASE_SHA"
hammerhead preflight ../base/configs ./configs --format json > preflight.json

# optional: your own rules, YAML; --strict exits 2 on a high or critical failure
hammerhead policy-check --config-dir ./configs --policies network-policy.yaml --strict

Teams with access also get:

• GitHub Action. A composite action that runs preflight on a pull request and posts the verdict as a comment. Inputs include config-dir, base-config-dir, max-blast-radius (default 5%) and policy; outputs include gate-verdict, gate-exit-code, gate-blockers, changed-routes and lost-flow-count. It needs a token that can read the private release.
• GitLab CI template. Fails the pipeline unless the verdict is exactly pass, and can post the result to a ServiceNow change record.
• Ansible. A role for pre_tasks gating, and an Event-Driven Ansible source.

We have no Jenkins example yet; the plain-CLI pattern above works there.

Environment

Questions these docs don't answer: ask us, and we will add the answer here.

How we rebuilt 134 outages, and what "flagged" means

We say Hammerhead flags the cause of 134 outages rebuilt from the public record. This page says how the rebuilds were made, what counts as a flag, and what the number does not show.

Methodology · September 2026

The claim, exactly

We rebuilt 134 network outages from public reports. For each, we ran the change behind it through Hammerhead. Every one ends in a failing verdict or an audit finding whose stated reason is the cause the public record gives, some only once you declare facts about your network, as described below.

Three things the claim is not:

• It is not the operators' configurations. None of them is public. Every rebuild is our reconstruction.
• It is not a claim that Hammerhead would have prevented any of these outages.
• It is not a blind test. See what it doesn't show.

Which outages

Four literature searches produced 314 incidents. We sorted each by whether its cause lives where Hammerhead looks, in device configuration or a command run against it: 73 were in scope, 88 partly in scope and 153 out of scope. Of the 161 in or partly in scope, we rebuilt 134 and excluded 27, each exclusion with a written reason.

Each incident carries a search-confidence grade for how well its public record supports the facts we used. For the 134: 72 high, 56 medium, 6 low. Not every entry has been re-checked against its sources since it was first catalogued.

How we rebuild one

1. Facts. A write-up of the public record, quoted and cited, with our own choices kept apart under a separate heading of assumptions. 125 of the 134 list their sources in the catalog; the other 9, built by hand, cite them in their own write-ups.
2. The smallest network with the same failure. Usually a before and an after directory of configs, often with a control case beside it. Topology and syntax are ours. Where many incidents share a mechanism, such as route leaks, the networks are generated from a template for that family.
3. The change. The difference between before and after. One exception: Microsoft's 2023 WAN outage was caused by a command, not a config line, so that rebuild feeds Hammerhead the command. Microsoft never named the vendor or the command, so we assumed both.

No outside party has checked that our rebuilds match the public reports. The full catalog, with each incident's sources and assumptions, is available to evaluators on request.

What "flagged the cause" means

A flag is a failing result where the check that fired names the reason the network actually broke. A failure for some other reason does not count. Automated tests pin both the verdict and the text of the reason for every one of the 134, and they run on every change to Hammerhead, on Linux and macOS.

Four kinds of run count:

Details that matter:

• 30 of the 134 are flagged by auditing the configuration, not by a verdict on a change. These are the accepting-network (18), layer-2 (8) and redundancy (4) families.
• The size gate never counts. Every replay runs with the blast-radius gate turned off (--max-blast-radius 100). On a four-router lab almost any change exceeds the default 5% of devices, which would "catch" everything for the wrong reason.
• Some catches need facts you supply. Several families are caught only once you declare your network boundary, your ROAs or your link capacities. Of 28 route mis-originations, 17 pass with a caveat when checked from the originating router with nothing declared. Microsoft 2023 is caught only when the command is listed; the same command on Cisco IOS returns unknown.

What the number doesn't show

The 134 were caught after fixes. On the first run, many verdicts were pass. We changed Hammerhead until each was caught, and every fix started as a failing test. The 134 are a regression suite we built the tool against, not a sample it had never seen. They show Hammerhead can represent and flag these failure modes. They do not estimate how often it would catch the next outage.

Some causes sit partly outside any configuration, and the public record says so:

• Facebook, 2021. The withdrawal of the DNS servers' routes came from software reacting to a health check. It is in no config.
• CenturyLink, 2020. The Flowspec rule was injected over BGP by a DDoS-mitigation system, not written into a device config.
• Microsoft WAN, 2023. Vendor and command assumed, as above. The timing of the resulting storm is not modeled.
• AS 7007, 1997. We rebuilt the mechanism usually taught, which has not been confirmed.
• OVH, 2021. The mechanism is our assumption.

False positives on healthy configs

We have not measured a false-positive rate. We have no measurement of how often Hammerhead fails a healthy change, and we won't quote one until we do.

What exists instead:

• The replay tests pin 52 passing results, 46 of them from preflight. Among them are 11 intended changes that keep required flows, 4 healthy redundancy variants and 3 RPKI controls. Others are known misses, such as the 17 mis-originations above, not controls. We wrote all of them alongside the replays, so they are expectations, not a sample of real changes.
• Known false failures, written down and not yet fixed: a description-only edit on a BGP neighbor still fails a gate, and the default blast-radius gate trips on almost any change to a small network.

Until we have measured it on real change histories, treat the rate at which Hammerhead fails a healthy change as unknown.

The 134, by family

The accepting-network, layer-2 and redundancy families are flagged by auditing the configuration. The rest are flagged by preflight, rpki-audit or drift on the change.

Our other numbers

135 of 136 routes match real routers

A lab of 10 routers running FRR 10.7.1 in containers, with the image pinned. We wait until every adjacency is up and every routing table has been unchanged for 60 seconds, then compare 136 route entries with Hammerhead's: every prefix matches, and 135 of 136 next hops. The lab is re-run every week and compared against the committed result; it does not gate merges. It is one topology on one routing stack, not production hardware, and not the other vendors we parse.

Checked against Batfish across 351 test snapshots

351 snapshots (2,040 devices) drawn from our test corpora, demos and generated topologies, not customer networks. Batfish and Hammerhead agree on 94.41% of prefixes and 99.80% of egress interfaces, for IPv4 in the default VRF. It is a comparison with another model, not with routers, and it runs weekly as a report. We quote no speed comparison with Batfish.

Questions about any of this, or want to run a replay yourself? Request access and ask for the catalog.

Checking network changes before they ship

A short white paper on what Hammerhead does, why it works from configuration rather than probes, how we measure it, and where it stops.

Optimesh Technologies · version 1 · September 2026 · about 8 minutes

1. The problem

A network change ships as a diff a colleague has read. The test is production. When the diff is wrong, the outage follows a familiar shape: Facebook in 2021, when a maintenance command withdrew the routes to its DNS servers, and Rogers in 2022, when a change that removed a routing filter took a national network down for most of a day. Different companies and equipment; the same pattern of a change that looked fine in review.

Most of the cost of such a night is not the fix, which is often one line. It is finding that line across a fabric, hop by hop, under pressure. And the rate of change is rising as automation, and now AI agents, propose changes faster than people can read them.

2. Why testing the live network misses it

A probe proves a path exists. Nothing you can send proves a path is absent. To show that a guest network can never reach a payment database, you would have to try every source, destination, port and protocol, a space far too large to sample. Monitoring checks the flows you thought of; the leak lives in the one you didn't.

The configuration already holds the answer. Configs, topology and routing protocols determine each device's forwarding table. Rebuild those tables faithfully and you can answer reachability for every packet from the model, before the change is applied, with no traffic sent. This is the line of work that runs from header space analysis through Veriflow and Batfish.

3. The approach

Hammerhead is a single binary that reads a directory of device configs, discovers the topology, runs the routing protocols to convergence and builds every device's forwarding table. Queries run against that model: reachability, traceroute, every ECMP path, ACL and NAT behavior, and a before-and-after comparison of two config sets.

• Deterministic. The same inputs give the same answer and the same evidence every run.
• Offline. It needs only the config files. It runs on your hardware and sends nothing out.
• Fast enough for every change. On a 976-device synthetic enterprise network, building the full model takes about 0.6 seconds on our benchmark machine, which is what lets it sit in a pull request instead of a quarterly audit.

A language model can write the change; Hammerhead doesn't trust it. The check that decides is deterministic and never sees the model's confidence, so an AI-proposed change is held to the same test as a human one.

4. Four verdicts, and a list of what wasn't checked

The preflight check compares the network before and after a change and returns one of four verdicts: pass, advisory (findings to read, nothing failed), fail (with the lost flows, routes, adjacencies or rules named) or unknown. Unknown matters most. When a change touches something the model does not cover, Hammerhead says so and names it, rather than reporting a pass it cannot back. Each verdict carries a ledger of what was and was not measured.

5. How we measure it

• Against real routers. In a 10-router FRR lab, Hammerhead's routes agree with the routers' on every prefix and on 135 of 136 next hops. The lab re-runs weekly.
• Against Batfish. Across 351 test snapshots (2,040 devices), the two agree on 94.41% of prefixes and 99.80% of egress interfaces, for IPv4 in the default VRF. This compares two models, not a model with routers.
• Against the public record. We rebuilt 134 outages from public reports, and Hammerhead flags the cause of each. These were caught after we fixed the tool to catch them, so they are a regression suite, not a blind test, and we have not yet measured how often Hammerhead fails a healthy change. The methodology has the details.

6. Where it fits

• In CI. Run preflight on every pull request that touches config. A non-zero exit stops the merge.
• In the change ticket. The verdict and its reasons travel with the change, so the approver decides on evidence.
• In front of automation. Ansible and AI agents propose; the gate decides before anything reaches a device.

7. Limits

Hammerhead models what the configs say, not what the network is doing right now. It reads 15 vendor formats, at different depths; some protocols and features are partial or not modeled, and the supported platforms table lists each. It has been checked against real routers in container labs only, not on production hardware. We have no public customer references yet.

Security

Where Hammerhead runs, what it touches, who can use it, what it records, and what it does not do yet. This page covers Hammerhead, RuleHawk and this website.

Last updated September 28, 2026

Where it runs

• On your machines. The hammerhead CLI and the optional hammerhead-api server run on hosts you control. Your configs stay there.
• Nothing phones home. There is no telemetry, license check or update check. Hammerhead makes a network call only when you turn on a feature that needs one: collecting configs over SSH or SNMP, pulling from a cloud API or your config manager, fetching your identity provider's signing keys, or sending webhooks you configured.
• Air-gap ready. Analysis needs only the config files. To install on an isolated network, copy the binary across.
• Private by default. The API server listens on 127.0.0.1 unless you bind it elsewhere, and reads only the config directories you allow.

Changes to your devices

Hammerhead reads configs. It never pushes configuration to a device and holds no device write credentials. SSH collection runs read commands such as show running-config.

When Hammerhead proposes a fix, it hands a gated change plus a rollback file to your own automation, as an Ansible bundle for your AWX or Ansible to run. A human approves by default. Rollback is a file you apply, not an automatic action.

SSO and roles

• The API server accepts bearer JWTs issued by your identity provider. You set the issuer, the audience and one key source: an HS256 secret, an RS256 public key, or a JWKS URL.
• Three roles, viewer, operator and admin, are enforced route by route (see the API docs). With no token settings, every protected route refuses access.
• Not built in: OIDC discovery, SAML and SCIM. Teams use an identity bridge such as Keycloak or Auth0 for those.
• The CLI has no roles. It runs as the operating-system user and reads what that user can read. Control it with OS and file permissions.

Audit trail

Set HAMMERHEAD_AUDIT_DIR and the API server keeps an append-only audit log:

• Every request that changes state, with who made it, what it asked for and the outcome, plus every denied request (401 and 403).
• Each entry carries the SHA-256 hash of the one before it. Editing or deleting an entry breaks the chain, and GET /audit/verify (admin) reports where.
• It never records authorization headers, query strings or request bodies. Each tenant gets its own chain.

Limits: a hash chain cannot show that the newest entries were cut off, so copy the latest hash somewhere you control. The trail covers work done through the Hammerhead server, not CLI runs on a laptop. It is off until you set the directory, except on multi-tenant servers, where it is required.

Compliance checks

Hammerhead ships rule packs that approximate these frameworks, checked offline against the model of your network with no AI model involved:

CIS (network devices, level 1) · PCI DSS (DMZ) · SOC 2 (change control) · HIPAA · ISO/IEC 27001 · NIST CSF 2.0 · DORA · NIS2

Each pack lists the controls it does not cover. They are checks labeled with control IDs, not certified mappings: passing one is evidence you can hand an auditor, not a certification. There are no DISA STIG or NERC CIP packs yet. You can write your own rules in the same YAML format with policy-check.

The software itself

• Hammerhead is written in Rust, and the compiler forbids unsafe code in the product. The only unsafe blocks are in test and benchmark tooling.
• Release archives come with SHA-256 checksums. They are not code-signed yet, and neither is the container image.

RuleHawk

RuleHawk analyzes your rules inside your browser, in a background worker running Python compiled to WebAssembly (Pyodide). The config you paste is not sent anywhere; the code that does this is public on GitHub under the Apache 2.0 license. The page is hosted on GitHub Pages and loads fonts from Google Fonts and Pyodide from the jsDelivr CDN, so those services see that you loaded it. To keep everything on your own machine, run the RuleHawk command line or its GitHub Action instead.

This website

No analytics, advertising or tracking scripts, and no cookies. The page loads only files from optimesh.ai, enforced by a Content-Security-Policy header. The request and message forms post to our host, Netlify. Details in the privacy notice.

Report a vulnerability

Email eng@optimesh.ai with a subject starting SECURITY:. If you hear nothing, escalate to hello@optimesh.ai. We don't publish a PGP key yet; if you need an encrypted channel, send a first email with the subject SECURITY: request encrypted channel and nothing sensitive in it, and we will set one up.

Please redact real device configs before sending anything: hostnames, public addresses, ASNs, keys and secrets.

Privacy notice

What we collect when you use optimesh.ai or our tools, and what we do with it. The short version: only what you type into our forms, plus the request logs our host keeps.

Last updated September 28, 2026

"We" means Optimesh Technologies. Questions go to contact@optimesh.ai.

What this website collects

• What you send us. The request-access form asks for your name, work email, company, network size, the product you're asking about and a message. The message form asks for your name, email, a subject and a message. Both are stored by our host, Netlify, and delivered to our team. If the form can't reach Netlify, your browser opens an email to us instead.
• Request logs. Netlify serves this site and, like any web host, logs requests: IP address, browser, the page requested and when. Netlify handles these under its privacy policy.
• Nothing else. No analytics, advertising or tracking scripts, and no cookies. The site loads no files from other domains.

How we use it

We use what you send to reply to you and to handle your request for access. We don't sell it, and we don't share it with anyone for their marketing. We keep it while we are talking with you and for as long as any relationship that follows needs it. Ask us and we will delete it.

Our products

• Hammerhead runs on your machines and sends us nothing: no telemetry, no usage data, no configs. See Security.
• RuleHawk analyzes your rules inside your browser; the config you paste is not sent to us or anyone else. The page is hosted on GitHub Pages and loads fonts from Google Fonts and code from the jsDelivr CDN, so GitHub, Google and jsDelivr see that you loaded it, under their own policies.
• Config Studio is set up per engagement. We describe its data flows in writing before you evaluate it.

Your choices

You can ask us what we hold about you, correct it, or have it deleted, by emailing contact@optimesh.ai. Links to other sites, such as GitHub or NVIDIA, are governed by those sites' own policies. If this notice changes, we will update the date at the top.

Terms of use

The terms for using optimesh.ai.

Last updated September 28, 2026

What these terms cover

These terms cover your use of this website, run by Optimesh Technologies ("we"). Hammerhead, Config Studio and other Optimesh software are licensed only under a separate written agreement with us. Nothing on this site grants a license to them.

Site content

The site describes our products and research for information. We work to keep it accurate and say how our figures were measured (see the methodology), but products change and the site may lag behind. Demos run on small synthetic labs, as each one says. Nothing here is a promise of results on your network.

The site's text, design and our product names and logos belong to us. Other names and logos belong to their owners and are used only to identify them.

RuleHawk

RuleHawk is free and open source under the Apache License 2.0, which governs its use and says it comes without warranty. Its findings help you review rules; they don't replace your own review before you change a firewall.

Using the site

Please don't attempt to disrupt or break into the site, and don't send us, through our forms, other people's personal information without their permission, or anything malicious. If you find a security problem, report it as described on the Security page.

No warranty

The site is provided as is, without warranties of any kind. To the extent the law allows, we are not liable for any loss arising from your use of the site or reliance on its content.

If these terms change, we will update the date at the top. Questions: contact@optimesh.ai.