Home Assistant에 SSH로 접속하는 방법(OS, Container, 휴대폰에서)

Home Assistant에 SSH로 접속하는 방법

"Home Assistant에 SSH 접속"에는 두 가지 계층이 있으며, 이를 혼동하는 것이 흔한 혼란의 원인입니다. Home Assistant OS에서는 호스트에 직접 SSH 접속하지 않고, SSH 애드온을 설치합니다. 이를 통해 Home Assistant 환경으로 들어가 설정을 편집하고 ha 명령을 실행할 수 있습니다. Container/Core/Supervised 설치에서는 평소처럼 하위 Linux 호스트에 SSH 접속합니다. 이 글은 두 경우 모두와, 휴대폰에서 하는 방법을 다룹니다.

Home Assistant OS ── SSH 애드온 사용

1. Home Assistant에서 설정 → 애드온 → 애드온 스토어로 이동합니다.
2. "Terminal & SSH"(공식) 또는 "Advanced SSH & Web Terminal"(커뮤니티, 더 유연함)을 설치합니다.
3. 애드온의 구성 탭을 열어 비밀번호를 설정하거나, 더 권장되는 방법으로 authorized_keys 아래에 SSH 공개 키를 추가합니다.
4. 포트를 설정하고(advanced 애드온은 기본값 22, 공식 애드온은 웹 터미널과 선택적 SSH 사용) 애드온을 시작합니다.

이제 아무 SSH 클라이언트에서나 HA 장비의 IP와 해당 포트, 사용자 이름 root(advanced 애드온)로 접속합니다. 그러면 Home Assistant 셸에 들어가게 되고, /config 폴더가 바로 그 자리에 있습니다.

Container / Core / Supervised ── 호스트에 SSH 접속

Home Assistant를 Docker로 실행하거나 자신의 Linux 장비에 Core로 설치한 경우, 애드온 계층이 없습니다. 평소대로 그 호스트에 SSH 접속한 뒤(호스트 IP, 포트 22, 자신의 사용자), 컨테이너나 config 디렉터리를 직접 다루면 됩니다.

휴대폰에서 하기

여기서 진가가 발휘됩니다 ── 소파에 앉아서, 또는 외출 중에 스마트홈을 고칠 수 있습니다. SSH 클라이언트를 설치하고(iPhone 선택지 / Android 선택지), HA의 IP와 포트로의 연결을 추가한 뒤 접속합니다.

유용한 Home Assistant SSH 명령

• ha core check ── 재시작 전에 설정을 검증
• ha core restart ── Home Assistant 재시작
• ha core logs ── 로그를 따라가며 문제를 디버깅
• nano /config/configuration.yaml ── 메인 설정 편집
• ha su update / ha core update ── supervisor / core 업데이트

정확한 ha 하위 명령이 기억나지 않을 때는, 하고 싶은 일을 TermAI 어시스턴트에게 설명하면 제안해 줍니다 ── 휴대폰에서 디버깅할 때 유용합니다.

ha core logs -f(또는 Container 호스트에서는 journalctl -f)로 로그를 따라가며 오토메이션이 작동하는 것을 지켜볼 때, TermAI는 로그 스트림 모드로 전환됩니다. 툴바에서 흐름을 일시 정지하거나, 최근 500줄을 오류와 경고를 색상으로 구분해 필터링하거나, 최근 100줄을 AI에 넘겨 "이 오토메이션이 왜 실패했나?"를 빠르게 파악할 수 있습니다. 휴대폰에서 HA 로그가 스크롤되는 것을 지켜보는 것보다 훨씬 덜 고통스럽습니다.

네트워크 밖에서 Home Assistant에 SSH 접속

외부에서 HA에 접근하려고 SSH 포트를 인터넷으로 포워딩하지 마세요 ── 스마트홈 허브를 노출시키게 됩니다. HA 장비와 휴대폰에 Tailscale을 설치하거나(Home Assistant용 애드온이 있습니다) TermAI 내장 Tailscale을 사용하면, 어디서나 비공개 주소로 Home Assistant에 SSH 접속할 수 있습니다. iPhone의 Tailscale을 참고하세요.

자주 묻는 질문

왜 Home Assistant OS에 직접 SSH로 접속할 수 없나요?
HA OS는 잠긴 어플라이언스입니다. 호스트 셸은 일상적 사용을 위한 것이 아닙니다. 대신 SSH 애드온이 지원되는 방식으로 Home Assistant 환경에 대한 셸을 제공합니다.

어떤 사용자 이름을 사용하나요?
Advanced SSH & Web Terminal 애드온에서는 root입니다. Container/Core 호스트에서는 일반 Linux 사용자입니다.

원격으로 Home Assistant에 SSH 접속하려면?
포트 포워딩 대신 Tailscale(HA용 애드온이 있습니다)을 사용한 뒤 HA의 비공개 주소로 접속하세요.

핵심 요약

• HA OS: Terminal & SSH 또는 Advanced SSH 애드온 설치 ── 호스트에 직접 SSH 하지 않기
• Container/Core: 하위 Linux 호스트에 평소대로 SSH 접속
• 핵심 명령: ha core check, ha core restart, ha core logs
• 휴대폰에서: 아무 SSH 클라이언트나 사용. TermAI가 ha 명령에 대한 AI 도움을 추가
• 원격 접근: 포트 포워딩이 아닌 Tailscale