Instalação do Desktop

Esta página explica como instalar e usar o Hagicode Desktop. Ele é o cliente de desktop oficial e reúne em um só lugar o fluxo de instalação local padrão e os controles do dia a dia.

Método recomendado

Para uso pessoal local no macOS, no Linux e no Windows sem a Store, recomendamos o Desktop:

• O guia de primeira inicialização conecta as etapas de download e de inicialização
• O início, a parada e a versão do Hagicode Server são gerenciados de forma centralizada pelo programa
• A interface gráfica facilita acompanhar o estado e executar operações
• O gerenciamento de versões integrado facilita alternar entre versões
• Os dados ficam locais por padrão, para você mantê-los sob seu controle

Se você usa Windows, considere primeiro a instalação pela Microsoft Store; para implantação em servidor ou em equipe, use o Docker Compose.

O que é o Hagicode Desktop

O Hagicode Desktop é o aplicativo de desktop oficial do Hagicode, compatível com Windows, macOS e Linux. Ele baixa, inicia e gerencia o Hagicode Server na sua máquina e oferece o gerenciamento de versões e os controles do dia a dia.

Principais vantagens

• Runtime .NET incluído: o .NET necessário para executar o Hagicode Server já acompanha o Desktop, sem instalação separada
• Gerenciamento de serviço: gerenciamento integrado do Hagicode Server, para iniciar e parar o serviço com facilidade
• Troca de versão: suporte a várias versões, com troca livre entre elas
• Execução local: todos os dados ficam armazenados localmente, protegendo sua privacidade
• Detecção de versão: detecta automaticamente novas versões disponíveis

Cenários indicados

Dê preferência ao Desktop nestes cenários:

• Desenvolvedores individuais que querem usar o Hagicode localmente
• Usuários que querem manter dados e projetos na própria máquina
• Usuários que preferem interface gráfica e não querem escrever configuração de implantação à mão
• Desenvolvedores que precisam alternar com frequência entre versões

Preparação antes da instalação

O Desktop não inclui o Node.js e também não oferece mais um ambiente Node interno. Ele usa o node e o npm que estão no PATH do sistema e instala pacotes gerenciados, como os Agent CLIs, no diretório global do npm da sua máquina. Antes de começar, prepare:

Dependência	Requisito	Descrição
Node.js	24 ou superior	Inclui o npm; veja Instalar o Node.js
Git	Qualquer versão estável atual	Detectado ao iniciar; o “Projeto de demonstração” da caixa de diálogo “Novo Projeto” o utiliza para clonar o repositório de exemplo; veja Instalar o Git
Agent CLI	Pelo menos um, já autenticado	O assistente lista apenas os CLIs detectados localmente; veja Instalação do AI Agent CLI

Confirme as versões primeiro no terminal:

node --version   # requer v24.0.0 ou superior
npm --version
git --version

Instale antes de iniciar, ou reinicie o Desktop

O Desktop lê o PATH do sistema ao iniciar. Se você instalar o Node.js ou o Git com o Desktop já aberto, feche-o por completo, abra-o novamente e atualize a página de dependências.

Baixar o Desktop

Download rápido

Para Windows, recomendamos instalar primeiro pela Microsoft Store; use as opções de download manual abaixo apenas se precisar do pacote de instalação, de um arquivo de versão específico ou se a Store não estiver disponível.

Escolha a versão adequada ao seu sistema operacional e baixe o instalador diretamente:

GitHubChina

Se a lista de downloads não carregar

Se a lista de pacotes de instalação do Desktop não puder ser carregada por enquanto, o ponto de entrada de instalação não exibirá um link de download inválido; em vez disso, direcionará você à página oficial de histórico de versões: index.hagicode.com/desktop/history. Lá você pode escolher uma versão e baixar o pacote de instalação; também é possível usar diretamente o GitHub Releases abaixo.

Outras formas de obter

Você também pode obter o instalador do Hagicode Desktop pelos seguintes canais:

