Instalación de Desktop

Esta página explica cómo instalar y usar Hagicode Desktop. Es el cliente de escritorio oficial y reúne en un mismo lugar el flujo de instalación local predeterminado y los controles de uso diario.

Método recomendado

Para uso local personal en macOS, Linux y Windows sin Microsoft Store, se recomienda Desktop:

• La guía del primer arranque enlaza la descarga y el inicio en un mismo flujo
• La aplicación gestiona de forma unificada el inicio, la parada y las versiones de Hagicode Server
• La interfaz gráfica facilita consultar el estado y realizar operaciones
• La gestión de versiones integrada permite cambiar entre versiones
• Los datos permanecen en local por defecto, bajo su propio control

Si usa Windows, considere primero la Instalación desde Microsoft Store; para despliegues en servidor o en equipo, use Docker Compose.

¿Qué es Hagicode Desktop?

Hagicode Desktop es la aplicación de escritorio oficial de Hagicode y es compatible con Windows, macOS y Linux. Se encarga de descargar, iniciar y gestionar el Hagicode Server de su equipo, y ofrece gestión de versiones y los puntos de entrada para el uso diario.

Principales ventajas

• Runtime de .NET integrado: el .NET necesario para ejecutar Hagicode Server se incluye con Desktop, por lo que no hay que instalarlo por separado
• Gestión del servicio: gestión integrada de Hagicode Server para iniciar y detener el servicio fácilmente
• Cambio de versión: admite varias versiones y permite cambiar libremente entre ellas
• Ejecución local: todos los datos se almacenan en local, lo que protege su privacidad
• Detección de versiones: detecta automáticamente las nuevas versiones disponibles

Escenarios aplicables

Priorice Desktop en estos casos:

• Desarrolladores individuales que quieren usar Hagicode en local
• Usuarios que prefieren que sus datos y proyectos permanezcan en su propio equipo
• Usuarios que prefieren una interfaz gráfica y no quieren escribir configuraciones de despliegue a mano
• Desarrolladores que necesitan cambiar con frecuencia entre distintas versiones

Requisitos previos

Desktop no incluye Node.js y tampoco ofrece ya un entorno de ejecución de Node propio. Usa los node y npm del PATH del sistema e instala los paquetes gestionados, como los Agent CLI, en el directorio global de npm de su equipo. Antes de empezar, prepare lo siguiente:

Dependencia	Requisito	Descripción
Node.js	24 o superior	También proporciona npm; consulte Instalar Node.js
Git	Cualquier versión estable actual	Se comprueba al iniciar; el “Proyecto de demostración” del cuadro de diálogo “Nuevo proyecto” lo necesita para clonar el repositorio de ejemplo; consulte Instalar Git
Agent CLI	Al menos uno, con la sesión iniciada	El asistente solo lista los CLI detectados en el equipo; consulte Instalación de AI Agent CLI

Compruebe primero las versiones en la terminal:

node --version   # Se requiere v24.0.0 o superior
npm --version
git --version

Instálelos antes de iniciar, o reinicie Desktop

Desktop lee el PATH del sistema al iniciarse. Si instala Node.js o Git con Desktop ya abierto, ciérrelo por completo y vuelva a iniciarlo; después actualice la página de dependencias.

Descargar Desktop

Descarga rápida

En Windows se recomienda usar primero la instalación desde Microsoft Store; utilice el acceso de descarga manual que aparece más abajo solo si necesita un paquete de instalación manual, un archivo de una versión concreta o si la Store no está disponible.

Seleccione la versión adecuada para su sistema operativo y descargue el instalador directamente:

GitHubChina

Si la lista de descargas no se carga

Si la lista de instaladores de Desktop no se puede cargar por el momento, el punto de entrada de instalación no mostrará un enlace de descarga no válido, sino que le dirigirá a la página oficial del historial de versiones: index.hagicode.com/desktop/history. Allí puede elegir una versión y descargar el instalador; también puede usar directamente los GitHub Releases que se indican más abajo.

Otras formas de obtenerlo

También puede obtener el instalador de Hagicode Desktop en los siguientes canales:

