Transferir um projeto do Codex para o Hermes num servidor

Para obter ajuda sobre a utilização do serviço, consulte a documentação do Ailoot.

O que preparar antes da transferência#

Um repositório é uma pasta de projeto com o histórico de alterações do Git. Uma cópia de trabalho contém os ficheiros que edita. O objetivo é colocar essa cópia no servidor e continuar o desenvolvimento. Ainda não precisa de disponibilizar a aplicação aos visitantes.

Se o agente ainda não estiver instalado no servidor, comece por instalar o Hermes Agent num VPS. Neste caso, precisa de uma instalação funcional do Hermes, do terminal do servidor e do Git. Precisa de um repositório remoto acessível a partir do servidor; se ainda não tiver um, crie-o primeiro e guarde lá o projeto sem segredos. No caso de um repositório privado, configure antecipadamente o acesso de leitura a partir da sua própria conta; não inclua um token no URL do repositório nem numa mensagem para o agente.

Suspenda as edições paralelas ao projeto durante a transferência. No computador de origem, abra um terminal na própria pasta do projeto e execute:

git status --short --branch
git status --short --ignored

O primeiro comando mostra o ramo e o estado dos ficheiros. M significa uma alteração e ?? significa um ficheiro que o Git ainda não controla. No segundo comando, os ficheiros ignorados são assinalados com !!. Um estado normal e limpo não prova que não tem ficheiros necessários fora do Git.

Guarde as alterações necessárias num commit separado e envie o ramo correto para o repositório remoto da forma habitual. Antes de o enviar, verifique o que o commit contém: não deve incluir chaves, palavras-passe nem dados reais de utilizadores. Se não souber que alterações deve guardar, peça primeiro ao Codex que as enumere e explique a finalidade de cada uma, sem eliminar ficheiros nem enviar alterações para o repositório.

Não parta do princípio de que a clonagem do repositório transfere uma base de dados externa, o conteúdo de uma pasta ignorada ou as suas conversas com o Codex. O histórico do chat, as subscrições, os perfis e as próprias definições dos agentes não fazem parte deste método de transferência.

Copie o ramo correto para o servidor#

Primeiro, guarde no computador de origem o resultado deste comando:

git status --porcelain=v2 --branch

A linha # branch.oid mostra o commit atual e # branch.head mostra o ramo. Um commit é uma versão guardada do projeto. Num projeto típico com commits existentes, isto permite comparar a cópia de origem com a nova cópia; esta comparação não verifica alterações ainda não submetidas num commit.

No servidor, aceda ao diretório onde irá guardar os projetos. Clone o repositório para uma nova pasta. No modelo abaixo, substitua REPOSITORY_URL pelo URL do seu repositório, BRANCH_NAME pelo nome do ramo que guardou e enviou, e my-project pelo nome que pretende dar à nova pasta:

git clone --branch BRANCH_NAME REPOSITORY_URL my-project
cd my-project
git status --porcelain=v2 --branch

Isto é um modelo, não um URL pronto a copiar. git clone cria uma pasta e uma cópia de trabalho do ramo selecionado. Se a pasta de destino já existir, tem de estar vazia: não elimine o conteúdo para voltar a executar o comando; escolha um nome novo.

Compare # branch.oid nas duas cópias. Se os valores forem diferentes, não comece a corrigir código no servidor: verifique o ramo selecionado, os commits que enviou e se foram feitas alterações em paralelo. Se o resultado do estado mostrar ficheiros modificados, investigue-os separadamente. Não use uma limpeza nem uma reposição forçada para os «fazer corresponder».

Os repositórios com submódulos do Git — repositórios aninhados — também exigem que obtenha o respetivo conteúdo. git clone tem a opção --recurse-submodules para este efeito; use-a se o projeto realmente contiver submódulos e se os respetivos URLs tiverem sido verificados. Os projetos com outros recursos externos podem exigir um procedimento adicional descrito no README.

Restaure as dependências de acordo com as regras do projeto#

Primeiro, leia o README e os ficheiros de configuração do projeto. Descubra que versão do ambiente de execução é necessária e que gestor de pacotes é usado para instalar as dependências. Não substitua a ferramenta habitual do projeto por npm só por aparecer no exemplo abaixo.

Exemplo hipotético para Node.js e npm: o repositório tem ficheiros package.json e package-lock.json coerentes e está instalada no servidor uma versão do Node.js adequada ao projeto. Nesse caso, execute o seguinte na pasta do projeto:

npm ci

De acordo com a documentação do npm ci, o comando instala as dependências de todo o projeto a partir do ficheiro de bloqueio, sem reescrever package.json nem package-lock.json. Se os respetivos conteúdos forem incoerentes, a instalação falha. Qualquer pasta node_modules existente é eliminada antes da instalação.

