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 and an independent recovery copy.
- A supported Docker Engine. Follow Docker IPv6 networking.
- 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 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:
sudo docker network create --ipv6 hermes-ipv6
sudo docker network inspect hermes-ipv6If 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 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.
sudo docker pull nousresearch/hermes-agent
sudo docker image inspect nousresearch/hermes-agent
mkdir -p ~/.hermes
chmod 700 ~/.hermesCheck 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
sudo docker run -it --rm \
--network hermes-ipv6 \
-v "$HOME/.hermes:/opt/data" \
nousresearch/hermes-agent setup- Follow the setup wizard for the intended provider and model.
- Enter credentials only through a private session.
- Configure only messaging accounts you control if a gateway is needed.
- Complete setup and confirm its result before starting a second process.
- 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
sudo docker run -it --rm \
--network hermes-ipv6 \
-v "$HOME/.hermes:/opt/data" \
nousresearch/hermes-agentSend 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:
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 hermesThis 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
- Record the existing image digest and selected configuration.
- Stop the gateway with
sudo docker stop hermes. - Preserve a private copy of the data directory while no agent writes to it.
- Review publisher release notes and any state-format migration requirements.
- Pull the selected replacement image.
- Remove only the stopped container with
sudo docker rm hermes. Do not delete its mounted data. - Recreate it using the gateway command and your selected image.
- 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 for provider network assignments or host faults. Use the Hermes documentation 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.