Desktop 설치

이 페이지에서는 Hagicode Desktop을 설치하고 사용하는 방법을 설명합니다. Hagicode Desktop은 공식 데스크톱 클라이언트로, 기본 로컬 설치 흐름과 일상적인 관리 기능을 한곳에 모아 제공합니다.

권장 방식

macOS, Linux, 그리고 Store를 사용하지 않는 Windows 사용자가 개인 로컬 환경에서 사용할 때는 Desktop을 권장합니다.

• 첫 실행 안내가 다운로드부터 시작까지의 흐름을 이어 줍니다
• Hagicode Server의 시작, 중지, 버전을 프로그램이 일괄 관리합니다
• 그래픽 인터페이스로 상태를 확인하고 작업하기 쉽습니다
• 내장된 버전 관리로 여러 버전 사이를 쉽게 전환할 수 있습니다
• 기본적으로 데이터가 로컬에 남아 직접 관리하기 쉽습니다

Windows 사용자는 Microsoft Store 설치를 먼저 고려하고, 서버나 팀 배포에는 Docker Compose를 사용하세요.

Hagicode Desktop이란?

Hagicode Desktop은 Hagicode의 공식 데스크톱 애플리케이션으로 Windows, macOS, Linux를 지원합니다. 로컬 컴퓨터의 Hagicode Server를 내려받고, 시작하고, 관리하며, 버전 관리와 일상 작업을 위한 진입점을 제공합니다.

주요 장점

• .NET 런타임 내장: Hagicode Server 실행에 필요한 .NET이 Desktop에 포함되어 있어 따로 설치할 필요가 없습니다
• 서비스 관리: Hagicode Server 관리 기능이 내장되어 서비스를 쉽게 시작하고 중지할 수 있습니다
• 버전 전환: 여러 버전을 관리하며 버전 사이를 자유롭게 전환할 수 있습니다
• 로컬 실행: 모든 데이터가 로컬에 저장되어 개인 정보를 보호합니다
• 버전 감지: 사용 가능한 새 버전을 자동으로 감지합니다

적용 시나리오

다음과 같은 경우에 Desktop을 우선 사용할 수 있습니다.

• Hagicode를 로컬에서 사용하려는 개인 개발자
• 데이터와 프로젝트를 자신의 컴퓨터에 두려는 사용자
• 그래픽 인터페이스를 선호하고 배포 설정을 직접 작성하고 싶지 않은 사용자
• 여러 버전을 자주 전환해야 하는 개발자

설치 전 준비

Desktop에는 Node.js가 내장되어 있지 않으며, 내부 Node 실행 환경도 더 이상 제공하지 않습니다. 시스템 PATH에 있는 node와 npm을 사용하고, Agent CLI 같은 관리 대상 패키지는 로컬 npm의 전역 디렉터리에 설치합니다. 시작하기 전에 다음을 준비하세요.

종속성	요구 사항	설명
Node.js	24 이상 버전	npm도 함께 제공됩니다. Node.js 설치 참고
Git	현재 안정 버전이면 어떤 버전이든 가능	시작할 때 감지합니다. “새 프로젝트” 대화상자의 “데모 프로젝트”가 예제 저장소를 클론할 때 필요합니다. Git 설치 참고
Agent CLI	최소 하나, 로그인 완료	마법사에는 로컬에서 감지된 CLI만 표시됩니다. AI Agent CLI 설치 참고

먼저 터미널에서 버전을 확인합니다.

node --version   # v24.0.0 이상 필요
npm --version
git --version

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

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

Desktop 다운로드

빠른 다운로드

Windows 사용자는 Microsoft Store 설치를 먼저 사용하길 권장합니다. 설치 패키지를 직접 받거나, 특정 버전 파일을 지정해야 하거나, Store를 사용할 수 없을 때만 아래의 수동 다운로드 진입점을 사용하세요.

운영 체제에 맞는 버전을 선택해 설치 프로그램을 바로 내려받으세요.

GitHubChina

다운로드 목록을 불러오지 못할 때

Desktop 설치 패키지 목록을 일시적으로 불러오지 못하면 유효하지 않은 다운로드 링크를 보여 주는 대신 공식 버전 기록 페이지로 안내합니다: index.hagicode.com/desktop/history. 그곳에서 버전을 선택해 설치 패키지를 내려받을 수 있으며, 아래의 GitHub Releases를 직접 사용할 수도 있습니다.

기타 입수 방법

다음 경로에서도 Hagicode Desktop 설치 프로그램을 받을 수 있습니다.

1. Windows 기본 권장: Microsoft Store 설치를 방문해 공식 Store 배포 채널을 이용합니다
2. 공식 릴리스 페이지: Hagicode GitHub Releases에서 수동 설치 패키지를 내려받습니다
3. 공식 웹사이트: Hagicode 공식 웹사이트에서 다운로드 링크와 설치 안내를 확인합니다

