[HomeLabs] Proxmox에 Home Assistant 올리기 ① — 설치부터 SmartThings 연동까지

환경 정보

항목	버전/사양
Proxmox VE	8.x
Home Assistant OS	17.1 (Stable)
Home Assistant Core	2026.3.x
홈랩 하드웨어	i5-8500 / 16GB RAM / 12TB RAID5
HAOS VM 할당	2 vCPU / 4GB RAM / 32GB Disk
SmartThings Hub	V3
연동 기기 수	31개

---

배경

SmartThings로 집 안 기기가 30개를 넘기니까 한계가 보이기 시작했다. 삼성 가전(TV, 세탁기, 건조기, 냉장고)부터 커튼, 조명, 도어센서까지 다 연결해놨는데, SmartThings 앱의 자동화 빌더만으로는 복잡한 시나리오를 만들기 어려웠다. 예를 들어 "아이 방 3개를 평일 밤 10시에 자동 소등하면서 세탁 완료 시 텔레그램으로 알림" 같은 건 SmartThings만으로는 한계가 있다.

그래서 이미 Proxmox로 홈랩을 운영하고 있으니, 여기에 Home Assistant를 VM으로 올려서 통합 제어 환경을 구축하기로 했다.

---

1. HAOS VM 설치 — Community Helper Script

Home Assistant를 Proxmox에 설치하는 방법은 여러 가지가 있지만, 커뮤니티 Helper Script를 쓰면 명령어 한 줄로 끝난다. 이 스크립트는 원래 tteck이라는 개발자가 만들었는데, 현재는 커뮤니티에서 유지보수하고 있다.

Proxmox Shell 열기

Proxmox 웹 UI(https://서버IP:8006)에서 노드(pve) 선택 → 오른쪽 상단 Shell 클릭.

⚠️ SSH가 아니라 반드시 웹 UI의 Shell을 사용해야 한다. 스크립트가 SSH 환경에서는 정상 동작하지 않을 수 있다.

스크립트 실행

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/vm/haos-vm.sh)"

실행하면 대화형 메뉴가 나온다.

설치 옵션 선택

질문	선택
Create New Home Assistant OS VM?	Yes (Enter)
Use default settings?	Yes (초보자 권장)

기본값으로 진행하면 2 vCPU, 4GB RAM, 32GB 디스크로 VM이 생성된다. 나중에 Proxmox 웹 UI에서 얼마든지 변경 가능하니 기본값으로 충분하다.

잠시 기다리면 아래 메시지가 나온다:

✓ Completed Successfully!

VM 부팅 확인

Proxmox 왼쪽 사이드바에서 노드 옆 ▶ 화살표를 펼치면 새로 생성된 HAOS VM이 보인다. VM을 클릭하고 Console 탭에서 부팅 상태를 확인한다.

Welcome to Home Assistant
homeassistant login:
ha >

IP 주소 확인:

ha network info

2. Home Assistant 초기 설정

브라우저에서 http://HA의IP:8123 으로 접속한다.

첫 접속 시 "Preparing Home Assistant" 화면이 나오면서 5~20분 정도 초기 설정이 진행된다. Docker 컨테이너, Supervisor 등을 내부적으로 구성하는 과정이니 기다리면 된다.

계정 생성

"Create my smart home" 버튼 → 이름, 사용자명, 비밀번호 설정.

집 위치 및 기본 설정

지도에서 집 위치 설정 → 단위 확인(섭씨, km) → 기기 자동 감지(나중에 해도 됨).

여기까지 하면 HA 메인 대시보드가 나타난다.

---

3. 필수 앱 설치 (구 Add-on)

참고: HA 2026.2부터 Add-on이 "앱(Apps)"으로 이름이 바뀌었다. 기능은 완전히 동일하고 라벨만 변경된 것이니 혼동하지 말자. 기존 블로그 글들에서 "애드온"이라고 부르는 것이 설정 메뉴의 "앱"이다.

File Editor 설치

설정(Settings) → 앱(Apps) → 앱 스토어에서 "File editor" 검색 → 설치 → 시작.

"부팅 시 자동 시작"과 "사이드바에 표시"를 활성화한다.

---

4. HACS 설치 — 가장 중요한 단계

HACS(Home Assistant Community Store)는 커스텀 통합, 테마, 프론트엔드 카드를 설치할 수 있는 비공식 앱스토어다. Mushroom Cards, 네이버 날씨 같은 필수 컴포넌트를 여기서 설치한다.

4-1. HACS 앱 저장소 추가

설정 → 앱 → 우측 상단 ⋮ → 저장소(Repositories) → 아래 URL 추가:

4-2. Get HACS 앱 설치 및 실행

앱 → 앱 설치 → "Get HACS" 찾기 → 설치 → 시작 → 로그 탭에서 완료 확인.

4-3. HA 재시작 + 브라우저 하드 리프레시

설정 → 시스템 → ⋮ → 재시작.

⚠️ 재시작 후 반드시 Ctrl + Shift + R (하드 리프레시)를 해야 한다. 캐시를 지우지 않으면 HACS가 통합 목록에 나타나지 않는다.

4-4. HACS 통합 추가

설정 → 기기 및 서비스 → 우측 하단 "+ 통합 추가" → HACS 검색 → 선택.

4-5. 약관 체크 + GitHub 인증

