Jak podłączyć się do Home Assistanta przez SSH

Problem

Home Assistant w wersji OS/Supervised nie ma domyślnie włączonego SSH. Webowy interfejs wystarcza do większości zadań, ale gdy trzeba podejrzeć logi, edytować configuration.yaml poza UI, uruchomić komendę ha, wejść do kontenera czy w ogóle do shella hosta — potrzebny jest SSH. Każda dystrybucja HA (OS, Container, Core) wymaga innego podejścia, a w HA OS są dwa różne dodatki SSH, które łatwo pomylić.

Home Assistant OS / Supervised

To najczęstszy scenariusz — HA działa na Raspberry Pi, mini PC, NUC albo w VM jako Home Assistant OS. SSH dodaje się jako add-on z poziomu UI. W sklepie znajdziesz dwa dodatki o podobnych nazwach, ale dość różne w możliwościach.

Terminal & SSH vs Advanced SSH & Web Terminal

Generowanie klucza SSH

Niezależnie od dodatku, do logowania potrzebujesz pary kluczy: prywatnego (zostaje na twojej maszynie) i publicznego (wgrywasz do HA). Klucze ed25519 są szybsze, krótsze i bezpieczniejsze niż RSA — używaj ich, chyba że masz stare narzędzia, które ich nie wspierają.

Linux / macOS

W terminalu:

$ssh-keygen -t ed25519 -C "ha-access"

Naciśnij Enter na pytanie o ścieżkę (domyślnie ~/.ssh/id_ed25519). Hasło do klucza opcjonalne — z hasłem bezpieczniej, bez hasła wygodniej (możesz też użyć ssh-agent, żeby mieć i jedno, i drugie).

Wyświetl klucz publiczny do wklejenia w konfiguracji dodatku:

$cat ~/.ssh/id_ed25519.pub

Skopiuj całą linijkę zaczynającą się od ssh-ed25519.

Windows — wbudowany OpenSSH (zalecane)

Współczesny Windows 10/11 ma wbudowany OpenSSH. W PowerShellu:

$ ssh-keygen -t ed25519 -C "ha-access"

Domyślna ścieżka to C:\Users\TwojaNazwa\.ssh\id_ed25519. Wyświetl klucz publiczny:

$ Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub

Format jest identyczny jak na Linuksie — gotowy do wklejenia.

Windows — PuTTYgen (jeśli używasz PuTTY)

Jeśli wolisz PuTTY, generuj klucz w PuTTYgen:

1. Otwórz PuTTYgen → wybierz EdDSA i Ed25519 (255 bits) na dole → Generate
2. Pomachaj myszką, żeby zebrać entropię
3. Opcjonalnie ustaw Key passphrase
4. Save private key → zapisz jako .ppk (do logowania PuTTY)
5. Skopiuj zawartość górnego pola "Public key for pasting into OpenSSH authorized_keys file" — to jest format dla HA

Logowanie do HA

Skopiowany klucz publiczny wklej w konfigurację dodatku (sekcja niżej). Po zainstalowaniu i uruchomieniu dodatku, łączysz się tak:

Linux / macOS

$ssh root@homeassistant.local -p 22222

(port 22 dla Advanced SSH). Jeśli .local nie działa w twojej sieci, użyj adresu IP:

$ssh root@192.168.1.50 -p 22222

Pierwszy raz potwierdź fingerprint pisząc yes. Jeśli masz wiele kluczy, wskaż konkretny:

$ssh -i ~/.ssh/id_ed25519 root@homeassistant.local -p 22222

Windows — wbudowany OpenSSH

Identycznie jak na Linuksie, w PowerShellu albo CMD:

$ ssh root@homeassistant.local -p 22222

Klient sam znajdzie klucz w %USERPROFILE%\.ssh\. Możesz też zapisać konfigurację w ~\.ssh\config, żeby nie wpisywać parametrów za każdym razem:

Host ha
    HostName homeassistant.local
    User root
    Port 22222
    IdentityFile ~/.ssh/id_ed25519

Wtedy logowanie to po prostu:

