NetCurfew

A production-grade local screen-time and internet control system for parents.

NetCurfew runs a privileged background daemon that manipulates OS firewall rules. Access is granted by the parent via an interactive menu, CLI, or local web dashboard — from any device on the same network, including a smartphone.

Architecture

 Menu (netcurfew-menu.bat)   CLI (netcurfew)   Web UI (browser)
           |                       |                  |
           +----------+------------+------------------+
                      | HTTP REST  (localhost:5000)
                      v
           NetCurfew Daemon  (FastAPI / runs as admin)
                      |
                      v  OS firewall commands
           Windows netsh / Linux iptables / macOS pfctl

Default state: internet BLOCKED. Access must be explicitly granted.

Installation

# Requires Python 3.11+
pip install netcurfew

# Or install from source
pip install -e .

Check version and updates

netcurfew --version

Prints the installed version and checks PyPI for a newer release automatically.

Optional: set a parent PIN

netcurfew set-pin 123456

Once set, all internet access changes (start, stop, extend, allow) require the PIN.

Quick Start — Interactive Menu (Recommended)

The easiest way to operate NetCurfew is the included menu script. Double-click netcurfew-menu.bat or run it from a terminal:

netcurfew-menu.bat

+------------------------------------------+
|        NetCurfew - Internet Control       |
+------------------------------------------+
|                                          |
|   SERVICE                                |
|   [1] Start Daemon                       |
|   [2] Stop  Daemon                       |
|                                          |
|   INTERNET ACCESS                        |
|   [3] Show Status                        |
|   [4] Allow 15 Minutes                   |
|   [5] Allow 30 Minutes                   |
|   [6] Allow  1 Hour                      |
|   [7] Allow  2 Hours                     |
|   [8] Unlimited  (Work Mode)             |
|   [9] Block Internet Now                 |
|                                          |
|   SETTINGS                               |
|   [P] Set Parent PIN                     |
|   [0] Exit                               |
+------------------------------------------+

Option [1] starts the daemon in the background with --no-block-on-exit so closing the menu window does not cut internet. Option [2] finds and stops it.

Running the Daemon Manually

The daemon must run with elevated privileges.

Windows (Run as Administrator)

netcurfew serve

For work machines where you don't want Ctrl+C to block internet:

netcurfew serve --no-block-on-exit

To install as a Windows Service (using NSSM or sc.exe):

sc create NetCurfew binPath= "C:\Python311\Scripts\netcurfew.exe serve" start= auto
sc start NetCurfew

Linux (systemd)

Create /etc/systemd/system/netcurfew.service:

[Unit]
Description=NetCurfew Internet Control Daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/netcurfew serve
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now netcurfew

macOS (launchd)

sudo netcurfew serve

CLI Usage

# View current state
netcurfew status

# Check installed version and whether an update is available
netcurfew --version

# Grant internet access — defaults to the first allowed_durations entry (15m)
netcurfew start

# Grant a specific duration
netcurfew start 30m
netcurfew start 1h
netcurfew start 2h

# Allow internet indefinitely — no timer (Work Mode)
netcurfew allow

# Block internet immediately
netcurfew stop

# Add time to the current active session
netcurfew extend 15m

# Supply PIN via flag (skips interactive prompt)
netcurfew start 30m --pin 123456
netcurfew allow --pin 123456
netcurfew stop --pin 123456

# Skip PIN prompt entirely (useful in scripts or when no PIN is configured)
netcurfew start -i
netcurfew allow -i
netcurfew stop -i
netcurfew extend 30m -i

If no parent PIN is configured, the PIN prompt is skipped automatically. Use --immediately / -i to bypass the prompt when a PIN is set.

Web Dashboard

Open http://<machine-ip>:5000 in any browser on the local network.

Features:

• Live status badge: 🟢 INTERNET ACTIVE (timed), 🟡 INTERNET UNLIMITED (work mode), 🔴 INTERNET BLOCKED
• MM:SS / HH:MM:SS countdown for timed sessions; ∞ for unlimited
• Quick-start buttons: +15m, +30m, +1h, +2h
• ∞ Unlimited (Work Mode) button for uninterrupted access
• Extend (+15m, +30m) and Stop Now buttons when a session is active
• PIN modal appears automatically if a parent PIN is configured
• Mobile-responsive, no internet required (fully self-contained — no CDN dependencies)

Configuration (config.json)

Security Notes

• All firewall changes require the daemon to run as Administrator / root.
• The daemon binds to 127.0.0.1 by default; LAN access requires binding to a local network interface (handled when lan_only: true).
• Session timing uses time.monotonic() — immune to OS clock manipulation.
• Fail-safe: the daemon blocks internet on startup and shutdown by default.
• Use --no-block-on-exit only on trusted parent/admin machines.