{"id":46243953,"url":"https://github.com/jasondostal/tunnelvision","last_synced_at":"2026-03-05T22:10:00.922Z","repository":{"id":341862537,"uuid":"1171295832","full_name":"jasondostal/tunnelvision","owner":"jasondostal","description":"All-in-one qBittorrent + WireGuard VPN + REST API container. See through the tunnel.","archived":false,"fork":false,"pushed_at":"2026-03-03T20:33:27.000Z","size":896,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-03T20:47:03.391Z","etag":null,"topics":["docker","home-assistant","killswitch","nftables","qbittorrent","selfhosted","vpn","wireguard"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jasondostal.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-03T04:24:50.000Z","updated_at":"2026-03-03T20:33:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jasondostal/tunnelvision","commit_stats":null,"previous_names":["jasondostal/tunnelvision"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/jasondostal/tunnelvision","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasondostal%2Ftunnelvision","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasondostal%2Ftunnelvision/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasondostal%2Ftunnelvision/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasondostal%2Ftunnelvision/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jasondostal","download_url":"https://codeload.github.com/jasondostal/tunnelvision/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jasondostal%2Ftunnelvision/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30060597,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T18:21:05.932Z","status":"ssl_error","status_checked_at":"2026-03-03T18:20:59.341Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","home-assistant","killswitch","nftables","qbittorrent","selfhosted","vpn","wireguard"],"created_at":"2026-03-03T21:00:31.944Z","updated_at":"2026-03-03T21:00:49.420Z","avatar_url":"https://github.com/jasondostal.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/tunnelvision-readme-banner.png\" alt=\"TunnelVision\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/jasondostal/tunnelvision?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Alpine-3.21-0D597F?style=flat-square\u0026logo=alpine-linux\" alt=\"Alpine\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/WireGuard-built--in-88171A?style=flat-square\u0026logo=wireguard\" alt=\"WireGuard\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/qBittorrent-built--in-2F67BA?style=flat-square\" alt=\"qBittorrent\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Home%20Assistant-native-41BDF5?style=flat-square\u0026logo=home-assistant\" alt=\"Home Assistant\"\u003e\n\u003c/p\u003e\n\n---\n\nqBittorrent + WireGuard VPN + killswitch + REST API + dashboard. One container. Full visibility.\n\nDrop your WireGuard config, `docker compose up`, and you can see everything — what IP you're on, where you're exiting, transfer stats, killswitch state, qBittorrent health. From your Homepage dashboard, from Home Assistant, from Prometheus, from the built-in UI, from `curl`. No guessing. No SSH-ing in.\n\nWorks with **any WireGuard provider**. Mullvad, IVPN, Proton, AirVPN, PIA, or your own server.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/screenshot-dashboard.png\" alt=\"TunnelVision Dashboard\" width=\"700\"\u003e\n\u003c/p\u003e\n\n## Quick Start\n\n```bash\nmkdir -p tunnelvision/wireguard\ncp /path/to/wg0.conf tunnelvision/wireguard/\n\ncurl -O https://raw.githubusercontent.com/jasondostal/tunnelvision/main/docker-compose.yml\ndocker compose up -d\n```\n\nThree things are now running inside one container:\n- **qBittorrent WebUI** on port `8080`\n- **TunnelVision API + Dashboard** on port `8081`\n- **WireGuard VPN** with nftables killswitch\n\n```bash\ncurl http://localhost:8081/api/v1/health | jq .\n```\n\n## Integrations\n\n### Homepage\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/screenshot-homepage.png\" alt=\"TunnelVision Homepage Widget\" width=\"700\"\u003e\n\u003c/p\u003e\n\nDrops right into [Homepage](https://gethomepage.dev) using the `customapi` widget. Pick the fields you want to see:\n\n```yaml\n- TunnelVision:\n    icon: https://raw.githubusercontent.com/jasondostal/tunnelvision/main/images/tunnelvision-mark-dark-512.png\n    href: http://your-host:8081\n    description: VPN + qBittorrent\n    widget:\n      type: customapi\n      url: http://tunnelvision:8081/api/v1/vpn/status\n      mappings:\n        - field: state\n          label: VPN\n          format: text\n        - field: location\n          label: Location\n          format: text\n        - field: public_ip\n          label: IP\n          format: text\n        - field: uptime\n          label: Uptime\n          format: text\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eAvailable fields for your widget\u003c/summary\u003e\n\nPick any 4 from `/api/v1/vpn/status`:\n\n| Field | Example | Good for |\n|-------|---------|----------|\n| `state` | `up` | Connection status at a glance |\n| `location` | `Zurich, Switzerland` | Where you're exiting |\n| `public_ip` | `193.32.127.220` | Current VPN IP |\n| `uptime` | `2h 34m` | How long the tunnel's been up |\n| `killswitch` | `active` | Firewall status |\n| `country` | `Switzerland` | Exit country only |\n| `city` | `Zurich` | Exit city only |\n| `provider` | `mullvad` | VPN provider |\n\nOr use `/api/v1/qbt/status` for torrent-focused widgets:\n\n| Field | Example | Good for |\n|-------|---------|----------|\n| `state` | `running` | qBit health |\n| `download_speed` | `5242880` | Current download (bytes/s) |\n| `upload_speed` | `1048576` | Current upload (bytes/s) |\n| `active_torrents` | `3` | Active count |\n| `total_torrents` | `47` | Library size |\n\n\u003c/details\u003e\n\n### Home Assistant\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/screenshot-ha.png\" alt=\"TunnelVision Home Assistant Entities\" width=\"400\"\u003e\n\u003c/p\u003e\n\nNative [HACS integration](https://github.com/jasondostal/tunnelvision-ha). 23 entities, real-time SSE updates, config flow, zero YAML.\n\n**Install via HACS:**\n1. HACS → Integrations → Three dots → **Custom Repositories**\n2. Paste `https://github.com/jasondostal/tunnelvision-ha` → category **Integration** → **Add**\n3. Search **TunnelVision** → **Download** → Restart HA\n4. **Settings → Integrations → Add → TunnelVision** — enter your host and port\n\nYou get:\n- **12 sensors** — VPN state, public IP, location, speeds, transfer stats, torrent counts, provider\n- **4 binary sensors** — VPN connected, killswitch active, healthy, qBittorrent running\n- **5 buttons** — Restart VPN, rotate server, restart qBit, pause/resume torrents\n- **2 switches** — VPN on/off, Killswitch on/off (reflect actual state)\n- **3 services** — `tunnelvision.vpn`, `tunnelvision.qbittorrent`, `tunnelvision.killswitch` for automations\n\nNo MQTT required. Real-time updates via SSE with polling fallback.\n\n### Prometheus + Grafana\n\n```bash\ncurl http://localhost:8081/metrics\n```\n\nExports `tunnelvision_vpn_up`, `tunnelvision_killswitch_active`, `tunnelvision_transfer_rx_bytes_total`, `tunnelvision_transfer_tx_bytes_total`, `tunnelvision_vpn_connected_seconds`, and more. Scrape it, graph it, alert on it.\n\n### Sonarr / Radarr / Prowlarr\n\nUse `tunnelvision` (or your container name) as the download client host in your arr stack:\n- **Host**: `tunnelvision` (Docker DNS) or your server IP\n- **Port**: `8080`\n- **Username**: `admin`\n- **Password**: your qBittorrent password\n\nAll torrent traffic routes through the VPN. The killswitch ensures nothing leaks if the tunnel drops.\n\n## Authentication\n\nOff by default. Three layers, all optional, all additive:\n\n| Method | Env Vars | How it works |\n|--------|----------|-------------|\n| **None** (default) | *(nothing set)* | Everything open |\n| **API key** | `API_KEY` | `X-API-Key` header for programmatic access (Homepage, HACS, Prometheus) |\n| **Local login** | `ADMIN_USER` + `ADMIN_PASS` | Login form in the dashboard, session cookie |\n| **Proxy bypass** | `AUTH_PROXY_HEADER` | Trusted header from your reverse proxy (Authentik, Authelia, Traefik, nginx) — skips the login form |\n\nSet `AUTH_PROXY_HEADER=Remote-User` (or `X-Forwarded-User`, whatever your proxy sends) and users authenticated by your reverse proxy get straight through. Direct users see the login form. API key always works for machine-to-machine.\n\n## Settings\n\nConfigurable from the dashboard UI (gear icon) or by editing `/config/tunnelvision.yml` directly. Settings in the YAML file override environment variables.\n\n```yaml\n# /config/tunnelvision.yml\nadmin_user: admin\nadmin_pass: changeme\nauth_proxy_header: Remote-User\nvpn_provider: custom\nhealth_check_interval: \"30\"\n```\n\n## Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003eEnvironment variables\u003c/summary\u003e\n\nAll via environment variables. Sensible defaults for everything. Settings UI and `/config/tunnelvision.yml` override these.\n\n| Variable | Default | What it does |\n|----------|---------|-------------|\n| `ADMIN_USER` | *(empty)* | Set to enable login (single user) |\n| `ADMIN_PASS` | *(empty)* | Password for ADMIN_USER |\n| `AUTH_PROXY_HEADER` | *(empty)* | Trusted header from reverse proxy (e.g. `Remote-User`) |\n| `VPN_ENABLED` | `true` | Enable/disable VPN |\n| `VPN_TYPE` | `auto` | VPN engine: `auto`, `wireguard`, or `openvpn` |\n| `VPN_PROVIDER` | `custom` | VPN provider: `custom` or `mullvad` |\n| `VPN_DNS` | *(from config)* | Override DNS server (default: provider DNS or `10.64.0.1`) |\n| `VPN_COUNTRY` | *(empty)* | Filter server rotation by country (e.g. `ch`, `us`) |\n| `VPN_CITY` | *(empty)* | Filter server rotation by city (e.g. `zurich`) |\n| `KILLSWITCH_ENABLED` | `true` | Enable nftables killswitch |\n| `WEBUI_PORT` | `8080` | qBittorrent WebUI port |\n| `API_PORT` | `8081` | TunnelVision API port |\n| `API_KEY` | *(empty)* | Set to require `X-API-Key` header on API calls |\n| `UI_ENABLED` | `true` | Serve the web dashboard |\n| `WEBUI_ALLOWED_NETWORKS` | `192.168.0.0/16,...` | Networks allowed to access WebUI and API |\n| `MQTT_ENABLED` | `false` | Enable MQTT with Home Assistant auto-discovery |\n| `MQTT_BROKER` | *(empty)* | MQTT broker hostname/IP |\n| `MQTT_PORT` | `1883` | MQTT broker port |\n| `MQTT_USER` / `MQTT_PASS` | *(empty)* | MQTT authentication |\n| `PUID` | `1000` | User ID for file permissions |\n| `PGID` | `1000` | Group ID for file permissions |\n| `TZ` | `America/Chicago` | Container timezone |\n| `HEALTH_CHECK_INTERVAL` | `30` | Seconds between health checks |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDocker requirements\u003c/summary\u003e\n\n```yaml\ncap_add:\n  - NET_ADMIN          # Required for WireGuard and nftables\ndevices:\n  - /dev/net/tun       # Required for WireGuard tunnel\nsysctls:\n  - net.ipv4.conf.all.src_valid_mark=1    # WireGuard routing\n  - net.ipv6.conf.all.disable_ipv6=1      # IPv6 leak prevention\n```\n\n| Volume | Purpose |\n|--------|---------|\n| `/config` | qBittorrent config, runtime state |\n| `/config/wireguard` | WireGuard config files (`wg0.conf`) |\n| `/downloads` | Torrent download directory |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAPI endpoints\u003c/summary\u003e\n\nInteractive docs at `http://localhost:8081/api/docs` (Swagger) when running.\n\n| Endpoint | What it returns |\n|----------|----------------|\n| `GET /api/v1/health` | Container health — VPN, killswitch, qBittorrent, uptime |\n| `GET /api/v1/vpn/status` | Full VPN status — IP, location, uptime, transfer stats |\n| `GET /api/v1/vpn/ip` | Just the public IP |\n| `GET /api/v1/vpn/check` | Provider-verified connection check |\n| `GET /api/v1/qbt/status` | Speeds, torrent counts, version |\n| `GET /api/v1/system` | Container versions and uptime |\n| `GET /api/v1/config` | Current configuration (no secrets) |\n| `GET /metrics` | Prometheus metrics |\n| `POST /api/v1/vpn/restart` | Restart VPN tunnel |\n| `POST /api/v1/vpn/rotate` | Rotate to a new server |\n| `POST /api/v1/vpn/disconnect` | Disconnect VPN |\n| `POST /api/v1/killswitch/enable` | Enable killswitch |\n| `POST /api/v1/killswitch/disable` | Disable killswitch |\n| `POST /api/v1/qbt/restart` | Restart qBittorrent |\n| `POST /api/v1/qbt/pause` | Pause all torrents |\n| `POST /api/v1/qbt/resume` | Resume all torrents |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eMigrating from other setups\u003c/summary\u003e\n\n**From gluetun + qBittorrent:** Copy your qBittorrent config directory and your WireGuard config. Point the volumes. Done.\n\n**From Trigus42/qbittorrentvpn:** Same config structure — mount `/config` and `/config/wireguard` the same way.\n\n**From transmission-openvpn:** You'll need to switch to qBittorrent. The VPN config carries over if it's WireGuard.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eArchitecture\u003c/summary\u003e\n\n```\n┌──────────────────────────────────────────────────────────┐\n│  TunnelVision Container                                  │\n│                                                          │\n│  ┌─────────────────┐  ┌──────────────┐  ┌────────────┐  │\n│  │  WireGuard VPN   │  │ qBittorrent  │  │ FastAPI    │  │\n│  │  + nftables      │  │   -nox       │  │ REST API   │  │\n│  │  killswitch      │  │              │  │ + React UI │  │\n│  └────────┬─────────┘  └──────┬───────┘  └─────┬──────┘  │\n│           │                   │                 │         │\n│           │    s6-overlay (process supervision)  │         │\n│           └───────────────────┼─────────────────┘         │\n│                               │                           │\n│  init-environment ──► init-wireguard ──► init-killswitch  │\n│           │                                     │         │\n│           └──► svc-qbittorrent    svc-api    svc-health   │\n│                                                           │\n│  Alpine Linux 3.21                                        │\n└──────────────────────────────────────────────────────────┘\n         │              │              │\n    :8080 (WebUI)  :8081 (API)    wg0 (tunnel)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eBuilding from source\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/jasondostal/tunnelvision.git\ncd tunnelvision\nmake build    # Build the Docker image\nmake dev      # Start development environment\n```\n\n\u003c/details\u003e\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasondostal%2Ftunnelvision","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasondostal%2Ftunnelvision","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasondostal%2Ftunnelvision/lists"}