Background research - FrankRay78/NetPace GitHub Wiki
This page records the research behind NetPace's direction: the opening it is aimed at, how it compares with the tool it can replace, what users of similar tools ask for, and three larger directions that were designed in detail and then deferred. The working backlog built from it is in Backlog. Last reviewed 11 October 2026.
Summary
NetPace is positioned as the open-source, scriptable successor to speedtest-cli. Three larger directions were researched and designed, and are deferred until the command-line tool has an installed base.
- The opening.
speedtest-cliwas archived in April 2026 and Homebrew will disable its formula in January 2027, so its users are choosing a successor. - The fit. NetPace already ships as a single native binary under the MIT licence, with CSV and JSON output, exit codes for automation, data-capped test profiles and a .NET library with test doubles.
- The gaps. A switch-by-switch comparison identified what a ported script would miss. Those gaps form the core of the backlog.
- The deferred directions. Cellular IoT testing, a product for managed service providers and a hosted cloud service each reached a concrete design. Each needs hardware in the test loop, a hosted backend or a sales channel, so each waits.
The speedtest-cli opening
The tool most people script against is being retired, and its users are choosing a successor. Figures are as of October 2026.
| Project | What it is | What the research found |
|---|---|---|
| speedtest-cli | Python command-line client for Ookla's servers, 14.1k GitHub stars | Archived by its owner on 30 April 2026. Homebrew deprecated the formula as unmaintained on 18 January 2026 and will disable it on 18 January 2027, yet it still recorded 18,995 installs over the previous year. Its documentation covers Python 2.4 to 3.7 and warns that results can be inconsistent. |
| speedtest-go | Open-source Go client and library for Ookla's servers, MIT, 822 GitHub stars | The closest open-source competitor. It is maintained and is in Homebrew's main repository as speedtest-go, with 154 installs in the last 30 days. It reports jitter and packet loss, and has --source, --custom-url, --json and --jsonl. NetPace differs in its data-capped profiles, its repeat-run and failure switches, and its .NET library with test doubles. |
| Ookla Speedtest CLI | Ookla's own client, installed from Ookla's Homebrew tap | The vendor's own tool and the default replacement for many users. |
| Speedtest Tracker | Self-hosted monitoring application, 5.9k GitHub stars | Runs as a container. Records download, upload, ping and packet loss, and notifies when performance drops below a threshold. It shows the demand for unattended monitoring, and leaves room for a tool that needs no container. |
| LibreSpeed CLI | Open-source client for self-hosted LibreSpeed servers, LGPL-3.0 | Anyone can host a server. The client has --server-json, --local-json, --interface and --source, which are precedents for backlog items 16 and 20. |
| Ookla Speedtest network | The server network NetPace uses by default | Hosting a server in the network requires registration and approval, so it does not suit private or self-hosted testing. |
Gap analysis
Every speedtest-cli switch was compared with NetPace as it stood in October 2026. The everyday switches are already covered, and each remaining gap became a backlog item. The comparison is a source of gaps, not a specification: NetPace competes for people leaving speedtest-cli without copying it switch for switch, and keeps its own switch names.
speedtest-cli switch |
Purpose | NetPace today | Backlog item |
|---|---|---|---|
--no-download, --no-upload |
Skip a test | Same switches | Covered |
--single |
One connection instead of several | Parallelism is a library setting with no switch | 21 |
--bytes |
Show bytes instead of bits | --unit BytesPerSecond |
Covered |
--simple |
Compact output | --minimal |
Covered |
--csv, --csv-delimiter |
CSV with speeds in bit/s | Same switches, but cells carry units by default and there are no server columns | 9, 11 |
--csv-header |
Print the CSV header only on request | Header printed at the start of every run | 14 |
--json |
JSON with numeric speeds in bit/s, latency in ms, bytes transferred, and server and client details | JSON with formatted strings, and the server's location, sponsor and URL | 8, 10, 12, 13 |
--list |
List servers by distance | servers command, with latency through servers -l |
Covered |
--server ID |
Choose a server by ID; scripts written for speedtest-cli pass an ID |
--server takes a URL |
17, 18 |
--exclude ID |
Leave a server out of selection | None | 19 |
--mini URL |
Test against a custom server | --server URL |
Covered |
--source IP |
Bind to a source address | None | 20 |
--timeout |
HTTP timeout, 10 seconds by default | Timeouts are library settings with no switch | 22 |
--secure |
Use HTTPS | Discovery defaults to plain HTTP | 23 |
--share |
Post the result to speedtest.net for a shareable image | None | Not planned |
--no-pre-allocate |
Avoid a large upload buffer on low-memory systems | Not needed: uploads are streamed in small chunks | Covered |
brew install, pip install |
One-line install | Download and unzip a release archive | 1, 2, 3 |
NetPace also has capabilities speedtest-cli never offered:
| Capability | How it is used |
|---|---|
| Repeat runs | --loop, --count, --delay |
| Data-capped tests | --profile (Tiny, Small, Medium, Large, Mega), --downloadsize, --uploadsize |
| Failure detection | --fail-on (None, Total, Partial), with request counts in every output format |
| Unit control | --unit, --unit-scale, --unit-system (SI or IEC) |
| File output | --file, --file-mode (Append or Overwrite) |
| Timestamps | --timestamp, --datetimeformat |
| Native binaries | Native AOT builds for Linux and Windows on x64 and ARM64, with no runtime to install |
| Developer library | NetPace.Core on NuGet, with SpeedTestStub, SpeedTestMock, VariableSpeedTester and FaultySpeedTester for testing without network calls |
Demand research
What users ask of comparable tools shaped the backlog items that go beyond parity. The main source was a Speedtest Tracker v2 discussion thread that ran from August 2025 to April 2026, with about 24 comments.
| Finding | Design sketch | Backlog item |
|---|---|---|
| Jitter is a frequent request. | The standard deviation of the latency samples NetPace already collects, reported in every output format. | 24 |
| Multi-WAN users want to choose the network interface. The most recent comment in the thread argued for it. | --interface eth1, passing a source-interface hint so a firewall can policy-route the traffic. LibreSpeed's --interface and --source are the precedent. |
20 |
| Threshold alerting is widely requested. | --alert-below-download 50mbps, printing a warning and exiting non-zero. The backlog generalises this to --min-download, --min-upload and --max-latency. |
25 |
| People want to test against servers they run themselves. LibreSpeed can be self-hosted with one Docker command and is LGPL-licensed. | --provider librespeed with --server https://... for a fixed endpoint, implemented as a second ISpeedTestService. A server list file modelled on LibreSpeed's --server-json and --local-json. |
16, 27 |
| Homelab and Proxmox users want a tool that runs without containers. | Lead the README with "no Docker, no setup, just a binary", and promote the library's test doubles to developers. | 7 |
| ARM boards and Apple Silicon need native builds. | Extend the release matrix. Linux and Windows ARM64 with Native AOT have shipped; macOS Native AOT remains. | 5 |
| Packet loss was requested in the same thread. | Set aside. A test that runs over HTTP cannot see lost packets, because TCP retransmits them. NetPace reports failed requests instead. | Not planned |
Measurement ideas
Twelve test modes were sketched early in the project, each with the switches it would need. Three have shipped, one is in the backlog and eight are held for later.
| Mode | How it works | Sketched switches | Status |
|---|---|---|---|
| Basic download test | Fetch a file of known size over one or several connections for an average speed. | --url, --threads, --duration |
Shipped as the default test |
| Long-term monitor | Repeat small tests on a schedule and log the results. | --monitor, --interval, --log |
Shipped as --loop, --count, --delay and --file |
| Fixed-size download | Download until a target total size is reached. | --size, --mirror, --threads |
Shipped as --downloadsize |
| Latency under load | Measure ping or HTTP HEAD response times while a large download runs, to reveal bufferbloat. | --latency-under-load, --ping, --threshold-latency |
Backlog item 26 |
| Baseline regression | Compare results with a saved reference and flag slowdowns. | --baseline, --warn-on-degrade, --threshold-speed |
Later; overlaps item 25 |
| Ramp-up visualiser | Record throughput each second during a large download to show how TCP speed climbs. | --rampup, --seconds |
Later |
| Concurrency optimiser | Test several levels of parallelism and report the best count. | --autoconcurrency, --max-threads |
Later |
| Asset burst simulation | Launch many simultaneous downloads of numbered small files. | --burst, --url-template, --concurrency, --shuffle |
Later |
| VPN and proxy test | Measure through a chosen proxy or VPN endpoint, with a custom address, port or SNI. | --proxy, --port, --sni |
Later |
| Cross-region benchmark | Run the same test against several regions or cloud zones and compare. | --region, --multi-region, --compare |
Later |
| Protocol test | Compare downloads over HTTP/1.1, HTTP/2, HTTP/3, TCP and UDP. | --protocol, --port |
Later |
| Raw TCP and UDP mode | Stream fixed-size blocks over sockets to a custom test server. | --mode, --host, --port, --size |
Later |
IoT research
Cellular IoT was researched as NetPace's first commercial direction, and five features were designed as the route in. IoT Analytics counted 18.5 billion connected IoT devices at the end of 2024 and forecasts 39 billion by 2030 (State of IoT 2025).
The problem. Teams deploying cellular devices must validate connectivity before shipping, diagnose failures in poor coverage, compare carriers, monitor fleets, and control data cost on plans of 10 to 100 MB a month.
Who it serves. Device manufacturers first, then fleet management companies, connectivity providers such as Aeris, Eseye, KORE Wireless and Onomondo, and enterprise deployments such as utilities and municipalities.
First five features
| Feature | Proposed switches | Design | Estimate | Status |
|---|---|---|---|---|
| Minimal data usage mode | --profile, --estimate |
Named profiles from micro (about 100 KB down, 50 KB up) to large. A "Data used" line in the output, and a warning before a run that would exceed a threshold. | 2 to 3 days | Profiles shipped as Tiny to Mega, with Tiny capped at 1 MiB. Data used is item 13. Estimate and warning held for later. |
| Signal strength metrics | --include-signal-metrics, off by default |
Fields signal_strength_dbm, signal_quality and network_type. Quality bands: Excellent above -70 dBm, Good -70 to -85, Fair -85 to -100, Poor below -100. On Linux, read /sys/class/net/wwan0/, call mmcli -m 0 --signal-get (ModemManager) or send AT commands. On Windows, use netsh or a Windows API. Parse RSSI, RSRQ and RSRP where available. |
3 to 5 days | Later |
| Location tagging | --location, --location-name |
Accepts "lat,lon", "lat,lon,alt", free text such as a depot name, or auto. Manual entry first with no geocoding, GPS through gpsd later. A location object in JSON and matching columns in CSV. |
2 to 3 days | Later |
| Device ID output | --device-id, --imei, --sim, --custom-field |
Fields device_id, imei and sim_iccid, with IMEI optionally read from the modem. Custom fields are arbitrary key-value pairs. |
1 to 2 days | Label and custom fields are item 15. IMEI and SIM later. |
| Quick test mode | --quick |
Use the first or a cached server in place of discovery, five pings in place of twenty, and optionally skip transfers. Cuts a run from 30 to 60 seconds down to 5 to 10. | 1 to 2 days | Item 28 |
Private networks are already supported: --server accepts a private endpoint, which suits private APNs and avoids relying on Ookla's public servers for commercial use.
Later tiers
| Tier | Features |
|---|---|
| 1 | A lightweight agent (binary under 5 MB, under 1 MB of data and 30 seconds per test), multi-carrier testing, signal metrics including SINR, location-based testing, scheduled tests, battery impact. |
| 2 | Bulk device testing, carrier certification reports, regional coverage testing, site surveys, SLA tracking, anomaly detection against a 30-day baseline. |
| 3 | Modem diagnostics for Quectel, Sierra Wireless and Telit modules, power profiling, OTA update testing, carrier cost analysis, regulatory compliance testing. |
Commercial options considered
- Pricing. Subscriptions by fleet size at $99, $299, $999 and $2,999 a month were preferred over per-test pricing at $0.10 a device, API credits, and white-label licensing at $10,000 plus $1,000 a month.
- Route to market. IoT World and MWC, partnerships with module makers, the AWS IoT and Azure IoT Hub marketplaces, and 5 to 10 pilot device makers to validate the product first.
- What customers use today. Manual field testing, validation services from connectivity providers, and carrier tools such as Verizon ThingSpace and the AT&T IoT Platform.
Why it is deferred. Signal and modem features need cellular hardware in the test loop, which the automated test suite cannot yet provide, and the fleet features depend on a hosted backend. The data-capped profiles and ARM64 Native AOT builds that came out of this research have shipped and serve every user.
MSP research
Managed service providers were researched as a second commercial direction: a product built on NetPace that tests, records and reports on many client networks.
The problem. MSPs spend heavily on client onboarding, manage many networks at once, owe clients SLA reports, need baselines to price work, and want to spot degradation before the client does.
| Tier | Features |
|---|---|
| 1 | Multi-tenant client management (NetPace client add, --client acme-001), scheduled tests, historical storage and trending, PDF and DOCX reports, baselines with deviation alerts by email, webhook, Slack or SMS, and CSV and JSON bulk export. |
| 2 | Ticketing integration (ConnectWise Manage, Autotask PSA, HaloPSA, ServiceNow, Zendesk, Freshdesk), white-label branding, before-and-after comparison, multi-location testing, SLA threshold tracking, a web dashboard, webhooks and a REST API. |
| 3 | VoIP and video quality testing, a mobile app for field technicians, year-over-year comparison, a cost-per-Mbps calculator, and role-based access (Admin, Technician, Read-Only, Client Portal). |
Technical direction. Move from file-based JSON and CSV to SQLite for small providers or PostgreSQL for large ones, with clients, tests and alerts tables. Keep per-client configuration in YAML folders. Generate reports with Pandoc, matplotlib or plotly, and Jinja2 templates.
Commercial options considered. Tiered pricing at $49 for 10 clients, $149 for 50 and $399 unlimited was preferred over $5 a client or $29 a technician a month. Routes to market were direct sales, the ConnectWise Marketplace, Pax8, Datto and MSP communities such as r/msp, with about 10 pilot MSPs to validate the product first.
Why it is deferred. This is a multi-tenant product with storage, scheduling and reporting, built on top of the command-line tool. It waits until the command-line tool has an installed base.
Cloud service research
A hosted service behind NetPace was planned in four phases, each assessed for what users gain and what it would teach about running a cloud platform.
| Phase | What it adds | Value to users | Learning value |
|---|---|---|---|
| 1. NetPace Cloud | An optional --upload flag, a personal history dashboard with CSV download, public shareable result links for ISP disputes, results from several devices under one account, baseline detection, and a NetPace.Cloud.Client NuGet library. |
High | Solid: core AWS services |
| 2. AWS IoT Core | A fleet dashboard with a map and offline detection, multi-carrier comparison, coverage heatmaps, email anomaly alerts, over-the-air schedule changes and remote firmware updates. Built on AWS IoT Core and the Device Shadow pattern, with Raspberry Pi test devices. About 8 weeks. | Very high | Very high: AWS IoT in practice |
| 3. Infrastructure as code | Nothing new for end users. The whole service deployable with AWS CDK into a fresh account in under 10 minutes, which allows self-hosting, safe rebuilds and cost control. | Low directly, high as an enabler | Very high: infrastructure as code |
| 4. Observability and scaling | A public status page, request tracing with AWS X-Ray, EKS or ECS for bulk device testing, and usage and cost dashboards. | High, but only with real users | High |
Where to stop. Phase 1 is worth building on its own. Phases 1 and 2 together are the highest-value stopping point. Phase 3 follows if the service continues, and Phase 4 only if Phase 2 gains traction; it should not be built speculatively.
Why it is deferred. A hosted service has running costs and needs users to fill it. It becomes worthwhile once the command-line tool is widely installed.