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:

GitHubChina

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 .tar.gz 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 prepare a separate .NET runtime. Desktop already bundles the runtime required for the default flow and initializes the supported local SQLite path by default.

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 and follow the on-screen instructions. Desktop prepares the runtime in the currently supported local path, manages Hagicode Server, and shows progress and status when network downloads are required.

Network Requirements

Ensure your network connection is available. Desktop may need to fetch version information or component packages from the internet; if a download fails, check your network, proxy, or firewall settings and retry.

First Use

After you first enter Hagicode, the current initialization wizard starts immediately. Follow the on-screen instructions; detailed first-run setup, project creation, and session creation guidance now lives in the quick-start pages.

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