$ ssh ha

Windows — PuTTY

1. Otwórz PuTTY
2. Session → Host Name: homeassistant.local (lub IP), Port: 22222 (lub 22 dla Advanced)
3. Lewy panel: Connection → SSH → Auth → Credentials
4. Private key file for authentication → wskaż swój plik .ppk
5. Wróć do Session, w Saved Sessions wpisz nazwę (np. HA) i kliknij Save
6. Open — logujesz się jako root (PuTTY zapyta o user przy pierwszym połączeniu, albo ustaw w Connection → Data → Auto-login username)

Następnym razem wystarczy podwójny klik na zapisaną sesję.

Instalacja dodatku Terminal & SSH

W panelu HA: Settings → Add-ons → Add-on Store → Terminal & SSH → Install.

Po instalacji wejdź w zakładkę Configuration i ustaw klucz publiczny SSH zamiast hasła:

authorized_keys:
  - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@laptop"
password: ""
server:
  packages: []

W zakładce Info włącz Start on boot, Watchdog i Show in sidebar, potem kliknij Start.

Loguj się tak, jak opisano w sekcji o logowaniu — port 22222, użytkownik root. Trafisz do środowiska z komendami ha, core, addons, supervisor — to nie host, tylko kontener add-onu z zamontowanym /config.

Instalacja dodatku Advanced SSH & Web Terminal

Standardowo nie ma go w głównym repozytorium — musisz najpierw dodać community store. Wejdź Settings → Add-ons → ⋮ (trzy kropki w prawym górnym rogu) → Repositories i dodaj:

https://github.com/hassio-addons/repository

Po chwili w sklepie pojawi się Advanced SSH & Web Terminal. Zainstaluj.

Konfiguracja w Configuration:

ssh:
  username: root
  password: ""
  authorized_keys:
    - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@laptop"
  sftp: false
  compatibility_mode: false
  allow_agent_forwarding: false
  allow_remote_port_forwarding: false
  allow_tcp_forwarding: false
zsh: true
share_sessions: true
packages: []
init_commands: []

Logowanie identyczne jak przy oficjalnym dodatku, tyle że port 22 zamiast 22222.

Protection mode — klucz do hosta

To najważniejsza różnica między dodatkami. W Info Advanced SSH jest przełącznik Protection mode.

Włączony (domyślnie) — sandbox, nie masz docker, apk, systemctl. Działa praktycznie tak jak oficjalny dodatek.

Wyłączony — pełen dostęp do hosta HA OS przez gniazdo Dockera. Możesz:

$docker ps
$docker logs homeassistant -f
$docker exec -it homeassistant bash
$apk add htop iotop

Po przełączeniu Protection mode na OFF dodatek wymaga restartu.

Kiedy używać którego

W codziennej pracy — oficjalny Terminal & SSH. Edycja configuration.yaml, restart HA przez ha core restart, instalacja niestandardowego komponentu w /config/custom_components/. Sandbox wystarcza i jest bezpieczniejszy.

Wchodzisz w Advanced SSH (z Protection mode OFF), gdy:

• musisz zobaczyć co dzieje się w kontenerze homeassistant od strony hosta (docker stats, docker logs)
• HA wisi i potrzebujesz wymusić restart kontenera (docker restart homeassistant)
• chcesz odpalić py-spy, iotop, profiling
• diagnozujesz problemy z siecią, USB (dmesg, lsusb) albo kartą SD (iostat)
• musisz wyciągnąć/podłączyć dongle Zigbee bez wyłączania HA i sprawdzić co się dzieje

Home Assistant Container (Docker)

Tu nie ma dodatków — HA działa jako kontener Docker na twoim serwerze (NAS, mini PC, VPS). SSH konfigurujesz na poziomie systemu hosta, jak na każdej zwykłej maszynie:

$ssh user@192.168.1.50
$docker exec -it homeassistant bash

Wewnątrz kontenera masz pliki konfiguracyjne w /config. Jeśli chcesz tylko edytować config bez wchodzenia do kontenera, zamontuj /config na hoście (typowo -v /home/user/ha-config:/config w docker-compose.yml) i edytuj bezpośrednio.

