Docker + Hermes Agent: Dua Cara Bermain

Kalau kamu pernah bertanya-tanya bagaimana Docker cocok dengan gambaran Hermes Agent, kamu berada di tempat yang tepat. Sebenarnya ada dua cara berbeda di mana keduanya bisa bekerja sama, dan penting untuk mengetahui perbedaannya sebelum kamu mulai mengetik docker run.

Dua Mode Docker

Menjalankan Hermes DI DALAM Docker — agen itu sendiri berada di dalam container. Ini adalah fokus utama dari panduan ini.
Docker sebagai backend terminal — Hermes berjalan di mesin host kamu, tetapi setiap perintah yang dieksekusi terjadi di dalam satu sandbox Docker yang persisten. Sandbox tersebut bertahan melintasi panggilan tool, /new, dan bahkan subagen selama proses Hermes masih hidup.

Artikel ini membahas opsi 1. Hal penting yang perlu kamu tahu: semua data kamu (konfigurasi, kunci API, sesi, skill, memori) tersimpan dalam satu direktori di host kamu, di-mount di /opt/data di dalam container. Image-nya sendiri bersifat stateless, jadi kamu bisa menarik versi baru kapan saja tanpa kehilangan pengaturan kamu.

Memulai dengan Cepat: Pengaturan Pertama Kali

Kalau ini pertama kalinya kamu melakukannya, buat direktori data dan jalankan container secara interaktif untuk menjalankan wizard pengaturan:

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

Ini akan membawamu ke wizard, yang akan meminta kunci API kamu dan menuliskannya ke ~/.hermes/.env. Kamu hanya perlu melakukan ini sekali saja. Sambil melakukannya, ini waktu yang tepat untuk mengatur sistem chat (Telegram, Discord, dll.) sehingga gateway kamu punya tempat untuk berbicara.

⚠️ Perhatian: Hindari konsol VPS berbasis browser untuk perintah instalasi ini. Beberapa penyedia (seperti Hetzner) merusak karakter khusus — : bisa berubah menjadi ;, @ dirender dengan salah, dan kunci API yang ditempel bisa rusak secara diam-diam. Selalu gunakan SSH untuk memasukkan perintah yang aman dari copy-paste. Jika kamu harus menggunakan konsol browser, ketik perintah secara manual dan periksa ulang setiap :, @, =, dan /.

Tips pro: Di dalam container, jalankan hermes setup --portal sekali — refresh token akan tersimpan di volume ~/.hermes yang ter-mount.

Menjalankan dalam Mode Gateway

Setelah dikonfigurasi, jalankan container di latar belakang sebagai gateway yang persisten:

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

Port 8642 mengekspos server API kompatibel OpenAI dari gateway dan endpoint kesehatan. Ini opsional jika kamu hanya menggunakan platform chat, tetapi wajib jika kamu ingin dashboard atau alat eksternal menjangkau gateway.

Yang Baru: Gateway yang Diawasi

Ini perubahan besar: di dalam image Docker resmi, gateway run sekarang secara otomatis diawasi oleh s6-overlay. Jika gateway crash, ia akan restart dalam hitungan detik tanpa kehilangan container. Dashboard (jika diaktifkan) juga diawasi bersamaan dengannya.

Kamu akan melihat jejak satu baris di docker logs yang mengonfirmasi peningkatan ini. Untuk keluar dan mendapatkan perilaku lama (container keluar = gateway keluar), berikan --no-supervise atau atur HERMES_GATEWAY_NO_SUPERVISE=1. Ini berguna untuk uji smoke CI; untuk produksi, default yang diawasi jelas lebih baik.

Penghentian Paksa Loop Tool

Satu pengaturan penting untuk gateway tanpa pengawasan: tool_loop_guardrails.hard_stop_enabled default-nya false. Itu baik-baik saja untuk sesi interaktif di mana manusia bisa melihat peringatan. Tetapi dalam deployment tanpa pengawasan, peringatan saja mungkin tidak menghentikan agen yang terjebak dalam loop. Jika kamu ingin perilaku pemutus sirkuit, aktifkan di config.yaml profil kamu:

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

Mengekspos Server API

Server API dibatasi oleh API_SERVER_ENABLED=true. Untuk mengeksposnya melampaui 127.0.0.1 di dalam container, atur juga API_SERVER_HOST=0.0.0.0 dan API_SERVER_KEY (minimal 8 karakter — buat dengan 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

Catatan keamanan: Membuka port apa pun di mesin yang menghadap internet adalah risiko. Jangan lakukan ini kecuali kamu sepenuhnya memahami konsekuensinya.

Menjalankan Dashboard

Dashboard web bawaan berjalan sebagai layanan s6-rc yang diawasi bersama gateway di container yang sama. Cukup atur 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

Jika dashboard crash, s6-supervise akan me-restart-nya secara otomatis setelah jeda singkat. Output-nya masuk ke docker logs <container>.

Ke Mana Log Pergi

Untuk peta routing lengkap (gateway per-profil, dashboard, boot reconciler, dan docker logs seluruh container), periksa bagian khusus di dokumentasi. Versi singkatnya: semuanya akhirnya masuk ke docker logs, tetapi dengan prefiks yang jelas sehingga kamu bisa membedakan apa itu apa.

Penutup

Docker memberi kamu cara yang bersih dan mudah di-upgrade untuk menjalankan Hermes Agent. Container-nya stateless, data kamu tersimpan aman di host, dan pengawasan s6 yang baru berarti gateway kamu tetap hidup bahkan jika crash. Baik kamu menjalankan pengaturan sederhana atau kombinasi dashboard + server API lengkap, perintah-perintah di atas membawamu ke sana dalam hitungan menit.