The Seed

Portable network diagnostic appliance with real-time web UI.

The Seed is a network diagnostic appliance from Mustard Seed Networks. Plug it into any network jack and the web UI shows link status, switch information, DHCP/DNS health, gateway reachability, Wi-Fi radio conditions, and security posture in real time. It runs on Linux, macOS and Windows.

What it does

• Wired diagnostics — link, DHCP, DNS, gateway, VLAN, path analysis, SNMP polling and topology.
• Wi-Fi troubleshooting — signal and SNR on the connected SSID, neighbour AP scan, channel utilization. Coverage mapping and AP placement are a different product: Seed answers "why is this client having a bad time here", not "where should the APs go".
• Security posture — insecure-service and guest-network checks, vulnerability scanning against CISA KEV and CVE feeds.
• Reporting — scheduled reports, exports and alert history.

Features

• Real-time diagnostics — live updates over WebSocket
• Link status — speed, duplex, advertised capabilities, flap counts
• Switch discovery — LLDP / CDP / EDP / FDP / Foundry
• DHCP analysis — phase timing breakdown (Discover/Offer/Request/Ack)
• DNS testing — forward + reverse lookups with timing
• Gateway health — ping, traceroute, latency tracking
• VLAN detection — tagged and native VLAN identification
• Wi-Fi — signal, SNR, neighbour APs, channel utilization (nl80211)
• Path discovery — multi-hop topology mapping
• Health checks — TCP / UDP / HTTP probes with thresholds
• Vulnerability scanning — CISA KEV + CVE feeds
• Threshold alerts — configurable green / yellow / red indicators
• Modern UI — Tailwind v4 design system, dark/light themes, mobile-responsive
• i18n-ready — translated UI namespaces
• Secure — HTTPS only with an operator-provided or self-signed certificate; password-only after first-run setup

Quick Start

Prerequisites

• Linux, macOS or Windows on x86-64 or arm64
• Go 1.27+
• Node.js 26+
• libpcap-dev

Hardware notes

Capability	Recommended adapter
Basic diagnostics	any
Wi-Fi visibility	nl80211-compatible (Intel AX200/210)
Cable diagnostics (TDR)	Intel I350/I210 or Broadcom BCM5719/5720

See HARDWARE.md for the full compatibility matrix.

The Seed needs raw-socket access for ARP scanning and packet capture. On Linux either:

# run as root
sudo ./seed

# or grant capabilities once
sudo setcap cap_net_raw,cap_net_admin=+ep ./seed
./seed

The ICMP ping sweep is the exception: where a raw socket is refused it falls back to the unprivileged datagram ICMP socket, which macOS always allows and Linux allows for any process whose group is inside net.ipv4.ping_group_range. Where neither is available the sweep does not run, and the discovery status stops listing icmp as an active method rather than reporting a scan that never happened.

What it does on its own

Discovery runs without a Settings visit: it listens for LLDP, CDP and EDP, and sweeps the active interface's subnet with ARP and ICMP at startup, on an interface change, and every 60 seconds after that. What answers is profiled lightly — the quick port list plus name resolution — so a device arrives with a type rather than a bare address.

The sweeps that act more loudly on the network wait for you: the full port scan, traceroute and SNMP queries are off until enabled, and SNMP also needs a credential in the vault. First-run setup offers to store one read community after the admin password is set — the field is empty, no community is suggested, and skipping it leaves the vault as it was. seed platform prints the same list for the machine it runs on, and the interval is a slider in Settings → Discovery.

Install + run

git clone https://github.com/MustardSeedNetworks/seed.git
cd seed
make build            # builds frontend + backend in one step
sudo ./seed           # listens on https://localhost:8443

Or grab an artifact from the releases page: .deb/.rpm/.tar.gz for Linux (amd64 and arm64), an Apple Silicon .tar.gz for macOS, or .zip for Windows. Packages are built only by release.yml on a tag — there is no local packaging target.

First run

1. Open https://<device-ip>:8443 (accept the self-signed cert).
2. Walk the first-run setup wizard to create the admin password — there is no shipped default password.

First-time TLS trust setup (optional)

Seed serves its UI over HTTPS with a self-signed certificate. To eliminate the browser warning, install that certificate into your OS trust store:

sudo seed install-ca