올바른 버전 선택

운영 체제에 맞는 설치 프로그램을 선택하세요.

• Windows: Microsoft Store를 우선 사용하고, 수동 설치 파일이 필요할 때만 .exe 설치 프로그램 또는 .msix 패키지를 내려받습니다
• macOS: .dmg 설치 프로그램을 내려받습니다
• Linux: .AppImage 또는 .tar.gz 패키지를 내려받습니다

시스템 요구 사항

• Windows: Windows 10 이상(64비트)
• macOS: macOS 10.15 이상
• Linux: 주요 Linux 배포판(Ubuntu 20.04+, Fedora 33+ 등)

직접 준비해야 하는 종속성

Desktop에는 Hagicode Server 실행에 필요한 .NET 런타임이 내장되어 있고, 현재 지원하는 로컬 SQLite 경로로 기본 초기화를 마치므로 .NET을 따로 설치할 필요가 없습니다. 하지만 Node.js 24+와 Git은 직접 설치해야 합니다. 자세한 내용은 위의 설치 전 준비를 참고하세요.

설치 및 실행 안내

macOS Gatekeeper 안내

앱을 기본 경로 /Applications/Hagicode.app에 설치했는데 처음 실행할 때 “앱이 손상되었습니다”, “열 수 없습니다” 같은 Gatekeeper 메시지가 표시된다면, 대개 Hagicode Desktop 설치 마법사 자체의 오류가 아니라 macOS가 인터넷에서 내려받은 앱에 com.apple.quarantine 격리 속성을 붙였기 때문입니다.

터미널에서 다음 명령을 실행하세요. 이 명령은 관리자 권한이 필요하며, 기본 설치 경로에 있는 앱의 quarantine 속성을 재귀적으로 제거합니다.

sudo xattr -dr com.apple.quarantine /Applications/Hagicode.app

실행을 마친 뒤 Hagicode Desktop을 다시 시작하세요.

Desktop 실행

다운로드가 끝나면 설치 프로그램이나 앱 패키지를 열어 설치를 마치고 Hagicode Desktop을 시작합니다.

네트워크 요구 사항

네트워크 연결이 정상인지 확인하세요. Desktop은 인터넷에서 버전 정보와 Hagicode Server 설치 패키지를 받아와야 합니다. 다운로드에 실패하면 네트워크, 프록시, 방화벽 설정을 확인한 뒤 다시 시도하세요.

첫 실행 안내

Desktop을 처음 열면 먼저 Desktop 자체의 “최초 설정”이 나타납니다. 이 안내는 Hagicode Server를 설치하고 시작하는 일만 담당하며, 다음 순서로 진행됩니다.

1. 언어 선택: Desktop에서 사용할 언어를 선택합니다. 내장 백엔드를 처음 시작할 때도 해당 언어에 맞는 기본 언어를 사용합니다.
2. 환영: 이번 안내에서 어떤 준비를 마치는지 확인합니다.
3. 법적 문서 확인: 현재 버전의 EULA와 개인정보 보호정책을 확인하며, 정식 문서는 브라우저에서 열려 읽을 수 있습니다.
4. Hagicode Server 다운로드: 최신 Server 설치 패키지를 내려받고 다이제스트를 검증합니다.

다운로드가 끝나면 Desktop 홈으로 돌아가 “서비스 시작”을 클릭해 Hagicode Server를 시작하고, 이어서 홈 화면의 안내에 따라 Web 인터페이스를 엽니다.

일부 단계만 표시될 수 있습니다

일부 배포 채널(예: 설치 패키지에 Server가 이미 포함된 버전)이나, 버전 업데이트 후 법적 문서만 다시 확인하면 되는 경우에는 안내에 일부 단계만 표시됩니다.

Web 인터페이스 처음 사용

처음 Web 인터페이스에 들어가면 초기화 마법사가 나타납니다(위의 Desktop 최초 설정 안내와는 별개입니다). 이 마법사에서 인터페이스 언어와 테마를 선택하고, 기본 Hagicoder를 설정하고, 첫 프로젝트를 만듭니다. 자세한 단계는 다음 문서를 참고하세요.

초기화 마법사 설정언어, 테마, 기본 Hagicoder, 첫 프로젝트 설정을 마칩니다.

버전 관리

Hagicode Desktop은 여러 버전 관리를 지원하므로 버전 사이를 자유롭게 전환할 수 있습니다.

버전 전환

1. Hagicode Desktop을 엽니다
2. “버전 관리” 페이지로 이동합니다
3. 전환할 버전을 선택합니다
4. “버전 전환” 버튼을 클릭합니다
5. 전환이 끝날 때까지 기다립니다

