Desktop Installation

This page explains how to install and use Hagicode Desktop. It is the official desktop client and puts the default local installation flow and day-to-day management in one place.

Recommended Method

For personal local use on macOS, Linux, and Windows without the Store, Desktop is recommended:

• The first-launch guide strings the download and startup flow together
• Starting, stopping, and versioning Hagicode Server are managed by the app in one place
• The graphical interface makes it easier to check status and operate
• Built-in version management makes it easy to switch between versions
• Data stays local by default, so you stay in control

Windows users should consider Microsoft Store Installation first; for server or team deployments, use Docker Compose.

What is Hagicode Desktop?

Hagicode Desktop is Hagicode’s official desktop application and supports Windows, macOS, and Linux. It downloads, starts, and manages Hagicode Server on your machine, and provides version management and day-to-day operation entry points.

Main Advantages

• Built-in .NET Runtime: the .NET needed to run Hagicode Server ships with Desktop, so you do not need to install it separately
• Service Management: built-in Hagicode Server management makes it easy to start and stop the service
• Version Switching: supports multi-version management, so you can freely switch between versions
• Local Operation: all data is stored locally, protecting your privacy
• Version Detection: automatically detects newly available versions

Applicable Scenarios

Desktop is a good first choice in these scenarios:

• Individual developers who want to use Hagicode locally
• Users who want their data and projects to stay on their own machine
• Users who prefer a graphical interface and do not want to write deployment configuration by hand
• Developers who need to switch between versions frequently

Before You Install

Desktop does not bundle Node.js and no longer provides an internal Node runtime. It uses the node and npm on your system PATH, and installs managed packages such as Agent CLIs into your local npm global directory. Prepare the following before you start:

Dependency	Requirement	Notes
Node.js	24 or higher	Also provides npm; see Installing Node.js
Git	Any current stable version	Checked at startup; the “Demo Project” in the “New Project” dialog needs it to clone the sample repository; see Install Git
Agent CLI	At least one, already signed in	The wizard only lists CLIs detected locally; see AI Agent CLI Installation

First confirm the versions in a terminal:

node --version   # requires v24.0.0 or higher
npm --version
git --version

Install First, Then Launch, or Restart Desktop

Desktop reads the system PATH at startup. If you install Node.js or Git while Desktop is already open, fully quit and restart Desktop, then refresh the dependency page.

Download Desktop

Quick Download

On Windows, installing from the Microsoft Store is recommended first. Use the manual download entries below only when you need an installer package, a specific version file, or the Store is unavailable.

Select the version suitable for your operating system and download the installer directly:

GitHubChina

If the Download List Fails to Load

If the Desktop installer list cannot be loaded here for the moment, the install entry will not show an invalid download link. Instead, it guides you to the official version history page: index.hagicode.com/desktop/history. There you can pick a version and download the installer; you can also use the GitHub Releases below directly.

Other Download Methods

You can also get the Hagicode Desktop installer from the following channels:

1. Recommended default for Windows: visit Microsoft Store Installation to use the official Store distribution channel
2. Official Release Page: visit Hagicode GitHub Releases to download manual installer packages
3. Official Website: visit the Hagicode Website to get download links and installation instructions

Choose the Correct Version

Select the corresponding installer for your operating system:

• Windows: use the Microsoft Store first; if you need manual installer files, download the .exe installer or the .msix package
• macOS: download the .dmg installer
• Linux: download the .AppImage or .tar.gz installer package

System Requirements

• Windows: Windows 10 or higher (64-bit)
• macOS: macOS 10.15 or higher
• Linux: Mainstream Linux distributions (Ubuntu 20.04+, Fedora 33+, etc.)

Dependencies You Need to Prepare Yourself

Desktop already bundles the .NET runtime needed to run Hagicode Server and completes default initialization along the currently supported local SQLite path, so you do not need to install .NET separately. However, you need to install Node.js 24+ and Git yourself; see Before You Install above.

Installation and Launch Notes

macOS Gatekeeper Notice

If you already installed the app to the default path /Applications/Hagicode.app but macOS shows “app is damaged”, “can’t be opened”, or a similar Gatekeeper warning on first launch, the usual cause is the com.apple.quarantine attribute that macOS adds to apps downloaded from the internet, not a failure in the Hagicode Desktop installer itself.

Run the following command in Terminal. It requires administrator privileges and recursively removes the quarantine attribute from the app in the default installation path:

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

After the command finishes, relaunch Hagicode Desktop.

Run Desktop

