Which Hermes Docker upgrade is safe to promote?
Use Docker Compose to rehearse a Hermes Agent upgrade against an isolated copy of its data. Compare the resolved mounts and image pins, then require state continuity and a verified rollback before promoting.
Distinguish image drift from state drift
Capture the effective image reference and the source, target, and write mode of the data mount before and after the candidate starts. Give your approval record two independent checks. The runtime check asks whether the expected image digest changed. The state check asks whether a fresh container can retrieve a known synthetic session and load a harmless custom skill from the rehearsal copy. A correct image with an empty session list points you toward the mount or the state copy before you investigate the model provider. A correct mount with an unexpected digest points you toward image selection. Use a digest for the exact artifact you approve. Keep the prior digest and a pre-upgrade copy together, because relaunching the old image alone leaves it reading whatever state the candidate already wrote.
Hermes Docker Setup | Hermes AgentCatch the mount override before starting Compose
Review the effective service configuration after applying the same overrides and environment inputs used for deployment. Record the host source as a resolved absolute path, the container destination, and whether the service can write there. For a bind-mount rehearsal, place synthetic data in a dedicated directory, then use that directory across the baseline and candidate starts. A project-relative path can refer to a different directory in another checkout, even when both files display the same short path. If you use a named volume instead, record the resolved volume identity and Docker context to make the equivalent comparison. After the candidate makes a synthetic state change, rehearse recovery on a separate copy of the pre-upgrade data. A successful rollback should recover the original marker and omit the upgrade-only marker.
How Compose works | Docker DocsChoose what belongs in Docker
Hermes supports two Docker arrangements. Running Hermes in Docker puts the agent process in the container. Using Docker as the terminal backend keeps the agent on the host and puts its shell commands in a persistent sandbox for the life of the Hermes process. Choose the first arrangement to deploy the gateway as a container, or the second if you already run the gateway on the host and want containerized shell execution.
Record where the gateway process runs and where its data lives. Before starting a containerized gateway, identify any existing host gateway and plan a handoff. If your test message still gets a reply with the new container stopped, check which process actually answered before calling the deployment successful.
Hermes Docker Setup | Hermes AgentUse one data path for both runs
For a persistent service, use a Compose YAML file to record the service configuration. Confirm the full Hermes image reference and setup and gateway invocations in the official Docker guide for your release. Choose a dedicated host directory, record its absolute path, and mount it at /opt/data for both the one-time setup and the long-running gateway. Run setup first, then start the service with the same mount.
Inspect the running service's mounts and startup logs before sending a test request. A passing run shows the expected host path at /opt/data and answers through the intended channel. A fresh setup prompt after a successful configuration is a reason to compare the two mounts and check directory permissions.
How Compose works | Docker DocsTest replacement before updating
The Hermes image is stateless. Use a versioned stable image for the trial and record its digest when exact redeployment matters. Back up the mounted directory before an upgrade. A backup can contain credentials and session data, so restrict access to it and make sure you can restore it to a separate test directory.
In an illustrative deployment, the host directory is /srv/hermes-pilot and the test session contains the text pilot-204. Record the session identifier, stop the gateway, and replace the container with one using the same image and mount. Check that the old session still contains pilot-204 and submit a new request. If either check fails, inspect the mount and permissions before changing the image version.
Hermes Docker Setup | Hermes AgentEnable HTTP only for an HTTP client
Hermes has an OpenAI-compatible HTTP endpoint. If a frontend needs it, verify the API server's bind address, port, and authentication settings for your release before publishing a container port. For a chat-channel deployment, start by testing the configured channel. For a frontend on the same host, limit access to that host wherever the client setup permits it.
Test the HTTP route from the actual client location with a valid request, then confirm that a caller without authorization cannot use it. A connection error points first to the bind address or port mapping. An HTTP response with a model or tool error shows the request reached a service and gives you a reason to check the Hermes backend configuration.
API Server | Hermes Agent