HA NOVA: 하나의 코드로 연결하고, 모든 변경 사항을 확인하는 시스템

curl -fsSL https://raw.githubusercontent.com/markusleben/ha-nova/main/install.sh | bash

설치 프로그램이 최신 안정화 버전을 선택합니다. 사용 중인 OS에 맞는 명령어를 실행하면 마법사가 Home Assistant를 감지하고 NOVA Relay App 설치 과정을 안내하며 AI 클라이언트를 구성해 줍니다. 페어링 단계에서는 자동으로 Home Assistant를 열어줍니다. 사이드바에서 **NOVA**를 열거나 (또는 앱 페이지의 "Open Web UI"에서) **"Connect a device"**를 클릭한 후, 여섯 자리 코드를 입력하면 완료됩니다.

### Home Assistant Cloud를 사용한 선택적 원격 액세스 (베타)

마법사는 기본 권장 설정으로 **Local only**를 유지합니다. Nabu Casa에서 Remote UI가 활성화된 유료 Home Assistant Cloud 구독을 사용하는 경우, 자동 원격 폴백(fallback)을 위해 **Local + Home Assistant Cloud**를 선택하거나, 원격 우선(remote-first) 설정을 위해 **Home Assistant Cloud only**를 선택하십시오. 마법사는 클라우드 URL을 검증하고, Home Assistant OAuth를 열며, 인증 정보를 네이티브 macOS, Windows 또는 Linux 데스크톱 자격 증명 저장소에 저장합니다. HA NOVA는 추가적인 공개 터널이나 호스팅된 브로커를 실행하지 않습니다.

Cloud Remote는 인증을 위해 Home Assistant OS/Supervised 및 지원되는 데스크톱 세션을 필요로 합니다. 중단되었거나 이미 검증된 설정은 `ha-nova cloud add --remote-resume`를 사용하여 SSH를 통해 완료할 수 있습니다. Headless, WSL, service, gateway, Container, 그리고 Core 설정은 local-only로 유지됩니다. 원격 우선 페어링은 별도의 비공개 Owner 세션을 사용하여 일회성 NOVA 장치 코드를 생성하며, OAuth 사용자는 표준 Home Assistant 사용자로 남을 수 있습니다.

이미 로컬에 설치되어 있습니까? `ha-nova cloud add`를 실행하거나, 동일한 안내 선택을 위해 `ha-nova setup`을 다시 실행하십시오.

<p align="center">
  <img src="https://raw.githubusercontent.com/markusleben/ha-nova/HEAD/assets/cloud-fallback.png" alt="Local first, Cloud fallback: at home your machine reaches Home Assistant over the direct local connection; away, the same session falls back through your Home Assistant Cloud remote access.">
</p>

*로컬 연결을 우선합니다: CLI는 직접 연결을 선호하며, Home Assistant Cloud 원격 접근은 자동 폴백(automatic fallback)으로만 사용됩니다. 수동 URL 전환이 필요하지 않습니다.*

작업 완료 후 다음 명령어를 시도해 보세요: *"내 모든 자동화를 보여줘."*

> **Home Assistant가 여러 개인가요?** 추가 인스턴스는 `ha-nova pair --server <이름> --relay-url http://<ha-호스트>:8791`로 추가하세요. 서버마다 고유 프로필과 격리된 자격 증명이 부여됩니다. 릴레이 호출 시 `--server <이름>` 플래그나 `HA_NOVA_SERVER` 환경 변수를 사용하여 하나를 선택하고, `ha-nova server list|default|rename|remove`로 프로필을 관리하세요.

> **이전 HA NOVA 버전에서 업그레이드하는 경우?** 모든 것이 업데이트를 통해 계속 작동합니다. 장치별 페어링으로 이동하려면 각 컴퓨터를 한 번씩 재페어(re-pair)해야 합니다(각각 고유 코드 사용). 준비가 되면 NOVA 페이지에서 이전 공유 접근 권한을 취소하세요.

<details>
<summary><strong >플랫폼 참고 사항</strong ></summary>

<br>

**macOS** — 실제 하드웨어에서 검증된 엔드투엔드(end-to-end) 기능입니다.

**Linux** — 헤드리스 설정(서버, 컨테이너, LXC, SSH 포함)을 포함하여 엔드투엔드가 검증되었습니다. 데스크톱 키링이 없으면 장치 자격 증명은 자동으로 개인 파일로 폴백됩니다. 이러한 시스템에서 독립형 릴레이(relay 토큰, 장치 페어링 없음)는 `ha-nova setup --service <클라이언트>`를 사용합니다 (Codex CLI, OpenCode, Hermes Agent).

**Windows** — 실제 Windows 11 시스템에서 검증된 엔드투엔드 기능입니다. x64 빌드를 제공하며(Windows ARM64는 에뮬레이션을 통해 x64 빌드를 사용할 수 있습니다. 네이티브 ARM64 번들은 제공되지 않습니다). 
- Claude Code가 현재 Windows에서 가장 많이 테스트된 클라이언트입니다.
- Google Antigravity는 기본적인 유효성 검사를 지원합니다.
- Codex와 OpenCode는 아직 초기 단계입니다.
- 필수 전제 조건: Claude Code는 Git for Windows / Git Bash가 필요하며, Google Antigravity Desktop 또는 CLI를 설치해야 합니다.
- [**.claude/INSTALL.md](.claude/INSTALL.md)** 및 [**.antigravity/INSTALL.md](.antigravity/INSTALL.md)**를 참조하세요.

⚠️ `[IMG:N]` 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

> `ha-nova-installer-bundle-*.tar.gz` / `.zip` 에셋을 수동으로 다운로드하지 마십시오. 해당 아카이브는 설치 프로그램 내부에서 사용됩니다. 항상 원라인 명령어 또는 `ha-nova update`를 사용하십시오.

</details>

<details>
<summary><strong
g지명: CLI 명령 및 레거시 제거</strong></summary>

<br>

| 명령어 | 기능 |
|:--------|:-------------|
| `ha-nova check-update` | 최신 버전 확인 |
| ... | 
**Go 이전 설치에서 오셨나요?**
- macOS / Linux: `curl -fsSL https://raw.githubusercontent.com/markusleben/ha-nova/main/scripts/legacy-uninstall.sh | bash`
- Windows: `irm https://raw.githubusercontent.com/markusleben/ha-nova/main/scripts/legacy-uninstall.ps1 | iex`

</details>

> **터미널 사용에 익숙하지 않으신가요?** 설정은 복사하여 붙여넣기만 하면 되는 단일 명령어입니다. 그 후에는 Claude Desktop과 Google Antigravity Desktop이 앱 창에서 동일한 기능을 제공하며, 다른 컴퓨터와 페어링하는 것은 단지 또 하나의 6자리 코드만 필요합니다.

---

## ⚙️ 작동 방식