Docker + Hermes Agent: Hai Cách Chơi

Nếu bạn từng thắc mắc Docker kết hợp với Hermes Agent như thế nào, thì bạn đã đến đúng nơi rồi. Thực ra có hai cách hoàn toàn khác nhau để hai thứ này hoạt động cùng nhau, và bạn nên biết sự khác biệt trước khi bắt đầu gõ docker run.

Hai Chế Độ Docker

Chạy Hermes TRONG Docker — bản thân agent sống bên trong container. Đây là trọng tâm chính của bài hướng dẫn này.
Docker làm backend terminal — Hermes chạy trên máy chủ của bạn, nhưng mọi lệnh nó thực thi đều diễn ra bên trong một sandbox Docker duy nhất và bền vững. Sandbox đó tồn tại xuyên suốt các lần gọi công cụ, /new, và thậm chí cả subagents — miễn là tiến trình Hermes còn sống.

Bài viết này đề cập đến lựa chọn 1. Điều quan trọng cần biết: tất cả dữ liệu của bạn (cấu hình, API keys, phiên làm việc, kỹ năng, bộ nhớ) nằm trong một thư mục duy nhất trên máy chủ, được mount vào /opt/data bên trong container. Bản thân image không lưu trạng thái, vì vậy bạn có thể kéo phiên bản mới bất cứ lúc nào mà không mất thiết lập của mình.

Bắt Đầu Nhanh: Thiết Lập Lần Đầu

Nếu đây là lần đầu tiên bạn làm quen, hãy tạo một thư mục dữ liệu và khởi động container ở 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

Lệnh này sẽ đưa bạn vào trình hướng dẫn, nơi nó hỏi API keys của bạn và ghi chúng vào ~/.hermes/.env. Bạn chỉ cần làm điều này một lần. Nhân tiện, đây cũng là thời điểm tuyệt vời để thiết lập một hệ thống chat (Telegram, Discord, v.v.) để gateway của bạn có nơi trò chuyện.

⚠️ Một lời cảnh báo: Tránh sử dụng bảng điều khiển VPS dựa trên trình duyệt cho các lệnh cài đặt này. Một số nhà cung cấp (như Hetzner) làm hỏng các ký tự đặc biệt — : có thể đến dưới dạng ;, @ bị hiển thị sai, và API keys dán vào có thể bị hỏng một cách âm thầm. Luôn kết nối qua SSH để nhập lệnh an toàn khi copy-paste. Nếu buộc phải dùng bảng điều khiển trình duyệt, hãy gõ lệnh thủ công và kiểm tra kỹ từng :, @, =, và /.

Mẹo chuyên nghiệp: Bên trong container, chạy hermes setup --portal một lần — refresh token sẽ được lưu trong volume ~/.hermes đã mount của bạn.

Chạy Ở Chế Độ Gateway

Sau khi cấu hình xong, chạy container ở chế độ nền như một gateway bền vững:

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

Cổng 8642 mở API server tương thích OpenAI và endpoint kiểm tra sức khỏe của gateway. Nó là tùy chọn nếu bạn chỉ dùng các nền tảng chat, nhưng bắt buộc nếu bạn muốn dashboard hoặc các công cụ bên ngoài truy cập gateway.

Điểm Mới: Gateway Được Giám Sát

Đây là một thay đổi lớn: bên trong image Docker chính thức, gateway run giờ đây tự động được giám sát bởi s6-overlay. Nếu gateway bị sập, nó sẽ khởi động lại trong vài giây mà không mất container. Dashboard (khi được bật) cũng được giám sát cùng lúc.

Bạn sẽ thấy một dòng thông báo ngắn trong docker logs xác nhận việc nâng cấp. Để từ chối và lấy lại hành vi cũ (container thoát = gateway thoát), truyền --no-supervise hoặc đặt HERMES_GATEWAY_NO_SUPERVISE=1. Điều này hữu ích cho các bài kiểm tra smoke trong CI; còn với môi trường production, chế độ giám sát mặc định tốt hơn hẳn.

Dừng Cứng Vòng Lặp Công Cụ

Một thiết lập quan trọng cho gateway chạy không người trông coi: tool_loop_guardrails.hard_stop_enabled mặc định là false. Điều đó ổn cho các phiên tương tác khi con người có thể thấy cảnh báo. Nhưng trong các triển khai không người trông coi, chỉ cảnh báo thôi có thể không đủ để ngăn một agent bị kẹt trong vòng lặp. Nếu bạn muốn hành vi ngắt mạch, hãy bật nó trong config.yaml của profile:

tool_loop_guardrails:
  hard_stop_enabled: true
  hard_stop_after:
    exact_failure: 5
    idempotent_no_progress: 5

Mở API Server

API server được kiểm soát bởi API_SERVER_ENABLED=true. Để mở nó ra ngoài 127.0.0.1 bên trong container, cũng cần đặt API_SERVER_HOST=0.0.0.0 và một API_SERVER_KEY (tối thiểu 8 ký tự — tạo một cái bằng openssl rand -hex 32):

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -e API_SERVER_ENABLED=true \
  -e API_SERVER_HOST=0.0.0.0 \
  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
  -e API_SERVER_CORS_ORIGINS='*' \
  nousresearch/hermes-agent gateway run

Lưu ý bảo mật: Mở bất kỳ cổng nào trên máy kết nối internet đều là rủi ro. Đừng làm điều đó trừ khi bạn hiểu rõ hoàn toàn hậu quả.

Chạy Dashboard

Dashboard web tích hợp chạy như một dịch vụ s6-rc được giám sát cùng với gateway trong cùng một container. Chỉ cần đặt HERMES_DASHBOARD=1:

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

Nếu dashboard bị sập, s6-supervise sẽ tự động khởi động lại nó sau một khoảng thời gian chờ ngắn. Đầu ra của nó sẽ được ghi vào docker logs <container>.

Logs Đi Về Đâu

Để xem bản đồ định tuyến đầy đủ (gateway theo từng profile, dashboard, bộ điều phối khởi động, và docker logs trên toàn container), hãy xem phần chuyên dụng trong tài liệu. Tóm lại: mọi thứ cuối cùng đều nằm trong docker logs, nhưng với các tiền tố rõ ràng để bạn phân biệt được cái gì là gì.

Tổng Kết

Docker mang đến cho bạn một cách sạch sẽ và dễ nâng cấp để chạy Hermes Agent. Container không lưu trạng thái, dữ liệu của bạn nằm an toàn trên máy chủ, và cơ chế giám sát s6 mới đảm bảo gateway của bạn luôn hoạt động ngay cả khi nó bị sập. Dù bạn chạy một thiết lập đơn giản hay kết hợp đầy đủ dashboard + API server, các lệnh trên sẽ giúp bạn hoàn thành trong vài phút.