OxNetLab

Local-first Windows network observability dashboard.

OxNetLab monitors this machine and the network targets you configure, using real telemetry (psutil, ping.exe, the OS DNS resolver, and HTTP checks). Nothing is simulated. Nothing is sent to the cloud.

Built with FastAPI, React, TypeScript, SQLite and a single shared WebSocket. The default portable edition is a read-only NOC dashboard for Windows 10/11.

Features

• NOC dashboard — fullscreen Monitor Mode for 1366×768 through 3840×2160 (1920×1080 first).
• System — CPU (total, per-core, frequency), RAM used/available, swap, disks/volumes with health, uptime, process/thread counts, top 5 processes.
• Network — active interface, RX/TX with automatic units, link speed/utilization, bytes and packets, errors and drops (total + recent), TCP connection count.
• Quality — latency, jitter, packet loss, min/avg/max/p95, session availability from existing ping samples (no extra probes).
• Connectivity — interface, gateway, Internet and DNS health, plus application/runtime status.
• Targets, DNS, HTTP — configurable ICMP targets, DNS domains and HTTP endpoints (lab/source mode).
• Alerts / events — threshold rules, compact event feed, bounded history.
• Realtime — one shared WebSocket; bounded ring buffers (not unbounded arrays).
• Local-first — SQLite on disk, loopback bind by default, no analytics.

Portable Windows Edition

The supported way to use OxNetLab is the portable onedir build from GitHub Releases.

1. Download OxNetLab-Portable-v1.2.2-win-x64.zip from the latest release.
2. Extract the ZIP (keep the _internal folder next to OxNetLab.exe — this is a PyInstaller onedir layout, not a single-file exe).
3. Double-click OxNetLab.exe.

No installer. No Python, Node.js, npm or pip on the target PC.

The portable build starts in Monitor Mode (read-only). The backend rejects POST / PUT / PATCH / DELETE with HTTP 403 (MONITOR_MODE). GET, WebSocket and export stay available. The UI binds the backend to 127.0.0.1 only.

Writable state goes to %LOCALAPPDATA%\OxNetLab\ (SQLite, rotating logs, window position). The extracted folder is not written to.

Requirements

• Windows 10 or 11 (64-bit)
• Microsoft Edge WebView2 Runtime (included with Windows 11 and most Windows 10 installs; not bundled inside the ZIP)

The executable is not Authenticode-signed. Windows SmartScreen may display a warning on first run. Do not disable OS security features to run it.

See docs/PORTABLE.md for lifecycle, --lab (configuration mode) and data locations.

Develop from source

Python and Node.js are development requirements only. They are not needed to run the portable ZIP.

git clone https://github.com/zaureliu/OxNetLab.git
cd OxNetLab
setup_windows.bat
run_tests.bat
run_dev.bat

SSH:

git clone git@github.com:zaureliu/OxNetLab.git

Service	Default URL
Frontend	http://127.0.0.1:5173
Backend	http://127.0.0.1:8000

setup_windows.bat creates .venv, installs backend/requirements.txt and npm install in frontend/, and copies .env.example to backend/.env when missing.

Tests

From a configured checkout:

run_tests.bat

Or separately:

:: backend
.venv\Scripts\python.exe -m pytest backend\tests -q

:: frontend
cd frontend
npm test
npm run lint
npm run build

scripts\smoke_test.py boots a real backend + Vite proxy and runs 15 end-to-end checks.

Portable package (developers)

package_windows.bat

Output: release/OxNetLab-Portable/ (not committed). Requires the venv plus Node for the frontend bundle.

Architecture

FastAPI/Uvicorn collects telemetry on a 5 s cycle, persists a bounded SQLite history, and broadcasts over one WebSocket. The React UI (Vite + TypeScript) is either proxied in development or served from the frozen frontend in the portable exe (pywebview + Edge WebView2).

See docs/ARCHITECTURE.md.

Security model

• Loopback-only bind by default (127.0.0.1).
• No authentication and no TLS — anyone on the same Windows session can call the API. Do not expose the port on a LAN without your own reverse proxy.
• Portable Monitor Mode is enforced in the backend, not by hiding buttons.
• OpenAPI /docs is disabled in the frozen/portable build.

See SECURITY.md.

License

MIT License — Copyright (c) 2026 Anderson A. Justino.

Third-party notices for redistributed libraries: THIRD_PARTY_NOTICES.md.