Home Assistant Core

HA Core to instalacja w wirtualnym środowisku Pythona na zwykłym Linuksie (typowo jako użytkownik homeassistant). SSH działa jak na dowolnym serwerze:

$ssh user@192.168.1.50
$sudo -u homeassistant -H bash
$cd ~/.homeassistant
$source /srv/homeassistant/bin/activate

Stąd masz dostęp do configuration.yaml, możesz wywołać hass --script check_config czy restartować usługę przez sudo systemctl restart home-assistant@homeassistant.

Awaryjny dostęp do HA OS bez UI

Jeśli HA się nie uruchamia i nie masz jak zainstalować dodatku, można włączyć SSH na poziomie hosta przez kartę SD:

1. Wyjmij kartę SD/dysk z urządzenia
2. Zamontuj partycję hassos-boot na innym komputerze
3. Wgraj swój klucz publiczny jako authorized_keys w katalogu głównym partycji
4. Włóż kartę z powrotem i uruchom urządzenie

Port hosta to 22222, użytkownik root. To dostęp bezpośrednio do HA OS, nie do shella add-onu.

Montowanie partycji hassos-boot w Windows

Karta z HA OS ma kilka partycji w formacie GPT — hassos-boot to pierwsza, sformatowana jako FAT32 (~32 MB). W teorii Windows powinien ją widzieć w Eksploratorze, ale w praktyce ma z tym kłopoty: czytniki SD często pokazują tylko pierwszą partycję, Windows automatycznie ustawia karty z partycjami GPT i nieznanymi systemami plików (ext4) w tryb "offline", co blokuje dostęp przez WSL i wymaga walki z diskpart, polityką SAN i Virtual Disk Service.

Zamiast walczyć z mechanizmami Windows, sięgnij po DiskGenius — narzędzie, które rozmawia bezpośrednio z driverem dyskowym i ignoruje stan offline/online. Działa nawet z kartami, których Eksplorator nie widzi.

1. Pobierz DiskGenius Free ze strony producenta (diskgenius.com) — wersja Standard wystarczy
2. Uruchom jako administrator
3. W lewym panelu znajdź swoją kartę (po rozmiarze, typowo opisana jako "Mass Storage")
4. Rozwiń kartę → kliknij partycję hassos-boot (FAT32, ~32 MB, pierwsza od góry)
5. Prawy klik w prawym panelu (zawartość partycji) → Copy Files To Current Partition
6. Wskaż swój id_ed25519.pub i zmień nazwę na authorized_keys (bez rozszerzenia)
7. Disk → Save All Changes (Ctrl+S) — bez tego zmiany nie zostaną zapisane
8. Zamknij DiskGenius, bezpiecznie odłącz kartę przez Eksplorator

Alternatywa o tej samej klasie: MiniTool Partition Wizard Free. Działa identycznie i też omija mechanizmy offline Windowsa.

Co się dzieje pod spodem

Home Assistant OS to nie zwykły Linux — to HassOS, minimalna dystrybucja Buildroot, gdzie HA i wszystkie dodatki działają jako kontenery Docker zarządzane przez Supervisora. Każdy dodatek SSH to też kontener, który ma zamontowany /config i prosty serwer SSH wystawiony na swoim porcie. Dlatego logując się do oficjalnego Terminal & SSH nie jesteś na hoście — jesteś w odizolowanym kontenerze, który gada z Supervisorem przez gniazdo.

Advanced SSH z wyłączonym Protection mode dostaje mount /, dostęp do gniazda Dockera (/var/run/docker.sock) i prawo wywoływania komend hosta — stąd różnica w możliwościach. To w zasadzie pełnoprawny container z escape do hosta, kontrolowanym przez flagę Supervisora.

Dla codziennej pracy z configuration.yaml, automatyzacjami i logami oficjalny dodatek wystarczy w 99% przypadków. Advanced ma sens, gdy trzeba podejść pod podszewkę — wtedy bez niego ani rusz.