NextDNS Blocker

Automated domain blocking with per-domain scheduling via the NextDNS API. Build healthier digital habits through intelligent scheduling and friction-based protection.

Features

• Per-domain scheduling - Configure unique availability hours for each domain
• Domain categories - Group domains together with shared schedules
• NextDNS Parental Control - Enable/disable native NextDNS categories and services
• Unblock delays - Add friction against impulsive unblocking (30m, 4h, 24h, or never)
• Panic mode - Emergency lockdown that blocks all domains
• Cross-platform - Native support for macOS, Linux, and Windows
• Automatic sync - Watchdog runs every 2 minutes to enforce schedules
• Discord notifications - Real-time alerts for block/unblock events
• Allowlist with schedules - Time-based exceptions for specific domains
• Priority-based filtering - Allowlist always wins over category/service blocks

Quick Install

Homebrew (macOS/Linux)

brew tap aristeoibarra/tap
brew install nextdns-blocker
nextdns-blocker init

pip

pip install nextdns-blocker
nextdns-blocker init

Docker

git clone https://github.com/aristeoibarra/nextdns-blocker.git
cd nextdns-blocker
cp .env.example .env && cp config.json.example config.json
docker compose up -d

Quick Start

1. Get your NextDNS API Key and Profile ID
2. Run nextdns-blocker init to configure
3. Edit your domains: nextdns-blocker config edit
4. Install watchdog: nextdns-blocker watchdog install

Documentation

For complete documentation, visit: nextdns-blocker.pages.dev

• Getting Started
• Commands Reference
• Configuration Guide

Basic Commands

nextdns-blocker config push       # Sync based on schedules
nextdns-blocker status            # Check current blocking status
nextdns-blocker unblock <domain>  # Manually unblock a domain
nextdns-blocker watchdog install  # Install automatic sync

Example Configuration

{
  "blocklist": [
    {
      "domain": "reddit.com",
      "unblock_delay": "30m",
      "schedule": {
        "available_hours": [
          {
            "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
            "time_ranges": [
              {"start": "12:00", "end": "13:00"},
              {"start": "18:00", "end": "22:00"}
            ]
          }
        ]
      }
    }
  ]
}

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT