Spostare un progetto da Codex a Hermes su un server

Per assistenza sull'uso del servizio, consulta la documentazione di Ailoot.

Cosa preparare prima del trasferimento#

Un repository è una cartella di progetto con la cronologia delle modifiche Git. Una copia di lavoro contiene i file che modifichi. In questo caso, devi trasferire quella copia sul server e continuare lo sviluppo. Non è ancora necessario rendere l'applicazione disponibile ai visitatori.

Se l'agente non è ancora installato sul server, inizia con installare Hermes Agent su un VPS. Qui ti serviranno un'installazione funzionante di Hermes, il terminale del server e Git. Hai bisogno di un repository remoto accessibile dal server; se ancora non ne hai uno, crealo prima e salvaci il progetto senza segreti. Per un repository privato, configura in anticipo l'accesso in lettura dal tuo account; non inserire un token nell'URL del repository o in un messaggio all'agente.

Sospendi le modifiche parallele al progetto durante il trasferimento. Sul computer di origine, apri un terminale nella cartella del progetto e lancia:

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

Il primo comando mostra il branch e lo stato dei file. M indica una modifica e ?? un file che Git non tiene ancora sotto controllo. Nel secondo comando, i file ignorati sono contrassegnati con !!. Uno stato normale e pulito non dimostra che non ci siano file necessari al di fuori di Git.

Salva le modifiche necessarie in un commit separato e invia il branch corretto al repository remoto nel modo consueto. Prima di inviarlo, controlla cosa contiene il commit: non deve includere chiavi, password o dati reali degli utenti. Se non sai quali modifiche salvare, chiedi prima a Codex di elencarle e spiegarne lo scopo, senza eliminare file né inviarle al repository.

Non dare per scontato che clonare il repository trasferisca un database esterno, il contenuto di una cartella ignorata o le tue conversazioni con Codex. La cronologia delle chat, gli abbonamenti, i profili e le impostazioni degli agenti non fanno parte di questo metodo di trasferimento.

Copiare il branch corretto sul server#

Per prima cosa, salva l'output di questo comando sul computer di origine:

git status --porcelain=v2 --branch

La riga # branch.oid mostra il commit corrente e # branch.head il branch. Un commit è una versione salvata del progetto. Per un progetto tipico con commit esistenti, questo ti consente di confrontare la copia di origine e quella nuova; il confronto non verifica le modifiche non salvate.

Sul server, vai alla directory in cui conserverai i progetti. Clona il repository in una nuova cartella. Nel modello qui sotto, sostituisci REPOSITORY_URL con l'URL del tuo repository, BRANCH_NAME con il nome del branch che hai salvato e inviato e my-project con il nome che vuoi dare alla nuova cartella:

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

Questo è un modello, non un URL pronto da copiare. git clone crea una cartella e una copia di lavoro del branch selezionato. Se la cartella di destinazione esiste già, deve essere vuota: non eliminarne il contenuto per rilanciare il comando; scegli un nuovo nome.

Confronta # branch.oid nelle due copie. Se i valori differiscono, non iniziare a correggere il codice sul server: controlla il branch selezionato, i commit che hai inviato e se sono state apportate modifiche parallele. Se l'output dello stato mostra file modificati, esaminali separatamente. Non usare la pulizia o un ripristino forzato per «farli coincidere».

Anche i repository con submodule Git, cioè repository annidati, richiedono il recupero dei loro contenuti. git clone offre l'opzione --recurse-submodules; usala se il progetto contiene davvero submodule e i relativi URL sono stati verificati. I progetti con altre risorse esterne possono richiedere una procedura aggiuntiva descritta nel README.

Ripristinare le dipendenze secondo le regole del progetto#

Per prima cosa, leggi il README e i file di configurazione del progetto. Verifica quale versione del runtime serve e quale gestore di pacchetti viene usato per installare le dipendenze. Non sostituire lo strumento abituale del progetto con npm solo perché compare nell'esempio qui sotto.

Esempio ipotetico per Node.js e npm: il repository contiene file package.json e package-lock.json coerenti e sul server è installata una versione di Node.js adatta al progetto. In tal caso, esegui questo comando nella cartella del progetto:

npm ci

Secondo la documentazione di npm ci, il comando installa le dipendenze dell'intero progetto dal lockfile senza riscrivere package.json o package-lock.json. Se il loro contenuto non è coerente, l'installazione non riesce. Prima dell'installazione viene eliminata qualsiasi cartella node_modules esistente.

Se il lockfile è stato creato con opzioni che influiscono sull'albero delle dipendenze, come --legacy-peer-deps, npm ci deve usare le stesse opzioni. Controlla le istruzioni e le impostazioni del progetto di origine. Non eliminare il lockfile né aggiornare tutte le dipendenze per nascondere il primo errore di trasferimento.

Prima di installare, controlla i comandi di installazione e avvio del tuo progetto. Eseguili in una copia di lavoro separata, senza accesso ai dati di produzione, e imposta gli eventuali valori d'ambiente necessari al di fuori della chat e di Git. Se possibile, usa credenziali di test con permessi limitati per verificare il progetto. Se il progetto dipende da un database o da file, ripristina prima un insieme di dati di test consentito secondo le istruzioni: file sorgente identici non sostituiscono quei dati.

Dopo l'installazione, esegui i controlli esistenti indicati nel README: test e build, se previsti. I nomi dei comandi dipendono dal progetto. Il fatto che le dipendenze si installino correttamente non significa ancora che l'applicazione funzioni.

Aprire la copia di lavoro in Hermes#

Nel terminale del server, vai alla radice della nuova copia e avvia l'agente già installato:

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

Qui /absolute/path/to/my-project è un segnaposto per il percorso completo del progetto. Nella schermata di avvio di Hermes, controlla la directory di lavoro e l'ambiente in cui vengono eseguiti i comandi del terminale. Questo metodo di avvio è pensato per l'ambiente del terminale locale di Hermes sul server. Se SSH o Docker sono configurati, l'agente potrebbe eseguire i comandi in un altro ambiente; verifica prima che il percorso del progetto sia disponibile lì.

Chiedi all'agente di confermare la cartella di lavoro effettiva usando il suo strumento terminale, quindi di leggere il README e le istruzioni del progetto. Il nome di una cartella menzionato in un messaggio non è una verifica sufficiente.

L'ordine riportato qui è indicato in una versione fissata della documentazione e potrebbe essere diverso nella versione di Hermes installata. Controlla le istruzioni aggiornate nella tua sessione. Hermes supporta AGENTS.md, ma la lettura di quel file dipende dalle priorità dei file di contesto. Secondo la documentazione ufficiale di Hermes, viene selezionato un solo tipo di file di istruzioni, in quest'ordine: .hermes.md, poi AGENTS.override.md, AGENTS.md, CLAUDE.md e .cursorrules. Prima di iniziare a lavorare, controlla se ci sono un vecchio .hermes.md o un tuo AGENTS.override.md: non presumere che l'agente applichi necessariamente anche AGENTS.md insieme a un altro file.

Nelle istruzioni selezionate, conserva lo scopo del progetto, i comandi di controllo e le restrizioni sulle modifiche. Non trasformarle in un archivio delle conversazioni. Se devi trasferire anche le impostazioni degli agenti, si tratta di un processo diverso, illustrato nella guida alla migrazione da Claude Code a Codex.

Assegnare un'attività all'agente e controllare il risultato#

Inizia leggendo il progetto, senza apportare modifiche. Per esempio:

Stiamo lavorando a un progetto esistente nella cartella che ho indicato.
Conferma la directory di lavoro effettiva usando lo strumento terminale.
Leggi il README e le istruzioni attuali del progetto.
Non aprire file che contengono segreti né mostrare valori d'ambiente.
Elenca i comandi di controllo e i prerequisiti per eseguirli.
Per ora, non modificare né installare nulla e non inviare modifiche al repository.

Poi concorda un'attività circoscritta, per esempio correggere un testo nell'interfaccia. Specifica i file o l'area da modificare e vieta gli aggiornamenti incidentali delle dipendenze. Se vuoi separare l'esperimento dalla copia principale, informati prima su una copia di lavoro Git worktree separata.

Accetta il risultato in base alle modifiche ai file e all'esecuzione ripetuta dei controlli del progetto. Prima di un esperimento che potrebbe non riuscire, salva la copia di origine e un punto di ripristino; non chiedere all'agente di ripristinare in blocco tutte le modifiche. Se un controllo non riesce, confronta l'errore con la copia di origine: questo aiuta a distinguere un problema di trasferimento da un difetto già presente.

Il trasferimento si può considerare completo quando è presente la versione richiesta dei file sorgente, l'ambiente è stato ripristinato, i dati necessari sono disponibili in un ambiente di test sicuro, i controlli passano e Hermes lavora in questa precisa cartella. La pubblicazione dell'applicazione per i visitatori è una fase successiva separata e non rientra in questa verifica.

Scopri Ailoot.