Se o ficheiro de bloqueio tiver sido criado com opções que afetam a árvore de dependências, como --legacy-peer-deps, npm ci precisa das mesmas opções. Verifique as instruções e as definições do projeto de origem. Não elimine o ficheiro de bloqueio nem atualize todas as dependências para ocultar o primeiro erro da transferência.

Antes de instalar, verifique os comandos de instalação e de arranque do seu projeto. Execute-os numa cópia de trabalho separada, sem acesso a dados de produção, e defina quaisquer valores de ambiente necessários fora do chat e do Git. Sempre que possível, use credenciais de teste com permissões limitadas para verificar o projeto. Se o projeto depender de uma base de dados ou de ficheiros, restaure primeiro um conjunto de dados de teste permitido, de acordo com as respetivas instruções; ficheiros de origem idênticos não substituem esses dados.

Após a instalação, execute as verificações existentes no README: testes e uma compilação, se estiverem disponíveis. Os nomes dos comandos dependem do projeto. Instalar as dependências com êxito ainda não significa que a aplicação funciona.

Abra a cópia de trabalho no Hermes#

No terminal do servidor, aceda à raiz da nova cópia e inicie o agente já instalado:

cd /absolute/path/to/my-project
hermes

Aqui, /absolute/path/to/my-project é um marcador para o caminho completo do seu projeto. No ecrã de arranque do Hermes, verifique o diretório de trabalho e o ambiente em que são executados os comandos do terminal. Este método de arranque destina-se ao ambiente de terminal local do Hermes no servidor. Se o SSH ou o Docker estiver configurado, o agente poderá executar comandos noutro ambiente; confirme primeiro o caminho do projeto disponível nesse ambiente.

Peça ao agente que confirme a pasta de trabalho efetiva através da ferramenta de terminal e, em seguida, leia o README e as instruções do projeto. Não considere suficiente a indicação do nome de uma pasta numa mensagem.

A ordem abaixo consta de uma versão fixa da documentação e pode diferir da versão do Hermes que tem instalada. Verifique as instruções atuais na sua sessão. O Hermes suporta AGENTS.md, mas a leitura desse ficheiro depende das prioridades dos ficheiros de contexto. Segundo a documentação oficial do Hermes, é selecionado um tipo de ficheiro de instruções: .hermes.md, depois AGENTS.override.md, AGENTS.md, CLAUDE.md e .cursorrules. Antes de começar a trabalhar, verifique se existe um .hermes.md antigo ou um AGENTS.override.md pessoal: não parta do princípio de que o agente irá necessariamente aplicar o AGENTS.md que esteja ao lado desses ficheiros.

Nas instruções selecionadas, mantenha a finalidade do projeto, os comandos de verificação e as restrições às alterações. Não as transforme num arquivo de conversas. Se precisar de transferir as próprias definições dos agentes, esse é um processo diferente; o respetivo âmbito é explicado no guia para migrar do Claude Code para o Codex.

Atribua uma tarefa ao agente e verifique o resultado#

Comece por ler o projeto sem fazer alterações. Por exemplo:

Estamos a trabalhar num projeto existente na pasta que indiquei.
Confirma o diretório de trabalho efetivo através da ferramenta de terminal.
Lê o README e as instruções atuais do projeto.
Não abras ficheiros que contenham segredos nem apresentes valores do ambiente.
Lista os comandos de verificação e os pré-requisitos para os executar.
Por agora, não alteres nem instales nada e não faças push para o repositório.

Depois, combine uma tarefa pequena, como corrigir texto na interface. Especifique os ficheiros ou a área a alterar e proíba atualizações incidentais das dependências. Se quiser separar a experiência da cópia principal, informe-se primeiro sobre uma cópia de trabalho Git worktree separada.

Aceite o resultado com base nas alterações aos ficheiros e nas verificações repetidas do projeto. Antes de uma experiência que possa falhar, guarde a cópia de origem e um ponto de recuperação; não peça ao agente para repor todas as alterações de uma só vez. Se uma verificação falhar, compare o erro com o da cópia de origem: isso ajuda a distinguir um problema de transferência de um defeito que já existia.

A transferência pode ser considerada concluída quando a versão necessária dos ficheiros de origem estiver disponível, o ambiente tiver sido restaurado, os dados necessários estiverem disponíveis num ambiente de teste seguro, as verificações forem aprovadas e o Hermes estiver a trabalhar exatamente nesta pasta. Publicar a aplicação para os visitantes é uma etapa seguinte separada e não faz parte desta verificação.

Conheça o Ailoot.