설치 가이드

HagiCode는 세 가지 설치 방식을 제공합니다. 먼저 사용 시나리오에 맞는 경로를 하나 고르고, 그 경로에 필요한 사전 요구 사항을 확인한 다음, 해당 설치 페이지로 이동합니다.

설치 방식 선택

사용 시나리오	권장 방식
Windows에서 개인 로컬 사용	Microsoft Store 설치
macOS / Linux에서 개인 로컬 사용, 또는 Windows에서 Store를 사용할 수 없는 경우	Desktop 설치
서버, NAS, 팀 공유, 또는 환경 격리가 필요한 경우	Docker Compose 설치

Microsoft Store 설치Windows에서 기본으로 권장하는 경로입니다. 공식 Store를 통해 설치하고 이후 업데이트도 받습니다.

Desktop 설치그래픽 인터페이스로 설치하고 관리합니다. macOS / Linux 사용자와 설치 패키지를 직접 내려받아야 하는 Windows 사용자에게 적합합니다.

Docker Compose 설치환경 격리, 통합 배포, 팀 협업이 필요한 시나리오에 적합합니다.

설치 전 준비

경로마다 필요한 사전 요구 사항이 다릅니다.

설치 방식	Node.js	Git
Microsoft Store / Desktop	24 이상 버전을 직접 설치해야 합니다	직접 설치해야 합니다
Docker Compose	호스트에 설치할 필요가 없습니다	호스트에 설치할 필요가 없습니다

Desktop은 더 이상 Node.js를 내장하지 않습니다

Desktop에는 HagiCode Server를 실행하는 데 필요한 .NET 런타임만 내장되어 있으며, Node.js는 더 이상 제공하지 않습니다. Desktop은 시스템 PATH에서 node와 npm을 찾고, Agent CLI 같은 관리 대상 패키지를 로컬 npm의 전역 디렉터리에 설치합니다. Desktop을 처음 실행하기 전에 Node.js 24 이상을 먼저 설치해야 합니다. 자세한 내용은 Node.js 설치를 참고하세요.

Git 설치

Desktop은 시작할 때 node, npm, git을 감지하며, 메인 화면의 “새 프로젝트” 대화상자에 있는 “데모 프로젝트”도 Git으로 공식 예제 저장소를 클론해야 합니다. 사용 중인 시스템에 맞는 방법 하나를 선택해 설치합니다.

Windows: winget install --id Git.Git -e를 실행하거나 git-scm.com에서 설치 프로그램을 내려받습니다.
macOS: xcode-select --install을 실행하거나 Homebrew로 brew install git을 실행합니다.
Debian / Ubuntu: sudo apt-get install -y git을 실행합니다.
Fedora: sudo dnf install -y git을 실행합니다.

설치가 끝나면 터미널을 다시 열고 명령을 사용할 수 있는지 확인합니다.

node --version
npm --version
git --version

설치를 마친 뒤에 Desktop을 시작하세요

Desktop은 시작할 때 시스템 PATH를 읽습니다. Desktop이 이미 열려 있는 상태에서 Node.js나 Git을 설치했다면 Desktop을 완전히 종료한 뒤 다시 시작하세요.

Agent CLI

HagiCode는 로컬 컴퓨터에 설치되어 있고 로그인까지 완료된 Agent CLI를 통해 동작합니다. 초기화 마법사에는 로컬에서 감지된 CLI만 표시되므로, 마법사에 들어가기 전에 최소 하나를 설치하고 로그인해 두어야 합니다. 현재 지원하는 CLI, 설치 방식, 공식 진입점은 AI Agent CLI 설치에서 통합 관리합니다.