Hermes Agent — Docker

Có hai cách riêng biệt mà Docker giao tiếp với Hermes Agent:

Chạy Hermes IN Docker — bản thân tác nhân chạy bên trong một vùng chứa (trọng tâm chính của trang này)
Docker dưới dạng chương trình phụ trợ đầu cuối — tác nhân chạy trên máy chủ của bạn nhưng thực thi các lệnh bên trong hộp cát Docker (xem Cấu hình → terminal.backend)

Trang này bao gồm tùy chọn 1. Vùng chứa lưu trữ tất cả dữ liệu người dùng (cấu hình, khóa API, phiên, kỹ năng, ký ức) trong một thư mục được gắn từ máy chủ tại /opt/data . Bản thân hình ảnh không có trạng thái và có thể được nâng cấp bằng cách lấy phiên bản mới mà không làm mất bất kỳ cấu hình nào.

Bắt đầu nhanh

Nếu đây là lần đầu tiên bạn chạy Hermes Agent, hãy tạo một thư mục dữ liệu trên máy chủ và khởi động vùng chứa một cách tương tác để chạy trình hướng dẫn thiết lập:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Thao tác này sẽ đưa bạn đến trình hướng dẫn thiết lập, trình hướng dẫn này sẽ nhắc bạn nhập khóa API và ghi chúng vào ~/.hermes/.env . Bạn chỉ cần làm điều này một lần. Bạn nên thiết lập một hệ thống trò chuyện để cổng hoạt động vào thời điểm này.

Chạy ở chế độ cổng

Sau khi được định cấu hình, hãy chạy vùng chứa ở chế độ nền dưới dạng một cổng liên tục (Telegram, Discord, Slack, WhatsApp, v.v.):

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Cổng 8642 mở máy chủ API tương thích OpenAI và endpoint kiểm tra sức khỏe của gateway. Tùy chọn nếu bạn chỉ dùng nền tảng chat (Telegram, Discord, v.v.), nhưng bắt buộc nếu bạn muốn bảng điều khiển hoặc công cụ bên ngoài kết nối đến gateway.

Mở bất kỳ cổng nào trên máy kết nối internet là rủi ro bảo mật. Bạn không nên làm điều này trừ khi hiểu rõ rủi ro.

Chạy bảng điều khiển

Bảng điều khiển web tích hợp có thể chạy cùng gateway dưới dạng container riêng.

Để chạy bảng điều khiển như container riêng, hướng nó đến endpoint kiểm tra sức khỏe của gateway để phát hiện trạng thái gateway giữa các container:

docker run -d \
  --name hermes-dashboard \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 9119:9119 \
  -e GATEWAY_HEALTH_URL=http://$HOST_IP:8642 \
  nousresearch/hermes-agent dashboard

Thay $HOST_IP bằng địa chỉ IP của máy chạy container gateway (ví dụ 192.168.1.100), hoặc dùng hostname mạng Docker nếu cả hai container dùng chung mạng (xem Ví dụ Compose bên dưới).

Biến môi trường	Mô tả	Mặc định
`GATEWAY_HEALTH_URL`	URL cơ sở của máy chủ API gateway, ví dụ `http://gateway:8642`	(không đặt — chỉ kiểm tra PID cục bộ)
`GATEWAY_HEALTH_TIMEOUT`	Thời gian chờ kiểm tra sức khỏe tính bằng giây	`3`

Không có GATEWAY_HEALTH_URL, bảng điều khiển quay về phát hiện tiến trình cục bộ — chỉ hoạt động khi gateway chạy trong cùng container hoặc trên cùng máy chủ.

Chạy tương tác (trò chuyện CLI)

Để mở phiên trò chuyện tương tác dựa trên thư mục dữ liệu đang chạy:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

Khối lượng liên tục

Tập /opt/data là nguồn sự thật duy nhất cho toàn bộ bang Hermes. Nó ánh xạ tới thư mục ~/.hermes/ của máy chủ của bạn và chứa:

Đường dẫn	Nội dung
`.env`	Khóa API và bí mật
`config.yaml`	Tất cả cấu hình Hermes
`SOUL.md`	Tính cách/danh tính của đại lý
`sessions/`	Lịch sử hội thoại
`memories/`	Lưu trữ bộ nhớ liên tục
`skills/`	Kỹ năng cài đặt
`cron/`	Định nghĩa công việc theo lịch trình
`hooks/`	Móc sự kiện
`logs/`	Nhật ký thời gian chạy
`skins/`	Giao diện CLI tùy chỉnh

cảnh báo

Không bao giờ chạy đồng thời hai container gateway Hermes trên cùng một thư mục dữ liệu — tệp phiên và kho lưu trữ bộ nhớ không được thiết kế để ghi đồng thời. Chạy container bảng điều khiển cùng gateway là an toàn vì bảng điều khiển chỉ đọc dữ liệu.

Chuyển tiếp biến môi trường

Khóa API được đọc từ /opt/data/.env bên trong vùng chứa. Bạn cũng có thể truyền trực tiếp các biến môi trường:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  nousresearch/hermes-agent

Cờ -e trực tiếp ghi đè các giá trị từ .env . Điều này hữu ích cho việc tích hợp CI/CD hoặc trình quản lý bí mật mà bạn không muốn có khóa trên đĩa.

