---
title: "Run Hermes Agent on an IPv6-only guest"
description: "Check endpoint reachability and run the publisher container without granting Docker host control to the agent."
image: "https://8labs.id/opengraph.jpg"
---

> Documentation Index
> Fetch the complete documentation index at: https://8labs.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Hermes Agent on an IPv6-only guest

[Hermes Agent](https://github.com/NousResearch/hermes-agent) is third-party software, not a managed 8Labs feature.
This tutorial is for a guest administrator authorized to run an AI agent and send data to its configured providers.
Do not give an agent customer secrets, production access, or tools beyond its intended task.

## Prerequisites

- Working guest SSH or [console access](https://8labs.id/docs/servers/console/) and an independent recovery copy.
- A supported Docker Engine. Follow [Docker IPv6 networking](https://8labs.id/docs/getting-started/install-docker-ipv6/).
- A provider account, available model, and securely stored credentials.
- Reachable registry, package, API, and messaging endpoints required by your chosen configuration.

Follow [IPv6 endpoint diagnostics](https://8labs.id/docs/getting-started/ipv6-github-dockerhub/) before changing resolvers or adding a proxy.
Do not assume every provider supports IPv6 or that DNS64 supplies a NAT64 gateway.
External API charges and provider policies are separate from your 8Labs service.

## Prepare the container network

Create a dedicated IPv6-enabled network once, then use it for every Hermes container:

```bash
sudo docker network create --ipv6 hermes-ipv6
sudo docker network inspect hermes-ipv6
```

If that network already exists, inspect it instead of recreating it. Confirm IPv6 is enabled and its assigned subnet is appropriate.
Test its egress using the container checks in the Docker guide, replacing `docs-ipv6` with `hermes-ipv6`.
A working guest route or image pull does not prove container egress. Containers without `--network` use Docker's separate default bridge.
Keep this network for setup, interactive sessions, gateway restarts, and updates. Remove it only after all dependent containers are removed.

## Select and inspect the image

The publisher's current [Docker guide](https://hermes-agent.nousresearch.com/docs/user-guide/docker) uses `nousresearch/hermes-agent` and `/opt/data` for persistent state.
The old GHCR image and `/home/hermes/.hermes` example are not this procedure's current storage contract.
Choose a publisher version or digest for repeatable deployment. The commands below use the publisher's moving default tag for illustration.

```bash
sudo docker pull nousresearch/hermes-agent
sudo docker image inspect nousresearch/hermes-agent
mkdir -p ~/.hermes
chmod 700 ~/.hermes
```

Check the image identity before granting credentials. Running Docker with sudo gives the command root-equivalent guest access.
Do not mount `/var/run/docker.sock`, the guest root filesystem, or unrelated credential directories into this agent.
A Docker socket mount can let the agent control the guest through Docker.

## Configure the first session

```bash
sudo docker run -it --rm \
  --network hermes-ipv6 \
  -v "$HOME/.hermes:/opt/data" \
  nousresearch/hermes-agent setup
```

1. Follow the setup wizard for the intended provider and model.
2. Enter credentials only through a private session.
3. Configure only messaging accounts you control if a gateway is needed.
4. Complete setup and confirm its result before starting a second process.
5. Protect the mounted directory and include it in your private recovery plan.

The directory can contain API keys, messages, sessions, and agent state. Never publish it or attach it to a support ticket.
Check any command pasted through a console before executing it. Newlines and incorrect keyboard mappings can change its meaning.

Use only one running container for this data directory. Exit the setup or interactive session before starting the gateway.
If `hermes` already runs, stop it with `sudo docker stop hermes` before using the interactive command.
Do not share `~/.hermes` between simultaneous containers. Concurrent session or memory writes can corrupt state.

## Run interactively

```bash
sudo docker run -it --rm \
  --network hermes-ipv6 \
  -v "$HOME/.hermes:/opt/data" \
  nousresearch/hermes-agent
```

Send a non-sensitive test request. Confirm that the expected model answers and that any external usage belongs to the intended account.
A successful container start does not prove provider authentication, model availability, or every tool integration works.

## Run a messaging gateway

After configuring the intended messaging integration, start one persistent gateway:

```bash
sudo docker run -d \
  --network hermes-ipv6 \
  --name hermes \
  --restart unless-stopped \
  -v "$HOME/.hermes:/opt/data" \
  nousresearch/hermes-agent gateway run
sudo docker ps --filter name=hermes
sudo docker logs --since 10m hermes
```

This example publishes no dashboard or API port. Do not expose one merely to test messaging.
If you require a web interface, follow the publisher's authentication, bind-address, TLS, and reverse-proxy requirements first.
Verify delivery with a private test message from the intended account. Messaging platforms have separate endpoint and permission requirements.
Read logs locally and redact keys, chat identifiers, prompts, and message contents before sharing an error.

## Update, stop, and recover

1. Record the existing image digest and selected configuration.
2. Stop the gateway with `sudo docker stop hermes`.
3. Preserve a private copy of the data directory while no agent writes to it.
4. Review publisher release notes and any state-format migration requirements.
5. Pull the selected replacement image.
6. Remove only the stopped container with `sudo docker rm hermes`. Do not delete its mounted data.
7. Recreate it using the gateway command and your selected image.
8. Verify the provider and a private messaging test again.

Do not assume an older image can read state written by a newer release.
If an update fails, stop the new container and follow the publisher's recovery guidance using your preserved image and data copy.
To stop without removing state, use `sudo docker stop hermes`. Restart deliberately with `sudo docker start hermes`.

## Troubleshooting

| Symptom                         | Safe next action                                                                                                |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Image cannot be pulled          | Check registry DNS, HTTPS, redirects, and your approved egress path.                                            |
| Provider returns 401            | Check the intended provider account and its key locally. Network routing is not the only failure boundary.      |
| Model or quota error            | Check the provider's current catalog, balance, and limits. Do not assume another gateway supports the same API. |
| Gateway is running but no reply | Check messaging setup, allowed recipient, provider response, and redacted logs.                                 |
| Container repeatedly restarts   | Stop it, preserve the error, and check image/configuration compatibility before recreating.                     |
| A key leaks                     | Revoke it at its actual provider and replace the local secret. Removing a container does not revoke a key.      |

Use [8Labs support](https://8labs.id/docs/help/contact/) for provider network assignments or host faults.
Use the [Hermes documentation](https://hermes-agent.nousresearch.com/docs/) for agent configuration, native installation, skills, plugins, and software defects.
No guest install, external model request, or messaging delivery was exercised by this content review.

Source: https://8labs.id/id/docs/getting-started/hermes-agent-ipv6/index.mdx
