Desktop Installation

This guide explains how to install and use the Hagicode Desktop application. Hagicode Desktop is a powerful and easy-to-use desktop application that provides you with a complete Hagicode experience.

Recommended Method

Hagicode Desktop is the most suitable installation method for individual users and developers, with the following advantages:

• One-click installation, no need to configure complex environments
• Automatic dependency and service management
• Graphical interface, simple and intuitive operation
• Built-in version management, easy to switch between different versions
• Local operation, complete control of your data

What is Hagicode Desktop?

Hagicode Desktop is Hagicode’s official desktop application, designed for Windows, macOS, and Linux systems. It integrates all of Hagicode’s core features and makes the installation process simple and fast through an installation wizard.

Main Advantages

• One-click Installation: Complete all configuration steps automatically through the installation wizard
• Automatic Dependency Management: Automatically detects and installs required runtime environments (like .NET runtime)
• 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

Hagicode Desktop is suitable for the following scenarios:

• 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

macOS Status

Native macOS package download is currently unavailable. Recommended: install the Docker version via the Container page.

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: Recommended: install the Docker version (Go to Container page)
• 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.)

Run the Installer

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

Installation Wizard Steps

Hagicode Desktop provides a four-step installation wizard to guide you through the complete installation process. Here are detailed instructions for each step:

Step 1: Select Pre-configured AgentCLI

The installation wizard will guide you to select a pre-configured AgentCLI for installation.

This Step Explains:

• View the list of available AgentCLI options
• Select your pre-configured AgentCLI
• Confirm selection and continue to next step

Pre-configuration

Before using the Hagicode Desktop installation wizard, please ensure you have completed the AgentCLI configuration work. If you haven’t configured AgentCLI yet, please complete the related configuration steps first.

Step 2: 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 3: Select Region and Install AI

Hagicode supports different AI models for different regions. You can choose the appropriate region based on your location.

Region Selection Explains:

• Mainland China: Optimized network connection, suitable for users in China
• International Region: Suitable for overseas users or users with special network requirements

The wizard will automatically configure and launch the AI installation process based on your selected region.

This Step Explains:

• AI assistant guides you through the installation process
• Please follow the on-screen prompts
• If you encounter issues, click “Need Help” for support

Step 4: Start Service

After AI installation is complete, 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

Create Project

When you first enter Hagicode, you can create your first project through the built-in import wizard.

Project Creation Steps:

1. Click “Create New Project”
2. Configure project name and path
3. Select programming language and framework
4. Configure API settings
5. Complete project creation

Import Git Repository

If you already have an existing Git repository, you can easily import it into Hagicode.

Import Steps:

1. Click “Import Project”
2. Enter the folder path containing Git repositories
3. Hagicode will automatically scan all Git repositories in that folder
4. Select the repository you want to import and confirm

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:

Create Your First Project Initialize your Hagicode project, configure basic settings, and begin your AI-assisted development journey.

Create Conversation Session Start interacting with AI, experience read-only and edit dual modes, and let AI become your capable programming partner.

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. Manually Install Dependencies: You can manually download and install .NET runtime
3. Check Firewall Settings: Ensure firewall doesn’t block the installer
4. Restart Application: Try restarting Hagicode Desktop
5. View Logs: View 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