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 CLI or a local web dashboard — from any device on the same network, including a smartphone.

Architecture

 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 -e .

Optional: set a parent PIN

netcurfew set-pin MySecretPin

Running the Daemon

The daemon must run with elevated privileges.

Windows (Run as Administrator)

netcurfew serve

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

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

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

# Immediately block internet
netcurfew stop

# Add time to the active session
netcurfew extend 15m

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

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

If no parent PIN is configured, the PIN prompt is skipped automatically. Use --immediately / -i on start, stop, and extend to bypass the prompt when a PIN is set but you want to proceed without one (the daemon still enforces its own PIN check server-side).

Web Dashboard

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

Features:

• Live status badge (green / red) with MM:SS countdown
• Quick action buttons: +15m, +30m, +1h, +2h, Extend, Stop
• PIN modal if a parent PIN is configured
• Mobile-responsive

Configuration (config.json)

Copy config.json.example to config.json and edit:

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, shutdown, and crash recovery.