diff --git a/docs/CLOUDFLARE_TUNNEL.md b/docs/CLOUDFLARE_TUNNEL.md
new file mode 100644
index 0000000..9c0d0e8
--- /dev/null
+++ b/docs/CLOUDFLARE_TUNNEL.md
@@ -0,0 +1,112 @@
+# Cloudflare Tunnel - Home Assistant
+
+## Cel
+Tunel Cloudflare umożliwia dostęp do Home Assistant przez internet bez otwierania portów na routerze.
+Adres publiczny: **https://ha.sky-it.pl**
+
+## Architektura
+
+```
+Internet
+   │
+   ▼
+Cloudflare Edge (ha.sky-it.pl)
+   │ QUIC/TLS
+   ▼
+cloudflared (192.168.50.244 LXC)
+   │ HTTP
+   ▼
+Home Assistant (192.168.50.151:8123)
+```
+
+## Infrastruktura
+
+| Komponent | Lokalizacja | Szczegóły |
+|-----------|-------------|-----------|
+| cloudflared | LXC 103, IP 192.168.50.244 | systemd service |
+| Tunel UUID | `514b8187-453f-45c3-878e-70fec451fc64` | nazwa: `ha-tunel` |
+| Hostname | `ha.sky-it.pl` | DNS zarządzany przez Cloudflare |
+| Backend | `http://192.168.50.151:8123` | HA bez TLS (ruch lokalny) |
+
+## Pliki konfiguracyjne (na .244)
+
+### `/etc/cloudflared/config.yml`
+```yaml
+tunnel: 514b8187-453f-45c3-878e-70fec451fc64
+credentials-file: /etc/cloudflared/514b8187-453f-45c3-878e-70fec451fc64.json
+
+ingress:
+  - hostname: ha.sky-it.pl
+    service: http://192.168.50.151:8123
+  - service: http_status:404
+```
+
+### `/etc/cloudflared/514b8187-...json`
+Plik credentials tunelu (nie commitować do repo - zawiera klucz prywatny).
+
+## Serwis systemd
+
+```bash
+systemctl status cloudflared
+systemctl restart cloudflared
+journalctl -u cloudflared -f
+```
+
+## Konfiguracja HA - trusted proxies
+
+W `/config/configuration.yaml` na HA (.151) musi być:
+
+```yaml
+http:
+  use_x_forwarded_for: true
+  trusted_proxies:
+    - 127.0.0.1
+    - ::1
+    - 192.168.50.244   # LXC z cloudflared
+    - 172.16.0.0/12
+    - 10.0.0.0/8
+    - 192.168.0.0/16
+```
+
+**Bez tej konfiguracji HA zwraca 400 Bad Request** - odrzuca żądania z niezaufanych proxy.
+
+## Zdrowie tunelu
+
+Sprawdzenie statusu połączeń z Cloudflare Edge:
+```bash
+curl http://127.0.0.1:20241/ready
+# Oczekiwana odpowiedź: {"status":200,"readyConnections":4,...}
+```
+
+Powinny być **4 aktywne połączenia** do edge nodes (np. prg01, prg03, waw02, waw05).
+
+## Historia
+
+| Data | Zmiana |
+|------|--------|
+| przed migracją | Docker container `cloudflared` na 192.168.50.243, backend 192.168.50.243:8123 |
+| 2026-03-02 | Przeniesiony na LXC 103 (192.168.50.244) jako systemd service, backend zmieniony na 192.168.50.151:8123 |
+
+## Zarządzanie przez Cloudflare Dashboard
+
+Panel: https://one.dash.cloudflare.com → Networks → Tunnels
+
+Widoczne są aktywne connectory i ich lokalizacje.
+
+## Rozwiązywanie problemów
+
+### 400 Bad Request
+Sprawdź czy w `configuration.yaml` HA jest sekcja `http.trusted_proxies` z IP `.244`.
+
+### Tunel offline
+```bash
+ssh root@192.168.50.244
+systemctl restart cloudflared
+curl http://127.0.0.1:20241/ready
+```
+
+### Brak połączeń (readyConnections: 0)
+Sprawdź łączność .244 z internetem:
+```bash
+curl -I https://cloudflare.com
+```