버전 전환 시 참고 사항

• 버전을 전환하면 Hagicode Server가 자동으로 다시 시작됩니다
• 전환하기 전에 모든 작업을 저장했는지 확인하세요
• 버전마다 프로젝트 설정이 다를 수 있습니다

서비스 시작 및 중지

Hagicode Desktop은 Hagicode Server 서비스를 간단하게 관리하는 방법을 제공합니다.

서비스 시작

Desktop 애플리케이션 홈에서 “서비스 시작” 버튼을 클릭하면 Hagicode Server가 시작됩니다.

서비스 중지

Hagicode Server를 중지하려면 홈의 “서비스 중지” 버튼을 클릭합니다.

서비스 상태

Desktop 애플리케이션은 다음을 포함해 Hagicode Server의 실행 상태를 실시간으로 표시합니다.

• 서비스 상태(실행 중/중지됨)
• 서비스 포트 번호
• 현재 버전 정보

다음 단계

설치를 마친 뒤에는 다음 단계를 이어서 진행할 수 있습니다.

초기화 마법사 설정처음 실행한 뒤 여기에서 프로젝트 생성을 마치고 표준 빠른 시작 흐름으로 이어 가세요.

대화 세션 만들기기본 읽기 전용 모드에서 프로젝트를 이해한 뒤 필요할 때만 편집 모드로 전환합니다.

제안 세션 만들기제안 기반 개발 워크플로를 알아보고 추상적인 아이디어를 구조화된 구현 계획으로 바꿉니다.

문제 해결

설치 실패

설치 중 문제가 발생하면 다음을 확인하세요.

1. 네트워크 연결 확인: 인터넷에 접속할 수 있는지 확인합니다
2. 디스크 공간 확인: 디스크 공간이 충분한지 확인합니다
3. 관리자 권한으로 실행: Windows에서는 설치 프로그램을 마우스 오른쪽 버튼으로 클릭하고 “관리자 권한으로 실행”을 선택합니다
4. 설치 프로그램 메시지 확인: 설치 프로그램이 표시한 오류 메시지를 기록해 두었다가 이슈를 제출할 때 함께 첨부합니다

Node.js, npm 또는 Git을 찾을 수 없음

Desktop이 node, npm, git이 없다고 안내하거나 Node.js 버전이 너무 낮다고 안내하는 경우:

1. 설치 확인: 터미널에서 node --version, npm --version, git --version을 실행합니다. Node.js는 24 이상이어야 하며, 설치 방법은 Node.js 설치와 Git 설치를 참고하세요.
2. Desktop 재시작: Desktop은 시작할 때 시스템 PATH를 읽습니다. 설치 후에는 Desktop을 완전히 종료한 뒤 다시 시작하고, 종속성 페이지를 새로 고치세요.
3. PATH 확인: 터미널에서는 실행되는데 Desktop에서는 찾지 못한다면, 대개 PATH가 특정 셸 설정에서만 적용되기 때문입니다(예: nvm 또는 fnm이 .bashrc / .zshrc에서 설정하는 경우). 시스템 수준 설치로 바꾸거나, 해당 PATH를 읽을 수 있는 환경에서 Desktop을 시작하세요.
4. CLI 패키지 수동 설치: Desktop이 CLI 패키지를 수동으로 설치하라고 안내하면 Desktop 밖의 터미널에서 안내된 명령을 실행하고, 끝난 뒤 Desktop으로 돌아와 새로 고치세요. 외부 Node / npm 환경과 PATH 동작은 Desktop이 사용자의 Node 환경을 사용하는 방식을 참고하세요.

서비스 시작 실패

Hagicode Server가 시작되지 않는 경우:

1. 포트 점유 확인: Desktop은 기본적으로 포트 36556을 사용합니다(홈 화면에 실제 사용 중인 포트가 표시됩니다). 다른 프로그램이 이 포트를 사용하고 있지 않은지 확인하세요
2. 방화벽 설정 확인: 방화벽이 Hagicode Server의 네트워크 접근을 허용하는지 확인하세요
3. 애플리케이션 재시작: Hagicode Desktop을 다시 시작해 보세요
4. 로그 확인: Desktop 애플리케이션에서 자세한 오류 로그를 확인하세요

도움이 더 필요하신가요?

여기서 다루지 않은 문제가 발생한 경우:

1. Desktop의 GitHub Issues에서 비슷한 문제를 찾아보세요
2. 커뮤니티 포럼에서 도움을 요청하세요
3. 새 이슈를 제출하고 문제를 자세히 설명하며, 시스템 버전, node --version, Desktop 로그를 함께 첨부하세요