Quick Start

WARP + NextDNS Manager is a cross-platform CLI tool that combines Cloudflare WARP's WireGuard-based encrypted tunneling with NextDNS's intelligent DNS filtering. This guide will help you set up enterprise-grade internet security on your system.

Pro Tip: For the best experience, use the interactive setup wizard by running python cli.py setup after installation.

Prerequisites

Python 3.8+

Required for the CLI application

Administrator Access

For service management and network configuration

Internet Connection

For initial setup and WARP registration

NextDNS Config ID

Optional, for custom DNS filtering profiles

Installation Methods

Python Package Installation

Recommended method for most users. This installs the latest stable release.

1

Clone the Repository

Terminal 
git clone https://github.com/nightcodex7/warp-nextdns-wireguard.git
cd warp-nextdns-wireguard
2

Choose Your Branch

Select the appropriate branch for your needs:

Terminal 
# For development/testing (latest features)
git checkout testing

# For stable releases (recommended for production)
git checkout main
3

Install Dependencies

Terminal 
pip install -r requirements.txt
4

Run Interactive Setup

Terminal 
python cli.py setup

The setup wizard will guide you through:

  • System detection and validation
  • WARP registration and configuration
  • NextDNS profile setup
  • Service installation and testing

Git Clone Method

For developers and users who want the latest development version.

1

Clone with Development Branch

Terminal 
git clone -b testing https://github.com/nightcodex7/warp-nextdns-wireguard.git
cd warp-nextdns-wireguard
2

Install Development Dependencies

Terminal 
pip install -r requirements.txt
pip install -e .

Pip Install Method

For users who prefer package manager installation (when available).

1

Install via Pip

Terminal 
pip install warp-nextdns-manager
2

Run Setup

Terminal 
warp-nextdns setup

Platform-Specific Instructions

macOS Not Supported: This project is designed for Linux and Windows only. macOS users should not attempt to install this software.

Linux Installation

Linux users get the most comprehensive feature set with native system integration.

Ubuntu/Debian

Terminal 
# Update system
sudo apt update && sudo apt upgrade -y

# Install Python and dependencies
sudo apt install python3 python3-pip python3-venv git curl -y

# Clone and setup
git clone https://github.com/nightcodex7/warp-nextdns-wireguard.git
cd warp-nextdns-wireguard
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python cli.py setup

CentOS/RHEL/Fedora

Terminal 
# Install Python and dependencies
sudo dnf install python3 python3-pip git curl -y

# Clone and setup
git clone https://github.com/nightcodex7/warp-nextdns-wireguard.git
cd warp-nextdns-wireguard
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python cli.py setup

Arch Linux

Terminal 
# Install Python and dependencies
sudo pacman -S python python-pip git curl

# Clone and setup
git clone https://github.com/nightcodex7/warp-nextdns-wireguard.git
cd warp-nextdns-wireguard
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python cli.py setup

Windows Installation

Windows users can enjoy full WARP + NextDNS integration with automatic service management.

Prerequisites

  • Windows 10/11 (64-bit)
  • Python 3.8+ installed
  • Administrator privileges
  • Git for Windows (optional)

Installation Steps

PowerShell (Admin) 
# Clone repository
git clone https://github.com/nightcodex7/warp-nextdns-wireguard.git
cd warp-nextdns-wireguard

# Create virtual environment
python -m venv venv
.\venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

# Run setup
python cli.py setup
Note: Run PowerShell as Administrator for proper service installation and network configuration.

Post-Installation Setup

WARP Configuration

The setup wizard will automatically handle:

  • WGCF installation and registration
  • WireGuard configuration generation
  • Service installation and startup
  • Connection testing and validation

NextDNS Configuration

For optimal DNS filtering:

  • Create a NextDNS account at nextdns.io
  • Configure your filtering preferences
  • Use your configuration ID during setup
  • Test DNS resolution and filtering

Verification

After installation, verify everything is working:

Terminal 
# Check system status
python cli.py status

# Run connection tests
python cli.py test

# View real-time logs
python cli.py logs

Troubleshooting

Permission Errors

If you encounter permission errors:

  • Ensure you're running with administrator/root privileges
  • Check file permissions in the configuration directory
  • Verify Python installation and PATH settings

Network Connectivity

If WARP or NextDNS isn't connecting:

  • Verify internet connection
  • Check firewall settings
  • Ensure DNS resolution is working
  • Try different WARP endpoints

Service Failures

If services fail to start:

  • Check service logs for detailed error information
  • Verify tool installation (wgcf, wg, nextdns)
  • Ensure proper configuration files exist
  • Restart the setup process

Getting Help

If you need additional help:

GitHub Issues Community Discussions