PTPBox

Precision Time Lab

Build an entire PTP cascade inside one multi-NIC Linux host. Observe every hop. Measure accumulated error. Tune the servo. Repeat.

Live demo · Install · Architecture · Hardware guide · API

---

PTPBox is a modern revival of the original namespace-based PTPBox experiment. It uses physical NICs, Linux network namespaces, LinuxPTP, and hardware PHCs to turn one server into a chain of isolated clocks. The Precision Observatory adds the control room the project always deserved: live topology, offset traces, per-hop error budgets, repeatable experiments, hardware inventory, guarded configuration, and an explicit simulation fallback for demos.

Important

The web UI is safe to explore immediately. Starting the physical cascade moves the NICs declared in agent/topology.json into network namespaces. Review that file carefully and keep every management interface in management_interfaces before running ptpboxctl setup or start.

See timing error grow, hop by hop

The first viewport is the experiment: GM to OC, measured one clock at a time. Select any node to isolate its trace, current master offset, path delay, frequency adjustment, PHC, quality score, and active servo constants.

What you can do

Surface	Purpose
Cascade overview	See the physically verified topology, raw per-hop offset, path delay, window RMS, frequency correction, and servo state.
Analytics	Compare unsmoothed LinuxPTP traces, inspect the endpoint distribution, and export the raw timestamped samples.
Experiments	Run step, wander, holdover, and gain-sweep recipes with reproducible capture settings.
Servo tuning	Adjust PI gains and thresholds, preview behavior, validate, stage, and roll changes through the chain.
Hardware inventory	Discover NICs, PCI addresses, drivers, link rates, PHCs, and hardware timestamping capability.
Event stream	Follow clock-state transitions, measurement windows, threshold events, and operator actions.
Demo mode	Use an explicitly labeled deterministic fallback only when the live agent is unavailable.

Product tour

Stability analytics Raw trace selection, endpoint density, window RMS, frequency correction, and CSV export.	Repeatable experiments Step response, holdover, wander, and gain-sweep recipes.

Two ways to run it

1. Observer / demo mode — no root required

This serves the complete UI, discovers the host, reads LinuxPTP logs, and stages configuration without moving interfaces or starting privileged processes.

git clone https://github.com/ahmadexp/PTPBox.git
cd PTPBox
npm ci
npm run build:standalone

PTPBOX_ROOT="$PWD" \
PTPBOX_WEB_ROOT="$PWD/dist-standalone" \
python3 agent/ptpbox_agent.py

Open http://localhost:8090. If the agent cannot find live measurements, the Observatory labels itself as a hardware model and keeps every visualization interactive.

2. Full host integration — physical cascade

# 1. Map this machine's PTP ports and protect its management links.
$EDITOR agent/topology.json

# 2. Build, install, and start the persistent web agent.
npm ci
npm run build:standalone
sudo PTPBOX_USER="$(id -un)" PTPBOX_ROOT="$PWD" bash scripts/install-host.sh

# 3. Validate before moving any NIC.
sudo ptpboxctl discover
sudo ptpboxctl status

The UI is then available at http://<ptpbox-host>:8090. See the complete installation and upgrade guide before starting the data plane.

Architecture

flowchart LR
    Browser["Precision Observatory\nReact UI"]
    Agent["PTPBox agent\nPython · unprivileged"]
    Inventory["sysfs · ethtool\nNIC / PHC inventory"]
    Logs["LinuxPTP logs\ntelemetry parser"]
    Helper["ptpboxctl\nfixed privileged verbs"]
    NS["BC1 … BC7\nnetwork namespaces"]
    PTP["ptp4l · phc2sys\nhardware clocks"]

    Browser <-->|"HTTP · :8090"| Agent
    Agent --> Inventory
    Agent --> Logs
    Agent -. "sudo: start / stop / restart / status only" .-> Helper
    Helper --> NS
    NS --> PTP

Loading

The agent runs as the operator, not root. Observation stays unprivileged. Lifecycle control crosses a narrow sudo boundary that accepts four fixed commands and no arbitrary arguments. See Architecture and Security.

What gets measured

• Master offset and RMS offset for each clock
• Per-hop delta and cumulative cascade error
• Mean path delay and frequency adjustment
• Lock/tracking state and recovery events
• MTIE windows and mask verdicts
• Offset distribution, P95, skew, and contribution share
• NIC carrier, speed, driver, PCI bus, PHC, and timestamp capability
• Experiment metadata, servo constants, and capture lifecycle

The live agent parses native LinuxPTP output. Missing data is never silently presented as live; the UI switches to its deterministic hardware-model mode.

Hardware

The reference host uses seven dual-port timing-capable adapters for the cascade plus separate management ports. PTPBox is not tied to ConnectX hardware: Intel E810, i210/i225, ixgbe devices, and mixed-PHC systems work as long as LinuxPTP and hardware timestamping are available.

The original seven-NIC PTPBox host	The original namespace cascade concept

Read the hardware and topology guide for discovery commands, shared-PHC behavior, interface mapping, and a preflight checklist.

Repository map

app/                 Precision Observatory UI
agent/               Read-only host API, topology, systemd template
scripts/             Safe lifecycle, install, and uninstall helpers
standalone/          Static-host entrypoint for the on-box agent
docs/                Installation, architecture, API, hardware, experiments
tests/               Rendered-product checks
.github/workflows/   CI for UI, Python, shell, and standalone builds

Development

npm ci
npm run dev          # local application server
make check           # lint, tests, both builds, Python and shell validation

The main application uses React 19, TypeScript, Vinext/Vite, and Canvas-based telemetry charts. The host agent uses only the Python standard library.

Project status

The Observatory, raw incremental LinuxPTP telemetry pipeline, standalone host, inventory agent, configuration staging, and guarded lifecycle controller are implemented. The next milestones are durable experiment storage, direct PMC and PPS comparison datasets, automated MTIE/TDEV/Allan deviation, and reusable topology presets. See CHANGELOG.md.

Heritage

This project modernizes the public Time Appliances Project PTPBox prototype, created by Ahmad Byagowi. The namespace architecture, seven-node cascade, and hardware photographs come from that work.

Contributing

Bug reports, hardware profiles, measurement ideas, and UI improvements are welcome. Start with CONTRIBUTING.md and keep hardware safety front and center.

License

MIT © 2026 Ahmad Byagowi.