Moving a project from Codex to Hermes on a server

For help using the service, see the Ailoot documentation.

What to prepare before the transfer#

A repository is a project folder with its Git change history. A working copy contains the files you edit. The task here is to get that copy onto the server and continue development. You do not need to make the application available to visitors yet.

If the agent is not installed on the server yet, start with installing Hermes Agent on a VPS. Here, you will need a working Hermes installation, the server terminal and Git. You need a remote repository that is accessible from the server; if you do not have one yet, create it first and save the project there without secrets. For a private repository, set up read access from your own account in advance; do not put a token in the repository URL or in a message to the agent.

Pause parallel edits to the project during the transfer. On the source computer, open a terminal in the project folder itself and run:

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

The first command shows the branch and the state of the files. M means a modification, and ?? means a file that Git does not track yet. In the second command, ignored files are marked with !!. A normal clean status does not prove that you have no necessary files outside Git.

Save the necessary changes in a separate commit and push the right branch to your remote repository in your usual way. Before pushing, check what the commit contains: keys, passwords and real user data must not be included. If you do not know which changes to save, first ask Codex to list them and explain their purpose, without deleting files or pushing to the repository.

Do not assume that cloning the repository will transfer an external database, the contents of an ignored folder or your conversations with Codex. Chat history, subscriptions, profiles and the agents' own settings are not part of this transfer method.

Copy the right branch to the server#

First, save the output of this command on the source computer:

git status --porcelain=v2 --branch

The # branch.oid line shows the current commit, and # branch.head shows the branch. A commit is a saved version of the project. For a typical project with existing commits, this lets you compare the source and new copies; this comparison does not check uncommitted changes.

On the server, go to the directory where you will store your projects. Clone your repository into a new folder. In the template below, replace REPOSITORY_URL with your repository URL, BRANCH_NAME with the name of the branch you saved and pushed, and my-project with the name you want for the new folder:

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

This is a template, not a ready-made URL to copy. git clone creates a folder and a working copy of the selected branch. If the destination folder already exists, it must be empty: do not delete its contents to rerun the command; choose a new name.

Compare # branch.oid in both copies. If the values differ, do not start fixing code on the server: check the selected branch, the commits you pushed and whether parallel changes were made. If the status output shows modified files, investigate them separately. Do not use cleanup or a forced reset as a way to “make them match.”

Repositories with Git submodules—nested repositories—also require you to fetch their contents. git clone has a --recurse-submodules option for this; use it if the project actually contains submodules and their URLs have been checked. Projects with other external resources may require an additional procedure described in the README.

Restore dependencies according to the project's rules#

First, read the README and the project configuration files. Find out which runtime version is required and which package manager is used to install dependencies. Do not replace the project's usual tool with npm just because it appears in the example below.

A hypothetical example for Node.js and npm: the repository has consistent package.json and package-lock.json files, and a version of Node.js suitable for the project is installed on the server. In that case, run this in the project folder:

npm ci

According to the npm ci documentation, the command installs dependencies for the entire project from the lockfile without rewriting package.json or package-lock.json. If their contents are inconsistent, installation fails. Any existing node_modules folder is deleted before installation.

If the lockfile was created with options that affect the dependency tree, such as --legacy-peer-deps, npm ci needs the same options. Check the source project's instructions and settings. Do not delete the lockfile or update all dependencies to hide the first transfer error.

Before installing, check the installation and startup commands in your own project. Run them in a separate working copy without access to production data, and set any necessary environment values outside chat and Git. Where possible, use test credentials with limited permissions to check the project. If the project depends on a database or files, first restore a permitted test dataset according to its instructions; identical source files do not replace that data.

After installation, run the existing checks from the README: tests and a build, if provided. Command names depend on the project. Successfully installing dependencies does not yet mean that the application works.

Open the working copy in Hermes#

In the server terminal, go to the root of the new copy and start the agent that is already installed:

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

Here, /absolute/path/to/my-project is a placeholder for the full path to your project. On the Hermes startup screen, check the working directory and the environment in which terminal commands run. This startup method is intended for Hermes's local terminal environment on the server. If SSH or Docker is configured, the agent may run commands in another environment; first confirm the project path available there.

Ask the agent to confirm its actual working folder using its terminal tool, then read the README and the project instructions. Do not treat a folder name in a message as sufficient verification.

The order below is stated in a pinned version of the documentation and may differ in your installed version of Hermes. Check the current instructions in your session. Hermes supports AGENTS.md, but whether it reads that file depends on the priorities of context files. According to the official Hermes documentation, one type of instruction file is selected: .hermes.md, then AGENTS.override.md, AGENTS.md, CLAUDE.md and .cursorrules. Check for an old .hermes.md or a personal AGENTS.override.md before starting work: do not assume that the agent will necessarily apply the AGENTS.md alongside it.

In the selected instructions, retain the project's purpose, check commands and restrictions on changes. Do not turn them into an archive of conversations. If you need to transfer the agents' settings themselves, that is a different process; its scope is explained in the guide to migrating from Claude Code to Codex.

Give the agent one task and check the result#

Start by reading the project, without making changes. For example:

We are working with an existing project in the folder I specified.
Confirm the actual working directory using the terminal tool.
Read the README and the current project instructions.
Do not open files containing secrets or print environment values.
List the check commands and the prerequisites for running them.
For now, do not change or install anything, or push to the repository.

Then agree on one small task, such as correcting text in the interface. Specify the files or area to change, and prohibit incidental dependency updates. If you want to separate the experiment from the main copy, first learn about a separate Git worktree working copy.

Accept the result based on the file changes and repeated project checks. Before a potentially unsuccessful experiment, save the source copy and a recovery point; do not ask the agent to reset all changes in bulk. If a check fails, compare the error with the source copy: this helps distinguish a transfer problem from a defect that was already there.

The transfer can be considered complete when the required version of the source files is in place, the environment has been restored, the necessary data is available in a safe test environment, the checks pass, and Hermes is working in this exact folder. Publishing the application for visitors is a separate next stage and is not part of this check.

Get to know Ailoot.