BlockForge

Website blocking toolkit — a Python CLI + FastAPI backend and React dashboard for managing domain blocking via the system hosts file.

Platform: Linux (Ubuntu) · Python: 3.12+ · Node: 18+

---

Overview

BlockForge lets you block distracting websites by redirecting their domains to 127.0.0.1 in /etc/hosts. It ships with two interfaces:

Interface	Technology	Purpose
CLI	Python / Typer	Block, unblock, and preview changes from the terminal
Dashboard	React + Vite + Tailwind	Browser-based UI to manage the blocklist and trigger actions

The frontend talks to the backend over a REST API (/api/*). During development, Vite proxies /api requests to the FastAPI server automatically — no CORS configuration needed.

---

Architecture

BlockForge/
├── backend/                  Python package (CLI + API)
│   ├── blockforge/
│   │   ├── cli.py            Typer CLI — block / unblock commands
│   │   └── blocker.py        Core hosts-file logic
│   ├── api/                  FastAPI REST layer
│   ├── scripts/
│   │   ├── block.sh          Shell wrapper for block command
│   │   └── unblock.sh        Shell wrapper for unblock command
│   ├── docs/                 Full documentation
│   ├── blocklist.txt         Default domain list (one domain per line)
│   └── pyproject.toml        Package metadata and dependencies
│
└── frontend/                 React + Vite dashboard
    ├── src/                  App source (components, pages, hooks)
    ├── vite.config.ts        Dev proxy → backend :8000
    └── package.json

---

Quick Start

1 — Backend (CLI + API)

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Run the API server as root (needed to write /etc/hosts)
sudo .venv/bin/uvicorn api.main:app --host 127.0.0.1 --port 8000 --reload

API live at http://127.0.0.1:8000 · Swagger docs at http://127.0.0.1:8000/docs

2 — Frontend (Dashboard)

cd frontend
npm install
npm run dev

Dashboard live at http://localhost:8080

3 — CLI (without the API server)

cd backend
source .venv/bin/activate

# Preview changes (no root needed)
blockforge block --dry-run

# Apply blocking
sudo env "PATH=$PATH" blockforge block

# Remove blocking
sudo env "PATH=$PATH" blockforge unblock

---

API Endpoints

Method	Path	Description
GET	/api/status	System status — is root, is hosts writable
GET	/api/domains	List all domains in the blocklist
POST	/api/domains	Add a domain to the blocklist
DELETE	/api/domains/{domain}	Remove a domain from the blocklist
POST	/api/block	Apply blocklist to /etc/hosts
POST	/api/unblock	Remove blocklist entries from /etc/hosts
GET	/api/hosts	Preview current /etc/hosts BlockForge entries
GET	/api/logs	Activity log

Full interactive docs at http://127.0.0.1:8000/docs when the server is running.

---

CLI Commands

blockforge block    [--dry-run] [--backup] [--file PATH] [--no-www] [--skip-flush]
blockforge unblock  [--dry-run] [--file PATH] [--no-www] [--skip-flush]

Option	Description
--dry-run	Preview changes without writing anything
--backup	Copy /etc/hosts to /etc/hosts.bak before modifying
--file PATH	Use a custom blocklist file instead of the default
--no-www	Skip automatic www. variants
--skip-flush	Do not flush the DNS cache after changes

See backend/docs/CLI_USAGE.md for the full reference.

---

Documentation

Document	Description
backend/docs/SETUP.md	Full installation and setup guide for backend and frontend
backend/docs/CLI_USAGE.md	Complete CLI command and option reference
backend/docs/troubleshooting.md	Diagnosis and fixes for common issues
backend/docs/roadmap.md	Planned features and next steps

---

Requirements

Component	Requirement
Python	3.12 or newer
OS	Linux (Ubuntu recommended)
Privileges	sudo for real block/unblock operations
Node.js	18 or newer (frontend only)

---

License

MIT — see backend/LICENSE.