1. 체크박스 모두 체크 → 제출
2. 화면에 나타난 8자리 코드를 메모
3. https://github.com/login/device 열기
4. GitHub 로그인 → 코드 입력 → Authorize HACS 클릭
5. 탭 닫고 HA로 돌아오기

사이드바에 HACS 메뉴가 나타나면 성공!

---

5. SmartThings 연동

HA에 내장된 공식 SmartThings 통합을 사용한다. 삼성 계정으로 로그인하면 기기가 자동으로 가져와진다.

연동 절차

1. 설정 → 기기 및 서비스 → "+ 통합 추가" → SmartThings 검색
2. 삼성 계정 로그인
3. 위치(Location) 선택 → 권한 모두 허용
4. 연동 완료 — 기기 자동 추가

SmartThings 앱에서 기기가 "Connected" 상태인지 미리 확인하자. 오프라인 기기는 HA에서도 인식되지 않는다.

연동된 기기 — 총 31개

영역	기기
거실 (9개)	우물조명, 커튼조명, 쇼파 다운라이트, 쇼파 무드등, TV 다운라이트, TV, 커튼×2, 카메라
주방 (7개)	메인등, 식탁등, 우물조명, 냉장고, 김치냉장고, 쿡탑, 큐커
아이방 (4개)	세아방 등, 세현이방 등, 수현이방 등, 장식장 LED
안방 (5개)	멀티탭, 청소기 멀티탭, 3D프린터 팬, 환풍기팬, 에어컨
세탁실 (2개)	세탁기, 건조기
현관 (1개)	도어센서
기타 (3개)	허브(V3), 나스, 거실 에어컨

하나 주의할 점이 있다. SmartThings에서 가져온 조명 대부분이 light가 아니라 switch로 등록된다. 나중에 대시보드를 만들 때 light.XXX가 아니라 switch.XXX로 entity를 잡아야 한다. 이 부분 때문에 처음에 살짝 헤맸다.

---

6. Mushroom Cards + 네이버 날씨 설치

Mushroom Cards

HACS → 검색 → "Mushroom" → DOWNLOAD → HA 재시작.

Mushroom Cards는 HACS 다운로드 수 440만 이상으로, HA에서 가장 인기 있는 대시보드 카드다. YAML 편집 없이 GUI로 깔끔한 카드를 만들 수 있다.

네이버 날씨

기상청 RSS 서비스가 2025년 2월에 종료되어 기존 기상청 기반 통합은 동작하지 않는다. 대신 네이버 날씨 커스텀 통합을 사용한다.

HACS 기본 목록에는 없으므로 Custom Repository로 추가해야 한다:

1. HACS → ⋮ → Custom repositories
2. URL: https://github.com/miumida/naver_weather
3. Category: Integration → 추가
4. HACS에서 "네이버 날씨" 검색 → 다운로드 → HA 재시작
5. 설정 → 기기 및 서비스 → 통합 추가 → 네이버 날씨 → 지역 입력 (예: "화성시")

네이버 날씨는 weather.* 엔터티가 아니라 sensor.*로 생성된다. 대시보드에서 날씨 카드를 추가할 때 이 점을 기억해두자.

---

7. 트러블슈팅

Add-on 메뉴가 없다?

HA 2026.2부터 "Add-on"이 "앱(Apps)"으로 이름이 바뀌었다. 설정 메뉴에서 "앱 — Home Assistant와 함께 추가 애플리케이션을 실행"이 바로 그 메뉴다.

HACS가 통합 목록에 안 보인다?

Get HACS 앱 설치 → HA 재시작까지 했는데도 안 보이면, 브라우저에서 Ctrl + Shift + R로 하드 리프레시. 캐시 때문에 안 보이는 경우가 대부분이다.

네이버 날씨 카드가 "엔터티를 찾을 수 없음"

weather.naver_weather가 아니라 sensor.naver_weather_XXX_nalssi_hyeonjaenalssi 같은 형태로 생성된다. 개발자 도구 → 상태 → "weather"로 검색하면 실제 entity_id를 확인할 수 있다.

---

마무리

Proxmox에 HAOS VM을 올리고, HACS 설치, SmartThings 31개 기기 연동, Mushroom Cards와 네이버 날씨까지 세팅했다. 직접 해보니 Community Helper Script 덕분에 VM 생성 자체는 5분이면 끝나고, 진짜 시간이 걸리는 건 HACS 설치와 기기 연동 설정이었다.

특히 SmartThings 기기가 switch로 등록되는 부분, 네이버 날씨가 sensor로 들어가는 부분은 미리 알고 있으면 삽질을 줄일 수 있다.

다음 편에서는 이 기기들로 실제 대시보드를 만드는 과정(Entity ID 찾는 법, Mushroom Cards YAML 작성, 7탭 대시보드 구성)을 다룬다.

---

참고 링크

• Community Helper Scripts
• Home Assistant 공식 문서
• HACS 공식 사이트
• Mushroom Cards GitHub
• 네이버 날씨 통합 GitHub

---

메타 설명: Proxmox VE에 Home Assistant OS를 VM으로 설치하고, HACS와 SmartThings 31개 기기를 연동하는 전 과정을 정리했습니다. Community Helper Script로 5분 만에 설치하고 실제 겪은 트러블슈팅까지 포함합니다.