bolok 0.5.0

Block websites with per-site daily time limits — hosts-based, daemon-enforced

bolok

bolok your distraction && focus your work

Block any website with a daily time limit. One timed session per day, then a 24-hour lockout — enforced at the OS level, survives reboots.

Works on macOS, Linux, and Windows. Pure Python, no dependencies, no browser extension, no account required.

How it works

bolok redirects domains to 0.0.0.0 via the system hosts file and keeps it in sync with a privileged background daemon that runs at boot and every 30 seconds.

• Add any site to your list with a per-site daily limit in minutes.
• bolok start opens a timed session — the site unblocks for that window.
• When the session ends (by timeout or bolok stop) the site re-blocks for a full 24-hour lockout, measured from the moment the session ended.
• Timers use absolute Unix timestamps, so sleep, reboot, or closing the terminal cannot extend a session.
• bolok off <sitename> is always available as an escape hatch.

Facebook (25 domains) is pre-loaded. Add anything else with bolok list add.

Requirements

Platform	Hosts file	Daemon	Extra
macOS	/private/etc/hosts	launchd	Xcode CLT (xcode-select --install)
Linux	/etc/hosts	systemd	Python 3.8+
Windows	System32\drivers\etc\hosts	Task Scheduler	Python 3.8+, elevated terminal

Install

# macOS / Linux
pip install bolok
sudo bolok install

# Windows (elevated terminal)
pip install bolok
bolok install

From source / dev:

git clone https://github.com/pdfarhad/bolok.git && cd bolok
pip install -e .
sudo bolok install

Upgrade: pip install --upgrade bolok && sudo bolok install

Quick start

# Enable blocking for all sites (Facebook is pre-loaded)
bolok on -a

# See per-site state and time remaining
bolok status

# Start your daily session for the single/default site
bolok start

# Done early? End the session (starts the 24h lockout from now)
bolok stop

Managing your site list

# Show all sites with limits and current state
bolok list

# Add a site — short name auto-derived from the URL
bolok list add instagram.com 15       # 15 min/day
bolok list add https://twitter.com 20 # 20 min/day

# Update a site's daily limit
bolok list edit instagram 30

# Enable / disable blocking per site
bolok on instagram
bolok off instagram

All commands

bolok on <sitename>               enable blocking for one site
bolok on -a                       enable blocking for all sites
bolok off <sitename>              disable blocking for one site
bolok off -a                      disable blocking for all sites
bolok start [<sitename>]          begin the one daily session
bolok stop  [<sitename>] [--yes]  end session early (costs the full 24h lockout)
bolok status                      per-site state, countdowns, daemon health
bolok limit [<sitename>] <min>    set session length (1-1440 minutes)
bolok browsers "Browser Name"     close these browsers when a block starts
bolok browsers off                stop auto-closing browsers
bolok list                        show all sites
bolok list add <url> <minutes>    add a new site
bolok list edit <sitename> <min>  update a site's daily limit
sudo bolok reset                  emergency: unblock hosts and reset all state
sudo bolok uninstall              remove daemon and CLI, keep state files

Known limitations

• macOS + Safari + iCloud Private Relay — Private Relay bypasses hosts-based blocking. Turn it off in System Settings, or use another browser.
• Windows Defender / antivirus may flag hosts file modifications. Allow bolok if prompted; it only writes its own marker section.
• Already-open tabs keep loading until the browser re-resolves DNS. Use bolok browsers "Firefox" to close browsers automatically at block time.
• VPNs and proxies bypass it. This is friction, not a prison — you have admin rights. bolok off <sitename> is always available.
• Domains are explicit. Adding a site blocks site.com, www.site.com, and m.site.com. Other subdomains are not covered unless added manually. Facebook's built-in list covers 25 domains across facebook.com, fb.com, and messenger.com.
• Windows enforcement granularity is 1 minute (Task Scheduler minimum), vs 30 seconds on macOS and Linux.

Reboot persistence

The hosts file is a plain file on disk — block entries survive reboots. A privileged daemon re-enforces timer transitions that expired while the machine was off:

Platform	Daemon	Boot delay	Interval
macOS	launchd (RunAtLoad = true)	immediate	30s
Linux	systemd timer	5s	30s
Windows	Task Scheduler	on startup	60s

Development

pip install -e .                          # editable install
python3 -m unittest tests.test_bolok -v  # 64 unit tests (pure functions only)

Single-file codebase (bolok.py). All pure logic is unit-tested; the imperative layer (file I/O, daemon wiring) is kept thin and verified manually.

License

MIT — see LICENSE