https://github.com/aristeoibarra/nextdns-blocker
Automated NextDNS domain blocker with schedule-based access control, watchdog protection, and audit logging
https://github.com/aristeoibarra/nextdns-blocker
addiction automation cli digital-wellbeing distraction-blocker dns-blocking focus homebrew-tap linux macos nextdns parental-control privacy productivity python scheduler screen-time self-control windows
Last synced: 3 months ago
JSON representation
Automated NextDNS domain blocker with schedule-based access control, watchdog protection, and audit logging
- Host: GitHub
- URL: https://github.com/aristeoibarra/nextdns-blocker
- Owner: aristeoibarra
- License: mit
- Created: 2025-11-01T05:32:35.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-03-05T01:56:38.000Z (3 months ago)
- Last Synced: 2026-03-05T07:32:09.333Z (3 months ago)
- Topics: addiction, automation, cli, digital-wellbeing, distraction-blocker, dns-blocking, focus, homebrew-tap, linux, macos, nextdns, parental-control, privacy, productivity, python, scheduler, screen-time, self-control, windows
- Language: Python
- Homepage: https://nextdns-blocker.pages.dev
- Size: 1.57 MB
- Stars: 6
- Watchers: 0
- Forks: 12
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# NextDNS Blocker
[](https://pypi.org/project/nextdns-blocker/)
[](https://pypi.org/project/nextdns-blocker/)
[](https://pypi.org/project/nextdns-blocker/)
[](LICENSE)
[](https://github.com/aristeoibarra/nextdns-blocker/actions/workflows/ci.yml)
[](https://github.com/aristeoibarra/homebrew-tap)
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)
```bash
brew tap aristeoibarra/tap
brew install nextdns-blocker
nextdns-blocker init
```
### pip
```bash
pip install nextdns-blocker
nextdns-blocker init
```
### Docker
```bash
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](https://my.nextdns.io/account) 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](https://nextdns-blocker.pages.dev)**
- [Getting Started](https://nextdns-blocker.pages.dev/getting-started/)
- [Commands Reference](https://nextdns-blocker.pages.dev/commands/)
- [Configuration Guide](https://nextdns-blocker.pages.dev/configuration/)
## Basic Commands
```bash
nextdns-blocker config push # Sync based on schedules
nextdns-blocker status # Check current blocking status
nextdns-blocker unblock # Manually unblock a domain
nextdns-blocker watchdog install # Install automatic sync
```
## Example Configuration
```json
{
"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](CONTRIBUTING.md) for guidelines.
## License
MIT