Run Hermes Agent with Docker Compose
Run Hermes Agent in Docker with docker-compose for easy deployment, isolation, and reproducibility.
Running Hermes in Docker gives you clean isolation, easy version pinning, and reproducible deployments. It's the preferred setup for security-conscious self-hosters who want a contained agent environment.
Before you start:
- ☑Docker and docker-compose installed on your machine or server
- ☑Basic familiarity with Docker and environment variables
- ☑Your API keys and bot tokens ready
Steps
- 1
Install Docker
Install Docker and docker-compose on your machine or server
- 2
Get the compose file
Download docker-compose.yml from the Hermes repo or create one with the hermes-agent image
- 3
Configure environment
Create a .env file with your API keys, bot tokens, and model configuration
- 4
Mount volumes
Mount ~/.hermes/ as a volume so memory and skills persist across container restarts
- 5
Start the container
docker-compose up -d to start Hermes in the background
- 6
View logs
docker-compose logs -f hermes to tail the agent's output
Pro Tips
- 💡Always mount ~/.hermes/ as a named volume — without this, all memory and skills are lost when the container restarts
- 💡Use a specific version tag (e.g. 'hermes-agent:0.6.0') for reproducible deployments rather than 'latest' in production
- 💡Docker's read-only root filesystem mode provides extra security — pair it with tmpfs for /tmp to allow temporary file operations
Troubleshooting
❌ Container starts but Hermes cannot access the internet
✅ Check Docker network mode. If running on a VPS with a firewall, ensure the Docker bridge subnet has outbound access rules.
❌ Memory not persisting between container restarts
✅ Verify your volume mount in docker-compose.yml: '- ~/.hermes:/root/.hermes'. Without this mount, the container's /root/.hermes is ephemeral and lost on restart.
❌ Permission errors on mounted volumes
✅ The container runs as root by default. If you mounted a directory owned by another user, run 'chown -R root:root ~/.hermes' or set the correct UID in your docker-compose.yml.