Migrate Hermes to a New Machine with Docker and GBrain MCP

This article explains how to move Hermes to a new machine while keeping the deployment simple and stable. The two machines are assumed to already be reachable over the network, so the only connectivity checks we need are basic ping, SSH, and container-level verification.

The main goals are:

• keep the Hermes data intact,
• copy the Docker project to the new machine,
• update the GBrain MCP endpoint,
• remove any Docker network settings that are no longer needed,
• verify that Hermes can still reach GBrain after the migration.

Assumption

In this guide, the old machine and the new machine can already communicate with each other using ping. No special networking setup is covered here.

The GBrain MCP endpoint runs on the old machine, so the new Hermes deployment will connect back to that host over the normal network.

Migration flow

Old machine
  ├─ GBrain MCP endpoint
  └─ SSH / rsync ───────────────> New machine
                                  |
                                  v
                           Hermes container
                                  |
                                  v
                    GBrain MCP endpoint on old machine

Before you begin

Make sure you have:

• Docker and Docker Compose installed on the new machine,
• SSH access from the old machine to the new machine,
• GBrain MCP running on the old machine,
• the Hermes project directory on the old machine, for example /root/docker/hermes.

1. Check basic network connectivity

From the new machine, confirm that the two hosts can reach each other over the network.

ping -c 3 <old_machine_ip>
ping -c 3 <new_machine_ip>

If both machines respond, you can continue with SSH and file transfer.

Note

This guide assumes the network path already works. If ping fails, fix the base network connection first before moving on.

2. Verify SSH from the old machine to the new machine

From the old machine, test SSH access to the new machine:

ssh root@<new_machine_ip> "echo OK"

Example:

ssh [email protected] "echo OK"

If the command returns OK, SSH is working and you can skip the key-creation step.

3. If needed, create a dedicated SSH key for the migration

If SSH access is not yet configured, create a temporary key pair on the old machine and authorize it on the new machine.

# On the old machine
ssh-keygen -t ed25519 -C "hermes-migration" -f ~/.ssh/id_ed25519_hermes -N ""
ssh-copy-id -i ~/.ssh/id_ed25519_hermes.pub [email protected]

Test it again:

ssh -i ~/.ssh/id_ed25519_hermes [email protected] "echo OK"

Tip

A dedicated key is safer for one-time migration work because it can be removed later without affecting your normal SSH setup.

4. Stop Hermes on the old machine and copy it to the new machine

Once SSH is ready, stop Hermes on the old machine to avoid data changes during the copy.

# On the old machine
cd /root/docker/hermes
docker compose down

Then copy the whole project directory to the new machine with rsync:

rsync -avz -e "ssh -i ~/.ssh/id_ed25519_hermes" /root/docker/hermes/ [email protected]:/root/docker/hermes/

If SSH already works with your default key, you can simplify the command:

rsync -avz /root/docker/hermes/ [email protected]:/root/docker/hermes/

Note

The trailing slash on /root/docker/hermes/ means “copy the contents of this directory”.

5. Update the GBrain MCP URL in the Hermes config

On the new machine, update the Hermes MCP configuration so it points to the GBrain MCP service running on the old machine.

Example:

mcp_servers:
  gbrain:
    headers:
      Authorization: Bearer ${GBRAIN_TOKEN}
    url: http://<old_machine_ip>:7333/mcp

Why this change is needed

Before the migration, Hermes may have used a Docker-internal hostname or another local shortcut to reach GBrain. After moving Hermes to a new machine, that internal Docker name may no longer exist. The configuration should now point to the real network address of the GBrain MCP service running on the old machine.

Important

Keep the token in an environment variable such as GBRAIN_TOKEN. Do not hardcode secrets directly into the YAML file.

6. Simplify docker-compose.yml on the new machine

If the new machine only runs Hermes, you do not need a custom Docker network such as hermes-net.

A simpler docker-compose.yml can look like this:

services:
  hermes:
    image: nousresearch/hermes-agent:v2026.7.7.2
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    shm_size: '1g'
    ports:
      - "8642:8642"
      - "9119:9119"
    volumes:
      - ./data:/opt/data
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro
    env_file:
      - .env
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - TELEGRAM_ALLOWED_USERS=${TELEGRAM_ALLOWED_USERS}
      - GBRAIN_TOKEN=${GBRAIN_TOKEN}
      - HERMES_DASHBOARD=1
      - HERMES_DASHBOARD_HOST=0.0.0.0
      - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=${HERMES_DASHBOARD_BASIC_AUTH_USERNAME}
      - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=${HERMES_DASHBOARD_BASIC_AUTH_PASSWORD}
      - HERMES_DASHBOARD_BASIC_AUTH_SECRET=${HERMES_DASHBOARD_BASIC_AUTH_SECRET}
    deploy:
      resources:
        limits:
          memory: 3G
          cpus: "2.0"

When to keep a network section

If the new machine also runs other containers that need to talk to Hermes directly, you can keep a custom Docker network. Otherwise, removing it makes the deployment easier to maintain.

7. Start Hermes on the new machine

Start the container and follow the logs.

cd /root/docker/hermes
docker compose up -d
docker compose logs -f hermes

Watch for configuration errors, missing environment variables, or failed MCP initialization.

Tip

If Hermes cannot start, check the .env file first. Most migration issues come from missing tokens or wrong paths.

8. Verify Hermes can reach GBrain from inside the container

Do not stop at host-level testing. Verify the connection from inside the running Hermes container.

docker exec hermes curl -i http://<old_machine_ip>:7333/health

A 200 OK response means:

• Hermes is running correctly inside Docker,
• the container can reach the GBrain host,
• the MCP endpoint is reachable,
• and the migration is successful end to end.

9. Confirm the migration is complete

You can consider the migration finished when all of these are true:

• ping works between the two machines,
• SSH from the old machine to the new machine works,
• the Hermes project has been copied successfully,
• Hermes starts without errors,
• docker exec hermes curl -i http://<old_machine_ip>:7333/health returns 200 OK.

Troubleshooting

1) Ping works, but SSH fails

Check:

• the SSH service on the new machine,
• the destination user,
• firewall rules,
• whether the correct SSH key is being used.

2) The files were copied, but Hermes does not start

Check:

• the .env file,
• volume paths,
• the docker-compose.yml syntax,
• the container logs from docker compose logs -f hermes.

3) Hermes starts, but GBrain is not reachable

Check:

• the old machine IP or hostname,
• the /mcp path,
• the port 7333,
• whether the GBrain service is running on the old machine,
• whether the GBRAIN_TOKEN value is correct.

Summary

The migration process is straightforward:

1. confirm basic network connectivity with ping,
2. verify SSH access,
3. stop Hermes on the old machine,
4. copy the project to the new machine,
5. update the GBrain MCP URL,
6. remove unnecessary Docker network settings,
7. restart Hermes,
8. verify the MCP health endpoint from inside the container.

When the final health check returns 200 OK, Hermes is ready on the new machine and connected to GBrain again.

See also

• Install and Use GBrain MCP in Zoo Code
• Integrate GBrain with Hermes in Docker via MCP HTTP