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 \
  nousresearch/hermes-agent gateway run

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 vùng chứa 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ế để truy cập đồng thời.

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ề soạn thảo Docker

Để triển khai cổng liên tục, docker-compose.yaml rất tiện lợi:

version: "3.8"
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    volumes:
      - ~/.hermes:/opt/data
    

# Uncomment to forward specific env vars instead of using .env file:
    

# 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"

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

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 exec hermes hermes version     

# Verify version
docker stats hermes                    

# Resource usage