A secure WebSocket tunnel to expose Home Assistant to Amazon Alexa and Google Assistant without requiring port forwarding or a public IP address.
Alexa/Google ──▶ HA Tunnel Server (public) ◀──WebSocket──▶ HA Tunnel Client ──▶ Home Assistant
(cloud) (local) (local)
The server runs on a publicly accessible host and receives requests from Alexa/Google. The client runs locally alongside Home Assistant, maintains a persistent WebSocket connection to the server, and proxies requests to your local HA instance.
The easiest way to install the client is as a Home Assistant add-on.
-
Add the repository to Home Assistant:
Or manually add the repository URL:
https://github.com/fkrauthan/ha-tunnel -
Install the "HA Tunnel Client" add-on
-
Configure the add-on with your server URL and secret
-
Start the add-on
-
Update
configuration.yaml
configuration.yaml
Since Home Assistant blocks requests from proxies/reverse proxies, you need to tell your instance to allow requests from the HA Tunnel Client app (add-on). The app (add-on) runs locally, so HA has to trust the docker network. In order to do so, add the following lines to your /config/configuration.yaml:
Note: There is no need to adapt anything in these lines since the IP range of the docker network is always the same.
http:
use_x_forwarded_for: true
trusted_proxies:
- 172.30.33.0/24If you are using non-standard hosting methods of HA (e.g. Proxmox), you might have to add another IP(range) here. Check your HA logs after attempting to connect to find the correct IP.
Both server and client are available as Docker images:
# Server
docker pull ghcr.io/fkrauthan/ha-tunnel-server:latest
# Client
docker pull ghcr.io/fkrauthan/ha-tunnel-client:latest# Build both binaries
cargo build --release
# Binaries are located at:
# target/release/ha-tunnel-server
# target/release/ha-tunnel-clientThe server must be hosted on a publicly accessible machine (cloud VPS, etc.).
docker run -d \
-p 3000:3000 \
-e HA_TUNNEL_SECRET="your-secure-secret" \
ghcr.io/fkrauthan/ha-tunnel-server:latestCreate a config.toml file or use environment variables (prefixed with HA_TUNNEL_):
# Server config.toml
secret = "your-secure-secret" # Required: shared secret for client authentication
host = "0.0.0.0" # Default: 0.0.0.0
port = 3000 # Default: 3000
client_timeout = 10 # Seconds to wait for client connection
request_timeout = 30 # Seconds to wait for client response
log_level = "INFO" # TRACE, DEBUG, INFO, WARN, ERROR
# Proxy settings (for extracting real client IP)
proxy_mode = "none" # none, x-forwarded-for, cloudflare, x-real-ip, true-client-ip, forwarded, or custom header name
trusted_proxies = [] # List of trusted proxy IPs (empty = trust all)docker run -d \
-e HA_TUNNEL_SERVER="https://your-server.example.com" \
-e HA_TUNNEL_SECRET="your-secure-secret" \
-e HA_TUNNEL_HA_SERVER="http://homeassistant:8123" \
ghcr.io/fkrauthan/ha-tunnel-client:latestCreate a config.toml file or use environment variables (prefixed with HA_TUNNEL_):
# Client config.toml
server = "https://your-server.example.com" # Required: server WebSocket URL
secret = "your-secure-secret" # Required: must match server
ha_server = "http://localhost:8123" # Required: local Home Assistant URL (or "DETECT" for add-on)
ha_external_url = "https://your-ha.domain.com" # External URL for OAuth redirects
# Optional settings
assistant_alexa = true # Enable Alexa integration (default: true)
assistant_google = true # Enable Google Assistant integration (default: true)
ha_timeout = 10 # Request timeout to HA in seconds (default: 10)
ha_ignore_ssl = false # Ignore SSL certificate errors for HA (default: false, auto-enabled with DETECT)
ha_pass_client_ip = false # Pass client IP to HA via X-Forwarded-For header (default: false)
reconnect_interval = 5 # Reconnection delay in seconds (default: 5)
heartbeat_interval = 30 # Heartbeat interval in seconds (default: 30)
log_level = "INFO" # TRACE, DEBUG, INFO, WARN, ERROR (default: INFO)- Create an Alexa Smart Home skill in the Amazon Developer Console
- Set the Lambda endpoint to:
https://your-server.example.com/api/alexa/smart_home - Configure account linking with your Home Assistant OAuth settings
- Enable the skill and link your account
- Create a project in Actions on Google Console
- Set the fulfillment URL to:
https://your-server.example.com/api/google_assistant - Configure OAuth account linking
- Test and publish your action
- Client authentication uses HMAC-SHA256 signatures with a shared secret
- Timestamps are validated within a 60-second window to prevent replay attacks
- All communication should use TLS (wss:// for WebSocket, https:// for HTTP)
- Use a strong, unique secret for production deployments
# Run tests
cargo test
# Format code
cargo fmt
# Lint
cargo clippy
# Build Docker images locally
docker build -t ha-tunnel-server -f server/Dockerfile .
docker build -t ha-tunnel-client -f client/Dockerfile .MIT License