1. Opción recomendada por defecto en Windows: visite la Instalación desde Microsoft Store para usar el canal de distribución de la tienda oficial
2. Página oficial de versiones: visite Hagicode GitHub Releases para descargar el paquete de instalación manual
3. Sitio web oficial: visite el sitio web de Hagicode para obtener los enlaces de descarga y las instrucciones de instalación

Elija la versión correcta

Seleccione el instalador correspondiente a su sistema operativo:

• Windows: use preferentemente Microsoft Store; si necesita un archivo de instalación manual, descargue el instalador .exe o el paquete .msix
• macOS: descargue el instalador .dmg
• Linux: descargue el paquete de instalación .AppImage o .tar.gz

Requisitos del sistema

• Windows: Windows 10 o superior (64 bits)
• macOS: macOS 10.15 o superior
• Linux: distribuciones Linux habituales (Ubuntu 20.04+, Fedora 33+, etc.)

Dependencias que debe preparar usted

Desktop ya incluye el runtime de .NET necesario para ejecutar Hagicode Server y completa la inicialización predeterminada con la ruta SQLite local actualmente admitida, por lo que no necesita instalar .NET por separado. Sin embargo, Node.js 24+ y Git los debe instalar usted mismo; consulte los Requisitos previos anteriores.

Notas de instalación y lanzamiento

Aviso de Gatekeeper en macOS

Si ya instaló la aplicación en la ruta predeterminada /Applications/Hagicode.app, pero en el primer arranque aparece “la aplicación está dañada”, “no se puede abrir” o un aviso de Gatekeeper similar, la causa habitual es el atributo de cuarentena com.apple.quarantine que macOS añade a las aplicaciones descargadas de Internet, y no un fallo del asistente de instalación de Hagicode Desktop.

Puede ejecutar el siguiente comando en la terminal. Requiere privilegios de administrador y elimina de forma recursiva el atributo de cuarentena de la aplicación en la ruta de instalación predeterminada:

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

Cuando termine, reinicie Hagicode Desktop.

Ejecutar Desktop

Tras la descarga, abra el instalador o el paquete de la aplicación para completar la instalación y, después, inicie Hagicode Desktop.

Requisitos de red

Asegúrese de que su conexión de red funciona. Desktop necesita obtener de Internet la información de versiones y el paquete de instalación de Hagicode Server; si la descarga falla, revise la configuración de red, proxy o cortafuegos y vuelva a intentarlo.

Guía de primer arranque

La primera vez que abra Desktop, accederá primero a la guía “Configuración por primera vez” que incluye Desktop. Su única función es instalar e iniciar Hagicode Server, y consta de los siguientes pasos, en este orden:

1. Elegir idioma: seleccione el idioma que usará Desktop. El primer arranque del backend integrado también adoptará el idioma predeterminado correspondiente.
2. Bienvenida: conozca los preparativos que completará esta guía.
3. Confirmar los documentos legales: confirme las revisiones actuales del CLUF (EULA) y de la Política de privacidad; los documentos oficiales se abren en el navegador para su lectura.
4. Descargar Hagicode Server: descargue el último paquete de instalación de Server y verifique su resumen (hash).

Cuando termine la descarga, vuelva a la página de inicio de Desktop y haga clic en “Iniciar servicio” para arrancar Hagicode Server; después, siga las indicaciones de la página de inicio para abrir la interfaz web.

Puede que no aparezcan todos los pasos

En algunos canales de distribución (por ejemplo, las versiones cuyo paquete de instalación ya incluye Server), o cuando tras una actualización de versión solo hace falta volver a confirmar los documentos legales, la guía muestra únicamente una parte de estos pasos.

Primer uso de la interfaz web

Cuando entre por primera vez en la interfaz web, aparecerá el asistente de inicialización (que es algo distinto de la guía de primer uso de Desktop descrita arriba). Le guiará para elegir el idioma y el tema de la interfaz, configurar el Hagicoder predeterminado y crear su primer proyecto. Para ver los pasos detallados, lea:

Configuración del asistenteComplete la configuración del idioma, el tema, el Hagicoder predeterminado y el primer proyecto.

Gestión de versiones

Hagicode Desktop admite la gestión de varias versiones, lo que le permite cambiar libremente entre ellas.

Cambiar de versión

