https://github.com/jasondostal/tunnelvision-ha
Home Assistant HACS integration for TunnelVision VPN containers
https://github.com/jasondostal/tunnelvision-ha
hacs home-assistant killswitch qbittorrent vpn wireguard
Last synced: 4 months ago
JSON representation
Home Assistant HACS integration for TunnelVision VPN containers
- Host: GitHub
- URL: https://github.com/jasondostal/tunnelvision-ha
- Owner: jasondostal
- License: gpl-3.0
- Created: 2026-03-03T05:47:25.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-03T20:48:07.000Z (4 months ago)
- Last Synced: 2026-03-04T00:23:09.355Z (4 months ago)
- Topics: hacs, home-assistant, killswitch, qbittorrent, vpn, wireguard
- Language: Python
- Size: 194 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
---
Native Home Assistant integration for [TunnelVision](https://github.com/jasondostal/tunnelvision). 33 entities, real-time SSE updates, HTTPS support, config flow, zero YAML.
## Install
### HACS (Recommended)
1. Open Home Assistant → HACS → Integrations
2. Click the three dots (top right) → **Custom Repositories**
3. Paste `https://github.com/jasondostal/tunnelvision-ha`
4. Select category **Integration** → click **Add**
5. Close the dialog → search for **TunnelVision** in the HACS store
6. Click **Download** → **Restart Home Assistant**
### Manual
1. Download the [latest release](https://github.com/jasondostal/tunnelvision-ha/releases)
2. Copy the `custom_components/tunnelvision/` folder into your HA `config/custom_components/` directory
3. Restart Home Assistant
## Setup
**Settings → Integrations → Add → TunnelVision** → enter host + port. Done.
If TunnelVision is behind a reverse proxy with TLS, check **Use HTTPS** and optionally uncheck **Verify SSL certificate** for self-signed certs.
> **Tip:** If HA runs in `network_mode: host`, use your server IP and the mapped port (e.g. `192.168.1.x:8181`). If HA is on the same Docker network, use the container name and internal port (e.g. `tunnelvision:8081`).
## What You Get
**16 sensors** — VPN state, public IP, country, city, location, download/upload speed, active/total torrents, total downloaded/uploaded, provider, forwarded port, DNS state, HTTP proxy state, SOCKS proxy state
**7 binary sensors** — VPN connected, killswitch active, healthy, qBittorrent running, DNS, HTTP proxy, SOCKS proxy
**5 buttons** — Restart VPN, rotate server, restart qBit, pause/resume torrents
**2 switches** — VPN on/off, Killswitch on/off (reflect actual state)
**3 services** — For automations:
```yaml
service: tunnelvision.vpn
data:
action: restart # disconnect, reconnect, rotate
service: tunnelvision.qbittorrent
data:
action: restart # pause, resume
service: tunnelvision.killswitch
data:
action: enable # disable
```
## Automations
Notify when VPN drops
```yaml
automation:
- alias: "TunnelVision VPN Down"
trigger:
- platform: state
entity_id: binary_sensor.tunnelvision_vpn_connected
to: "off"
action:
- service: notify.mobile_app
data:
title: "VPN Down"
message: "TunnelVision VPN disconnected"
```
Auto-reconnect after 1 minute
```yaml
automation:
- alias: "TunnelVision Auto-Reconnect"
trigger:
- platform: state
entity_id: binary_sensor.tunnelvision_vpn_connected
to: "off"
for: "00:01:00"
action:
- service: tunnelvision.vpn
data:
action: reconnect
```
Rotate server daily at 4am
```yaml
automation:
- alias: "TunnelVision Daily Rotation"
trigger:
- platform: time
at: "04:00:00"
action:
- service: tunnelvision.vpn
data:
action: rotate
```
Pause torrents when VPN drops
```yaml
automation:
- alias: "TunnelVision Pause on VPN Drop"
trigger:
- platform: state
entity_id: binary_sensor.tunnelvision_vpn_connected
to: "off"
action:
- service: tunnelvision.qbittorrent
data:
action: pause
```
## MQTT Alternative
TunnelVision also supports **MQTT with auto-discovery**. Set `MQTT_ENABLED=true` in your TunnelVision container and entities appear in HA without this integration. Use whichever method fits your setup — this integration uses direct API polling (every 15s), MQTT provides real-time push.
## License
[GPL-3.0](LICENSE)