Ví dụ về Docker Compose

Để triển khai liên tục với cả gateway và bảng điều khiển, docker-compose.yaml rất tiện lợi:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"
    volumes:
      - ~/.hermes:/opt/data
    networks:
      - hermes-net
    # Bỏ ghi chú để chuyển tiếp biến env cụ thể thay vì dùng file .env:
    # environment:
    #   - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    #   - OPENAI_API_KEY=${OPENAI_API_KEY}
    #   - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

  dashboard:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-dashboard
    restart: unless-stopped
    command: dashboard --host 0.0.0.0
    ports:
      - "9119:9119"
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - GATEWAY_HEALTH_URL=http://hermes:8642
    networks:
      - hermes-net
    depends_on:
      - hermes
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "0.5"

networks:
  hermes-net:
    driver: bridge

Bắt đầu với docker compose up -d và xem nhật ký bằng docker compose logs -f .

Giới hạn tài nguyên

Thùng chứa Hermes cần nguồn lực vừa phải. Mức tối thiểu được đề xuất:

Tài nguyên	Tối thiểu	Được đề xuất
Ký ức	1 GB	2–4GB
CPU	1 lõi	2 lõi
Đĩa (khối lượng dữ liệu)	500 MB	2+ GB (tăng dần theo phiên/kỹ năng)

Đặt giới hạn trong Docker:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  --memory=4g --cpus=2 \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Dockerfile làm gì

Hình ảnh chính thức dựa trên debian:13.4 và bao gồm:

Python 3 với tất cả các phần phụ thuộc của Hermes ( pip install -e ".[all]" )
Node.js + npm (để tự động hóa trình duyệt và cầu nối WhatsApp)
Nhà viết kịch với Chrome ( npx playwright install --with-deps chromium )
ripgrep và ffmpeg là tiện ích hệ thống
Cầu WhatsApp ( scripts/whatsapp-bridge/ )

Tập lệnh điểm vào ( docker/entrypoint.sh ) khởi động khối lượng dữ liệu trong lần chạy đầu tiên:

Tạo cấu trúc thư mục ( sessions/ , memories/ , skills/ , v.v.)
Bản sao .env.example → .env nếu không tồn tại .env
Sao chép mặc định config.yaml nếu thiếu
Sao chép mặc định SOUL.md nếu thiếu
Đồng bộ hóa các kỹ năng đi kèm bằng cách sử dụng cách tiếp cận dựa trên bảng kê khai (bảo toàn các chỉnh sửa của người dùng)
Sau đó chạy hermes với bất kỳ đối số nào bạn vượt qua

Nâng cấp

Kéo hình ảnh mới nhất và tạo lại vùng chứa. Thư mục dữ liệu của bạn không bị ảnh hưởng.

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Hoặc với Docker Compose:

docker compose pull
docker compose up -d

Tệp kỹ năng và thông tin xác thực

Khi sử dụng Docker làm môi trường thực thi (không phải các phương thức ở trên mà là khi tác nhân chạy các lệnh bên trong hộp cát Docker), Hermes sẽ tự động liên kết gắn kết thư mục kỹ năng ( ~/.hermes/skills/ ) và mọi tệp thông tin xác thực được kỹ năng khai báo vào vùng chứa dưới dạng ổ đĩa chỉ đọc. Điều này có nghĩa là các tập lệnh kỹ năng, mẫu và tài liệu tham khảo có sẵn bên trong hộp cát mà không cần cấu hình thủ công.

Quá trình đồng bộ hóa tương tự cũng xảy ra đối với các chương trình phụ trợ SSH và Modal - các tệp kỹ năng và thông tin xác thực được tải lên thông qua rsync hoặc API gắn kết Modal trước mỗi lệnh.

Khắc phục sự cố

Container thoát ngay lập tức

Kiểm tra nhật ký: docker logs hermes . Nguyên nhân phổ biến:

Tệp .env bị thiếu hoặc không hợp lệ — trước tiên hãy chạy tương tác để hoàn tất thiết lập
Xung đột cổng nếu chạy với các cổng bị lộ

Lỗi "Quyền bị từ chối"

Vùng chứa chạy dưới quyền root theo mặc định. Nếu máy chủ ~/.hermes/ của bạn được tạo bởi người dùng không phải root thì quyền sẽ hoạt động. Nếu bạn gặp lỗi, hãy đảm bảo thư mục dữ liệu có thể ghi được:

chmod -R 755 ~/.hermes

Công cụ trình duyệt không hoạt động

Nhà viết kịch cần có bộ nhớ chung. Thêm --shm-size=1g vào lệnh chạy Docker của bạn:

docker run -d \
  --name hermes \
  --shm-size=1g \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

Cổng không kết nối lại sau sự cố mạng

Cờ --restart unless-stopped xử lý hầu hết các lỗi nhất thời. Nếu cổng bị kẹt, hãy khởi động lại vùng chứa:

docker restart hermes

Kiểm tra tình trạng container

docker logs --tail 50 hermes          

# Recent logs
docker run -it --rm nousresearch/hermes-agent:latest version     

# Kiểm tra phiên bản
docker stats hermes                    

# Mức sử dụng tài nguyên