This adds seed's root certificate to the macOS Keychain, the Linux system CA bundle (Debian/Ubuntu via update-ca-certificates, RHEL/Fedora via update-ca-trust), or the Windows Certificate Store. After the install command finishes it prints the certificate's SHA-256 fingerprint. Compare it against what your browser shows ("View certificate → Details → Fingerprints") and against the value served at /__version:

seed install-ca --print-fingerprint
curl -k https://localhost:8443/__version | jq -r .tlsFingerprint

The two values must match.

To remove the certificate from the trust store:

sudo seed install-ca --uninstall

Editions

Seed ships as one binary on three tiers — Free, Starter and Pro. Entitlement is validated locally against a key you hold; nothing phones home. See docs/EDITIONS.md.

Configuration

seed.json (and SEED_* env vars) configure the appliance. See configs/seed.json for the full default config and configs/README.md for field documentation:

{
  "server": {
    "port": 8443,
    "public_origin": "",
    "cert_file": "",
    "key_file": ""
  },
  "interface": { "default": "eth0" }
}

Common environment overrides:

SEED_HTTPS_PORT=8443
SEED_PUBLIC_ORIGIN=https://seed.example.com
SEED_LOG_LEVEL=info       # debug | info | warn | error
SEED_DB_PATH=/var/lib/seed/data.db

Leave cert_file and key_file empty to use Seed's generated self-signed certificate. Set both paths for an operator-provided certificate. Remote deployments that use passkeys must set public_origin to the exact HTTPS origin browsers use to reach Seed.

Architecture

ui/src/              → React/TypeScript frontend (Vite)
                            ↓ npm run build
internal/api/ui/     → Built assets (embedded via go:embed)
                            ↓
cmd/seed/            → Entry point
internal/
├── api/             → HTTP/WebSocket handlers
├── database/        → SQLite store + migrations
├── network/         → Link, DHCP, DNS, cable, path probes
├── wifi/            → Wi-Fi visibility and troubleshooting
├── discovery/       → Device discovery and enumeration
├── license/         → Tier policy over the shared foundation module
├── config/          → JSON + env loading
├── auth/            → JWT + first-run setup
├── logging/         → Structured logging
├── i18n/locales/    → Translation namespaces
└── version/         → Build metadata (injected via ldflags)

The frontend builds directly into internal/api/ui/ and is embedded via //go:embed — no copy step, no runtime dependency on the source tree.

Build

Command	Purpose
make build	Full build (frontend + backend)
make test	Go + frontend unit/integration tests
make test-e2e	Playwright UI tests
make lint	golangci-lint + Biome
make security	govulncheck + npm audit + gitleaks
make fmt-check	Format check (Go + TS)
make fmt-all	Auto-format everything
make verify	Full local CI gate (lint + test + security + build)

Frontend-only iteration:

cd ui
npm run dev          # http://localhost:3000 with proxy to backend
npm run lint
npm run test
npm run typecheck
npm run test:e2e     # or `make test-e2e`, which builds an isolated backend first

Verified versions: Go 1.27.0, Node.js 26.8.1, golangci-lint v2.13.2. Cross-platform releases (linux/macOS/windows × amd64/arm64) are built by release.yml on tag push and signed with cosign keyless OIDC.

Frontend design system

The UI uses a Tailwind v4 CSS-first theme with semantic tokens:

• ui/src/styles/DESIGN_SYSTEM.md — full token reference (colors, typography, spacing, components)
• docs/DEVELOPMENT.md — setup and coding conventions

Versioning & Releases

Conventional commits drive release-please. Tags trigger release.yml, which builds binaries and packages (.deb/.rpm/.zip/.tar.gz) for linux, macOS and Windows on amd64 and arm64, and attaches an SBOM, a cosign bundle and SLSA provenance to each. Seed is not distributed through Homebrew and will not be (owner decision, 2026-09-07); on macOS the .pkg installer is the supported route.

License

Business Source License 1.1 — free for non-commercial use; commercial use requires a license. Converts to Apache-2.0 on the change date stated in the LICENSE file.

For commercial licensing inquiries: kris.armstrong@icloud.com.

Security

See SECURITY.md for the vulnerability-disclosure policy.

Contributing

See CONTRIBUTING.md.

Related projects

The Seed is the diagnostic appliance. Two sibling tools complete the Mustard Seed Networks testing toolkit:

• stem — RFC-compliant network performance testing
• niac-go — network device simulator