Desktop Installation

This guide covers installing and using Hagicode Desktop. It is the official desktop client and keeps the default local setup path plus daily controls in one place.

Recommended Method

Desktop is the default local path for individual users and developers because:

• the installer keeps the default flow in one guided path
• dependencies and services are managed in the app
• the UI makes state and operations easier to inspect
• built-in version management makes switching easier
• data stays local by default

What is Hagicode Desktop?

Hagicode Desktop is Hagicode’s official desktop application, designed for Windows, macOS, and Linux systems. It bundles Hagicode’s core features, and the installer keeps the default setup path in one guided flow.

Main Advantages

• One-click Installation: Complete all configuration steps automatically through the installation wizard
• Automatic Runtime Preparation: The default installer already includes the runtime it needs, so you do not need to install a separate .NET runtime first
• Service Management: Built-in Hagicode Server management, easily start and stop services
• Version Switching: Support for multi-version management, freely switch between different versions
• Local Operation: All data is stored locally, protecting your privacy
• Automatic Updates: Automatically detects and downloads the latest version

Applicable Scenarios

Desktop is a good fit when:

• Individual developers who want to use Hagicode locally
• Users who need to use Hagicode offline
• Non-technical users who want to simplify the installation process
• Developers who need to frequently switch between different versions

Download Desktop

Quick Download

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

Install Now

Other Download Methods

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

1. Official Release Page: Visit Hagicode GitHub Releases to download the latest version
2. Official Website: Visit Hagicode Website to get download links

Choose the Correct Version

Select the corresponding installer for your operating system:

• Windows: Download the .exe installer
• macOS: Download the .dmg installer
• Linux: Download the .AppImage or .deb installer package

System Requirements

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

Default Prerequisites

For the latest HagiCode local installation flow, you usually do not need to install PostgreSQL manually in advance, and you do not need to prepare a separate .NET runtime. Desktop already bundles the runtime required for the default flow. Only review the PostgreSQL guide if you plan to use an external database, follow an advanced deployment path, or connect HagiCode to a separately managed database.

Run the Installer

After downloading, run the installer. You will see the Hagicode Desktop installer welcome screen.

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.

Installation Wizard Steps

The current default installation flow mainly has two stages. Here are detailed instructions for each stage:

Step 1: Download Hagicode

After configuration is complete, the wizard will automatically download the latest version of Hagicode.

This Step Explains:

• Wizard automatically detects and downloads the latest stable version
• Download progress is displayed in real-time
• Automatically proceeds to next step after download completes

Network Requirements

Ensure your network connection is normal. The installer needs to download components from the internet. If download fails, please check your network settings or try again later.

Step 2: Start Service

After Hagicode finishes downloading, the wizard will launch the Hagicode Server service.

This Step Explains:

• Hagicode Server starts automatically in the background
• Startup usually takes only a few seconds
• After startup completes, you can start using Hagicode

Service Startup Complete

When Hagicode Server successfully starts, you will see the following interface.

Click the “Open Hagicode” button to start using.

First Use

After you first enter Hagicode, the current initialization wizard starts immediately. The new flow now covers language, dependency checks, themes, AgentCLI, Agents, projects, and community entry points as one continuous 8-step setup instead of reusing the older three-step walkthrough.

If you want the up-to-date screen-by-screen guide for first-run setup, continue with the quick-start page below:

Wizard Setup Click here to see how initialization works after entering the web page.

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 Setup Complete project creation here after first launch and continue through the canonical quick-start flow.

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

Create Proposal Session Learn 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. View Log Files: The installer generates detailed log files that can help diagnose issues

Dependency Installation Failure

If dependency installation fails:

1. Check System Compatibility: Ensure your operating system meets minimum requirements
2. Check Network and Firewall Settings: Ensure the installer can reach required downloads and is not blocked by your firewall
3. Confirm Installer Permissions: On Windows, try running the installer as administrator so it has sufficient permissions
4. Restart the App and Retry: Close and reopen Hagicode Desktop, then retry the installation step
5. View Logs: Review detailed error logs in the Desktop application

Service Startup Failure

If Hagicode Server fails to start:

1. Check Port Occupancy: Ensure port 45000 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 GitHub Issues for similar problems
2. Visit our Community Forum for help
3. Submit a new Issue, describing your problem in detail