After downloading, open the installer or application package to finish the installation, then launch Hagicode Desktop.

Network Requirements

Make sure your network connection is working. Desktop needs to fetch version information and the Hagicode Server package from the internet; if a download fails, check your network, proxy, or firewall settings and retry.

First-Launch Guide

The first time you open Desktop, it starts with Desktop’s own “First-Time Setup”. It only handles installing and starting Hagicode Server, and includes these steps in order:

1. Choose Your Language: choose the language Desktop uses. When the embedded backend starts for the first time, it also adopts the matching default language.
2. Welcome: learn what preparation this guide will complete.
3. Confirm Legal Documents: confirm the current EULA and Privacy Policy revisions; the official documents open in your browser for reading.
4. Download Hagicode Server: download the latest Server package and verify its digest.

After the download finishes, return to the Desktop home page and click “Start Service” to start Hagicode Server, then follow the prompts on the home page to open the Web interface.

Steps May Be Incomplete

In some distribution channels (for example, builds whose installer already ships the Server), or when you only need to re-confirm the legal documents after a version update, the guide shows only some of these steps.

First Use of the Web Interface

The first time you enter the Web interface, the Initialization Wizard appears (this is a different thing from the Desktop First-Time Setup above). It guides you through choosing the interface language and theme, setting up the default Hagicoder, and creating your first project. For detailed steps, read:

Wizard SetupComplete the language, theme, default Hagicoder, and first project setup.

Version Management

Hagicode Desktop supports multi-version management, allowing you to freely switch between different versions.

Switch Version

1. Open Hagicode Desktop
2. Go to “Version Management” page
3. Select the version you want to switch
4. Click “Switch Version” button
5. Wait for switch to complete

Version Switching Notes

• Switching versions will automatically restart Hagicode Server
• Ensure you save all work before switching
• Project configurations may differ between versions

Start and Stop Service

Hagicode Desktop provides a simple way to manage Hagicode Server service.

Start Service

On the home page of the Desktop application, click the “Start Service” button to start Hagicode Server.

Stop Service

To stop Hagicode Server, click the “Stop Service” button on the home page.

Service Status

The Desktop application displays Hagicode Server’s running status in real-time, including:

• Service status (running/stopped)
• Service port number
• Current version information

Next Steps

After installation is complete, you can continue with the following steps:

Wizard SetupComplete project creation here after first launch and continue through the canonical quick-start flow.

Create a Conversation SessionUnderstand the project in default read-only mode, then switch to edit mode only when needed.

Create Proposal SessionLearn about the proposal-driven development workflow, transforming abstract ideas into structured implementation plans.

Troubleshooting

Installation Failure

If you encounter issues during installation:

1. Check Network Connection: Ensure you can access the internet
2. Check Disk Space: Ensure you have sufficient disk space
3. Run as Administrator: On Windows, right-click the installer and select “Run as administrator”
4. Read the Installer Messages: Note any error message the installer shows and include it when you submit an issue

Node.js, npm, or Git Not Found

If Desktop reports that node, npm, or git is missing, or that the Node.js version is too old:

1. Confirm they are installed: run node --version, npm --version, and git --version in a terminal. Node.js must be version 24 or higher; for installation, see Installing Node.js and Install Git.
2. Restart Desktop: Desktop reads the system PATH at startup. After installing, fully quit and restart Desktop, then refresh the dependency page.
3. Check PATH: if the commands work in a terminal but Desktop cannot find them, the usual cause is that PATH is only set in a particular shell configuration (for example, nvm or fnm configured in .bashrc / .zshrc). Switch to a system-wide installation, or make sure you launch Desktop from an environment that can read that PATH.
4. Install CLI packages manually: when Desktop says a CLI package must be installed manually, run the command it gives in a terminal outside Desktop, then return to Desktop and refresh. For how the external Node / npm environment and PATH are handled, see How Desktop Uses Your Node Environment.

Service Startup Failure

If Hagicode Server fails to start:

1. Check Port Occupancy: Desktop uses port 36556 by default (the home page shows the actual port in use). Make sure it is not occupied by other programs
2. Check Firewall Settings: Ensure firewall allows Hagicode Server network access
3. Restart Application: Try restarting Hagicode Desktop
4. View Logs: View detailed error logs in the Desktop application

Need More Help?

If you encounter issues not covered here:

1. Check Desktop GitHub Issues for similar problems
2. Visit our Community Forum for help
3. Submit a new Issue, describing your problem in detail and attaching your system version, node --version output, and Desktop logs