1. Recomendação padrão para Windows: acesse a instalação pela Microsoft Store para usar o canal oficial de distribuição da loja
2. Página oficial de lançamentos: acesse o GitHub Releases do Hagicode para baixar o pacote de instalação manual
3. Site oficial: acesse o site do Hagicode para obter links de download e instruções de instalação

Escolha a versão correta

Escolha o instalador correspondente ao seu sistema operacional:

• Windows: dê preferência à Microsoft Store; se precisar de um arquivo de instalação manual, baixe o instalador .exe ou o pacote .msix
• macOS: baixe o instalador .dmg
• Linux: baixe o pacote .AppImage ou .tar.gz

Requisitos do sistema

• Windows: Windows 10 ou superior (64 bits)
• macOS: macOS 10.15 ou superior
• Linux: distribuições Linux convencionais (Ubuntu 20.04+, Fedora 33+ etc.)

Dependências que você mesmo precisa preparar

O Desktop já inclui o runtime .NET necessário para executar o Hagicode Server e conclui a inicialização padrão no caminho SQLite local compatível, portanto você não precisa instalar o .NET separadamente. Porém, o Node.js 24+ e o Git precisam ser instalados por você; veja Preparação antes da instalação acima.

Observações sobre instalação e inicialização

Aviso do Gatekeeper do macOS

Se você já instalou o aplicativo no caminho padrão /Applications/Hagicode.app, mas na primeira inicialização o macOS mostra “o aplicativo está danificado”, “não pode ser aberto” ou um aviso semelhante do Gatekeeper, a causa comum é o atributo de quarentena com.apple.quarantine, que o macOS adiciona aos aplicativos baixados da internet, e não uma falha do próprio instalador do Hagicode Desktop.

Execute o comando abaixo no Terminal. Ele exige privilégios de administrador e remove recursivamente o atributo de quarentena do aplicativo no caminho de instalação padrão:

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

Depois que o comando terminar, reinicie o Hagicode Desktop.

Executar o Desktop

Depois do download, abra o instalador ou o pacote do aplicativo para concluir a instalação e inicie o Hagicode Desktop.

Requisitos de rede

Verifique se sua conexão de rede está funcionando. O Desktop precisa obter da internet as informações de versão e o pacote de instalação do Hagicode Server; se o download falhar, verifique as configurações de rede, de proxy ou de firewall e tente novamente.

Guia de primeira inicialização

Na primeira vez que você abrir o Desktop, ele exibe primeiro o guia de primeiro uso do próprio Desktop (tela “Configuração inicial”). Esse guia serve apenas para instalar e iniciar o Hagicode Server e inclui, em ordem:

1. Escolher idioma: escolha o idioma usado pelo Desktop. Na primeira inicialização do backend integrado, o idioma padrão correspondente também será usado.
2. Boas-vindas: conheça os preparativos que este guia vai concluir.
3. Confirmar documentos legais: confirme as revisões atuais do EULA e da Política de Privacidade; os documentos oficiais são abertos no navegador para leitura.
4. Baixar o Hagicode Server: baixe o pacote de instalação mais recente do Server e verifique seu resumo.

Depois do download, volte à página inicial do Desktop e clique em “Iniciar serviço” para iniciar o Hagicode Server; em seguida, siga as instruções da página inicial para abrir a interface Web.

As etapas podem estar incompletas

Em alguns canais de distribuição (por exemplo, versões que já trazem o Server no pacote de instalação), ou quando, após uma atualização de versão, só é preciso reconfirmar os documentos legais, o guia exibe apenas parte dessas etapas.

Primeiro acesso à interface Web

Ao entrar pela primeira vez na interface Web, aparece o assistente de inicialização (que é algo diferente do guia de primeiro uso do Desktop descrito acima). Ele ajuda você a escolher o idioma e o tema da interface, configurar o Hagicoder padrão e criar o primeiro projeto. Para ver os passos detalhados, leia:

Configuração do assistente de inicializaçãoConfigure o idioma, o tema, o Hagicoder padrão e o primeiro projeto.

Gerenciamento de versão

O Hagicode Desktop oferece suporte ao gerenciamento de várias versões, permitindo alternar livremente entre elas.

Trocar de versão

