openboatmobile-ai/docs/DOCKER_VS_DIRECT.md

Docker vs Direct Installation Guide

Overview

OpenBoatmobile now supports two deployment modes for Hermes Agent:

1. Docker Container (default, docker_enabled = true)

   • Runs Hermes in a Docker container
   • Isolated environment, easier updates
   • Slightly higher resource usage

2. Direct Installation (docker_enabled = false)

   • Installs Hermes directly on the host system
   • Lower resource usage, faster startup
   • hermes command available in PATH
   • Better for dedicated VPS environments

Configuration

Enable Direct Installation

In .env file:

TF_VAR_docker_enabled=false

In terraform.tfvars:

docker_enabled = false

Default Behavior

• docker_enabled = true (Docker container) - Default
• docker_enabled = false (Direct installation)

Deployment Differences

Docker Mode (docker_enabled = true)

Installation:

• Installs Docker and docker-compose
• Pulls nousresearch/hermes-agent:latest
• Runs in container with volume mounts

Management:

# Check status
docker ps | grep hermes

# View logs
docker logs hermes

# Restart
docker restart hermes

# Access hermes CLI
docker exec hermes hermes --help

Resource Usage:

• ~200MB additional RAM for Docker daemon
• Container overhead (~50MB RAM)
• Isolated filesystem

Direct Mode (docker_enabled = false)

Installation:

• Installs uv package manager from Astral
• Clones github.com/NousResearch/hermes-agent repository
• Creates Python 3.11 virtual environment
• Installs with uv pip install -e ".[messaging]" (Discord/Slack/Telegram support)
• Creates /usr/local/bin/hermes wrapper script

Management:

# Check status
systemctl status hermes.service

# View logs
journalctl -u hermes.service -f

# Restart
systemctl restart hermes.service

# Access hermes CLI directly
hermes --help
hermes gateway status

Resource Usage:

• Minimal overhead (~20MB RAM for venv)
• Direct process execution
• Shared filesystem with host

File Locations

Docker Mode

/home/hermes/.hermes/          # Config and data (host)
/var/lib/docker/                # Container runtime

Direct Mode

/home/hermes/.hermes/               # Config and data
/home/hermes/hermes-agent/          # Git repository
/home/hermes/hermes-agent/venv/     # Python virtual environment
/usr/local/bin/hermes              # CLI wrapper script
/root/.local/bin/uv                # uv package manager

Command Line Access

Docker Mode

# Run hermes commands
docker exec hermes hermes --version
docker exec hermes hermes gateway status

# Or create alias for convenience
echo "alias hermes='docker exec hermes hermes'" >> ~/.bashrc

Direct Mode

# hermes command is directly available
hermes --version
hermes gateway status
hermes --help

Health Checks

Docker Mode

/usr/local/bin/hermes-health-check.sh
# Checks: Docker daemon, container status, port 18789, config files

Direct Mode

/usr/local/bin/hermes-health-check.sh
# Checks: hermes binary, venv, process status, port 18789, config files

Troubleshooting

Docker Mode Issues

# Docker daemon not running
sudo systemctl start docker

# Container crashed
docker logs hermes
docker restart hermes

# Permission issues
sudo usermod -aG docker $USER
newgrp docker

Direct Mode Issues

# hermes command not found
which hermes
ls -la /usr/local/bin/hermes
cat /usr/local/bin/hermes  # Check wrapper script content

# Virtual environment issues
ls -la ~/hermes-agent/venv/
ls -la ~/hermes-agent/venv/bin/hermes

# Check if repo was cloned
ls -la ~/hermes-agent/

# Check if uv is installed
ls -la /root/.local/bin/uv

# Service not starting
journalctl -u hermes.service -n 20
systemctl status hermes.service

# Reinstall manually
cd ~
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
/root/.local/bin/uv venv venv --python 3.11
/root/.local/bin/uv pip install -e '.[messaging]'

Migration Between Modes

From Docker to Direct

1. Set docker_enabled = false
2. Run terraform apply
3. Data in ~/.hermes/ is preserved
4. hermes command becomes available

From Direct to Docker

1. Set docker_enabled = true
2. Run terraform apply
3. Data in ~/.hermes/ is preserved
4. Use docker exec hermes hermes for CLI access

Performance Comparison

Metric	Docker Mode	Direct Mode	Difference
RAM Usage	~400MB	~200MB	-50%
Startup Time	~15s	~5s	-67%
Disk Usage	~2GB	~1GB	-50%
hermes CLI	docker exec	Direct	Simpler in Direct
Isolation	Full	None	Docker more secure

Recommendations

Use Docker Mode When:

• Running multiple services on the same server
• Wanting easy rollback/updates
• Security isolation is important
• Using cloud environments with limited control

Use Direct Mode When:

• Dedicated VPS for Hermes only
• Wanting minimal resource usage
• Needing fastest possible startup
• Wanting direct CLI access without docker exec

Examples

Minimal Direct Installation

# terraform.tfvars
cloud_provider = "hetzner"
agent_framework = "hermes"
docker_enabled = false
venice_api_key = "your-key"
ssh_key_names = ["your-key"]

Docker Installation with Custom User

# terraform.tfvars
cloud_provider = "hetzner"
agent_framework = "hermes"
docker_enabled = true
admin_user = "ai-admin"  # Override default 'hermes'
venice_api_key = "your-key"
ssh_key_names = ["your-key"]

Support

Both modes are fully supported. The direct mode is recommended for dedicated VPS deployments where you want the hermes command directly available in your PATH.