1. Abra Hagicode Desktop
2. Vaya a la página “Gestión de versiones”
3. Seleccione la versión a la que quiere cambiar
4. Haga clic en el botón “Cambiar”
5. Espere a que termine el cambio

Notas sobre el cambio de versión

• Cambiar de versión reinicia automáticamente Hagicode Server
• Guarde todo su trabajo antes de cambiar
• La configuración de los proyectos puede diferir entre versiones

Iniciar y detener el servicio

Hagicode Desktop ofrece una forma sencilla de gestionar el servicio Hagicode Server.

Iniciar el servicio

En la página de inicio de la aplicación Desktop, haga clic en el botón “Iniciar servicio” para arrancar Hagicode Server.

Detener el servicio

Para detener Hagicode Server, haga clic en el botón “Detener servicio” de la página de inicio.

Estado del servicio

La aplicación Desktop muestra en tiempo real el estado de ejecución de Hagicode Server, que incluye:

• El estado del servicio (en ejecución / detenido)
• El número de puerto del servicio
• La información de la versión actual

Próximos pasos

Cuando termine la instalación, puede continuar con los siguientes pasos:

Configuración del asistenteComplete aquí la creación del proyecto tras el primer arranque y continúe con el flujo de inicio rápido estándar.

Crear una sesión de conversaciónComprenda el proyecto en el modo de solo lectura predeterminado y cambie al modo de edición solo cuando lo necesite.

Crear una sesión de propuestaConozca el flujo de desarrollo basado en propuestas, que convierte ideas abstractas en planes de implementación estructurados.

Solución de problemas

Fallo de instalación

Si surgen problemas durante la instalación:

1. Compruebe la conexión de red: asegúrese de poder acceder a Internet
2. Compruebe el espacio en disco: asegúrese de que hay suficiente espacio libre
3. Ejecute como administrador: en Windows, haga clic con el botón derecho en el instalador y seleccione “Ejecutar como administrador”
4. Revise los mensajes del instalador: anote el mensaje de error que muestra el instalador y adjúntelo al enviar un informe del problema

No se encuentra Node.js, npm o Git

Si Desktop indica que faltan node, npm o git, o que la versión de Node.js es demasiado antigua:

1. Confirme que están instalados: ejecute node --version, npm --version y git --version en la terminal. Node.js debe ser la versión 24 o superior; para instalarlos, consulte Instalar Node.js e Instalar Git.
2. Reinicie Desktop: Desktop lee el PATH del sistema al iniciarse. Tras la instalación, ciérrelo por completo y vuelva a iniciarlo; después actualice la página de dependencias.
3. Revise el PATH: si funciona en la terminal pero Desktop no lo encuentra, normalmente es porque el PATH solo se define en la configuración de un shell (por ejemplo, con nvm o fnm en .bashrc / .zshrc). Use una instalación a nivel de sistema o asegúrese de iniciar Desktop desde un entorno que pueda leer ese PATH.
4. Instale manualmente el paquete CLI: cuando Desktop indique que hay que instalar un paquete CLI de forma manual, ejecute el comando que muestra en una terminal ajena a Desktop y, al terminar, vuelva a Desktop y actualice. Para el comportamiento del entorno externo de Node / npm y del PATH, consulte Cómo usa Desktop su entorno de Node.

Fallo de inicio del servicio

Si Hagicode Server no se inicia:

1. Compruebe si el puerto está ocupado: Desktop usa por defecto el puerto 36556 (la página de inicio muestra el puerto real en uso); asegúrese de que no lo ocupa otro programa
2. Revise la configuración del cortafuegos: asegúrese de que el cortafuegos permite el acceso a la red de Hagicode Server
3. Reinicie la aplicación: pruebe a reiniciar Hagicode Desktop
4. Consulte los registros: revise los registros de errores detallados en la aplicación Desktop

¿Necesita más ayuda?

Si encuentra problemas que no se tratan aquí:

1. Busque problemas similares en los GitHub Issues de Desktop
2. Visite nuestro foro de la comunidad para pedir ayuda
3. Abra un nuevo Issue y describa su problema con detalle, adjuntando la versión de su sistema, la salida de node --version y los registros de Desktop