1. Abra o Hagicode Desktop
2. Vá para a página “Gerenciamento de versão”
3. Selecione a versão para a qual deseja mudar
4. Clique no botão “Alterar versão”
5. Aguarde a conclusão da troca

Observações sobre a troca de versão

• A troca de versão reinicia automaticamente o Hagicode Server
• Salve todo o seu trabalho antes de trocar
• As configurações de projeto podem diferir entre as versões

Iniciar e parar o serviço

O Hagicode Desktop oferece uma forma simples de gerenciar o serviço Hagicode Server.

Iniciar o serviço

Na página inicial do aplicativo Desktop, clique no botão “Iniciar serviço” para iniciar o Hagicode Server.

Parar o serviço

Para parar o Hagicode Server, clique no botão “Parar serviço” na página inicial.

Estado do serviço

O aplicativo Desktop exibe em tempo real o estado de execução do Hagicode Server, incluindo:

• Estado do serviço (em execução / parado)
• Número da porta do serviço
• Informações da versão atual

Próximos passos

Depois de concluir a instalação, você pode seguir com os passos abaixo:

Configuração do assistente de inicializaçãoDepois da primeira inicialização, crie seu projeto aqui e siga o fluxo padrão de início rápido.

Criar uma sessão de conversaEntenda o projeto no modo somente leitura padrão e mude para o modo de edição só quando precisar.

Criar uma sessão de propostaConheça o fluxo de desenvolvimento orientado por propostas, que transforma ideias abstratas em planos de implementação estruturados.

Solução de problemas

Falha na instalação

Se você tiver problemas durante a instalação:

1. Verifique a conexão de rede: confirme que é possível acessar a internet
2. Verifique o espaço em disco: confirme que há espaço em disco suficiente
3. Execute como administrador: no Windows, clique com o botão direito no instalador e selecione “Executar como administrador”
4. Leia as mensagens do instalador: anote a mensagem de erro exibida pelo instalador e inclua-a ao abrir uma Issue

Não encontro o Node.js, o npm ou o Git

Se o Desktop avisar que falta node, npm ou git, ou que a versão do Node.js é muito antiga:

1. Confirme que estão instalados: execute node --version, npm --version e git --version no terminal. O Node.js precisa ser 24 ou superior; para instalar, veja Instalar o Node.js e Instalar o Git.
2. Reinicie o Desktop: o Desktop lê o PATH do sistema ao iniciar. Depois de instalar, feche o Desktop por completo, abra-o novamente e atualize a página de dependências.
3. Verifique o PATH: se os comandos funcionam no terminal, mas o Desktop não os encontra, normalmente o PATH só vale em uma configuração de shell específica (por exemplo, definido em .bashrc / .zshrc via nvm ou fnm). Use uma instalação em nível de sistema ou garanta que o Desktop seja iniciado a partir de um ambiente que enxergue esse PATH.
4. Instale o pacote CLI manualmente: quando o Desktop avisar que um pacote CLI precisa ser instalado manualmente, execute o comando indicado em um terminal fora do Desktop e, ao terminar, volte ao Desktop e atualize. Sobre o comportamento do ambiente externo de Node / npm e do PATH, veja Como o Desktop usa o seu ambiente Node.

Falha na inicialização do serviço

Se o Hagicode Server não iniciar:

1. Verifique se a porta está em uso: o Desktop usa por padrão a porta 36556 (a página inicial mostra a porta realmente em uso); confirme que ela não está ocupada por outro programa
2. Verifique as configurações do firewall: confirme que o firewall permite o acesso do Hagicode Server à rede
3. Reinicie o aplicativo: tente reiniciar o Hagicode Desktop
4. Veja os logs: consulte os logs de erro detalhados no aplicativo Desktop

Precisa de mais ajuda?

Se você encontrar problemas que não são tratados aqui:

1. Consulte as Issues do Desktop no GitHub em busca de problemas semelhantes
2. Visite nosso fórum da comunidade para pedir ajuda
3. Abra uma nova Issue, descrevendo o problema em detalhes e anexando a versão do sistema, a saída de node --version e os logs do Desktop