xcancel-forwarder

Local network tool that transparently redirects all X/Twitter traffic to xcancel.com, allowing you to browse Twitter content without directly accessing X's servers.

Project maintained by ryantenney Hosted on GitHub Pages — Theme by mattgraham

X/Twitter → xcancel Redirector

Local network tool that transparently redirects all X/Twitter traffic to xcancel.com, allowing you to browse Twitter content without directly accessing X’s servers.

What is xcancel?

xcancel.com is a privacy-respecting Twitter/X frontend that lets you view tweets, threads, and profiles without tracking, ads, or algorithm manipulation. It’s similar to Nitter but remains actively maintained as of 2025.

How It Works

This setup intercepts X/Twitter traffic using DNS override + reverse proxy:

┌─────────────┐      DNS Query           ┌──────────────┐
│ Your Device │─────twitter.com?────────▶│ DNS Server   │
│             │                           │ (Pi-hole/    │
│             │◀────nginx IP (local)─────│  dnsmasq)    │
└─────────────┘                           └──────────────┘
       │
       │ HTTP Request to twitter.com
       │ (goes to nginx IP instead)
       ▼
┌─────────────┐
│ nginx       │─────301 Redirect────────▶ xcancel.com
│ Container   │                           (loads content)
│ (local)     │
└─────────────┘

What happens:

  1. Your DNS server points twitter.com/x.com/t.co to your nginx server’s IP
  2. nginx receives the request and issues a 301 redirect to xcancel.com
  3. Your browser loads content from xcancel instead of X

Why? View tweets shared in links while avoiding tracking and supporting privacy-respecting alternatives.

Prerequisites

Choose Your Setup Path

🎯 Path 1: Web Wizard (Recommended for Beginners)

🚀 Launch Web Wizard

Interactive browser tool that:

Time: 10-15 minutes • Difficulty: Easy

⚡ Path 2: CLI Wizard (For Servers)

python3 scripts/setup-wizard.py

Command-line wizard that:

Time: 5-10 minutes • Difficulty: Medium

📚 Path 3: Manual Setup (For Learning)

Follow the detailed guides to understand each component:

  1. Quick Start Guide - Step-by-step manual setup
  2. SSL Setup (mkcert) - Easy certificates
  3. DNS Configuration - Choose your DNS method

Time: 20-30 minutes • Difficulty: Medium-Hard

Not sure which? See Decision Guide for help choosing setup options.

Quick Start (Manual)

For those who want to understand each step:

# 1. Clone and configure
git clone https://github.com/ryantenney/xcancel-forwarder.git
cd xcancel-forwarder
cp .env.example .env
# Edit .env with your network settings

# 2. Set up SSL certificates (optional but recommended)
brew install mkcert
mkcert -install
mkcert twitter.com x.com "*.twitter.com" "*.x.com" t.co "*.t.co"
# Place certificates in nginx/ssl/

# 3. Start nginx
docker compose up -d

# 4. Configure DNS (choose one):
#    - Pi-hole: Add DNS records in web UI
#    - dnsmasq: Uncomment in docker-compose.yaml
#    - Router: Add static DNS entries
#    See docs/ for detailed instructions

# 5. Test
curl -I http://twitter.com  # Should show 301 to xcancel.com

Full details: See docs/QUICKSTART.md

Configuration Options

Web Server

See Caddy Alternative

SSL Certificates

See SSL Setup Guide or Advanced SSL

DNS Method

See Decision Guide to choose

Networking

See docker-compose.yaml comments for setup

Project Structure

.
├── setup-wizard.html          # Web-based setup wizard
├── docker-compose.yaml        # nginx configuration
├── docker-compose.caddy.yaml  # Caddy alternative
├── .env.example               # Environment template
├── nginx/
│   ├── conf.d/
│   │   └── xcancel-redirect.conf  # Redirect rules
│   └── ssl/                   # Place certificates here
├── caddy/
│   ├── Caddyfile              # Caddy config (simpler)
│   └── ssl/                   # Caddy certificates
├── dnsmasq/
│   └── dnsmasq.conf           # Optional DNS server
├── docs/                      # Detailed guides
└── scripts/
    ├── setup-wizard.py        # CLI wizard
    └── test-redirect.sh       # Quick test

Testing

# Check DNS resolution
nslookup twitter.com  # Should return nginx IP

# Test HTTP redirect
curl -I http://twitter.com  # Should show 301

# Test HTTPS redirect (if SSL configured)
curl -I https://twitter.com

# Test in browser
# Visit twitter.com - should redirect to xcancel.com

Detailed testing: See docs/TESTING.md

Common Issues

Redirect not working

# Check DNS
nslookup twitter.com  # Should return nginx IP

# Check nginx is running
docker compose ps

# View logs
docker compose logs nginx

Browser warnings

DNS not updating

Full troubleshooting: See docs/TESTING.md

Quick Reference

# Start services
docker compose up -d

# View logs
docker compose logs -f nginx

# Restart
docker compose restart

# Stop
docker compose down

# Update
docker compose pull && docker compose up -d

Complete reference: See docs/QUICK_REFERENCE.md

Documentation

Getting Started:

Configuration:

Testing & Troubleshooting:

Security Notes

Installing a self-signed CA as trusted means your device will trust any certificate signed by that CA. Keep the CA private key secure and only install on devices you control.

This setup only intercepts domains you explicitly configure. It cannot intercept other domains without adding them to DNS, nginx config, and SSL certificate.

See Security Considerations for details.

Contributing

Issues and pull requests welcome at https://github.com/ryantenney/xcancel-forwarder

License

MIT License - see LICENSE

Acknowledgments