Tutorial 16: Deployment Docker

Selamat datang kembali, para penjelajah Hermes! Di tutorial sebelumnya, kita sudah nyaman menjalankan Hermes Agent langsung di mesin kita. Hari ini, kita naik level: kita akan menaruh Hermes di dalam kontainer Docker. Ini adalah pengubah permainan untuk menjaga lingkungan kamu tetap bersih, portabel, dan mudah di-upgrade.

Dua Cara Docker Bertemu Hermes

Sebelum kita menyelam lebih dalam, penting untuk dipahami bahwa Docker dan Hermes Agent dapat bekerja sama dalam dua cara yang berbeda:

Menjalankan Hermes di dalam Docker – Agen itu sendiri hidup di dalam kontainer. Ini yang akan kita fokuskan hari ini.
Docker sebagai backend terminal – Hermes berjalan di host kamu, tetapi setiap perintah yang dieksekusi terjadi di dalam sandbox Docker yang persisten. Ini bagus untuk keamanan dan isolasi, tapi itu topik untuk lain hari.

Hari ini, kita semua tentang opsi 1. Keindahan pendekatan ini adalah semua data kamu—konfigurasi, kunci API, sesi, skill, dan memori—tersimpan dalam satu direktori di host kamu, yang di-mount ke dalam kontainer di /opt/data. Kontainer itu sendiri stateless, jadi kamu bisa menarik versi baru dan melakukan upgrade tanpa kehilangan apa pun.

Memulai Cepat: Kontainer Pertama Kamu

Jika kamu benar-benar baru mengenal Hermes, jalur termudah adalah membuat direktori data dan menjalankan wizard pengaturan secara interaktif. Ini akan memandumu memasukkan kunci API dan menyimpannya ke ~/.hermes/.env.

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

Satu kata peringatan: hindari konsol VPS berbasis browser (seperti punya Hetzner Cloud) untuk perintah-perintah ini. Mereka sering merusak karakter khusus seperti :, @, dan =, yang bisa diam-diam merusak argumen docker run kamu. Selalu terhubung melalui SSH (ssh root@<host>) untuk entri yang aman dari copy-paste. Jika kamu harus menggunakan konsol browser, ketik perintah secara manual dan periksa ulang setiap karakter.

Setelah kamu masuk ke wizard, sangat disarankan untuk menyiapkan sistem chat (Telegram, Discord, dll.) sehingga gateway kamu punya tempat untuk mengirim pesan.

Menjalankan dalam Mode Gateway

Setelah dikonfigurasi, kamu akan ingin menjalankan Hermes sebagai gateway latar belakang yang persisten. Ini adalah cara ia terhubung ke platform chat kamu dan tetap hidup 24/7.

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

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

Ini fitur baru yang keren: di dalam image Docker resmi, gateway run sekarang otomatis diawasi oleh s6-overlay. Ini berarti jika proses gateway crash, ia akan dimulai ulang dalam hitungan detik tanpa kehilangan kontainer. Kamu akan melihat jejak di docker logs yang mengonfirmasi upgrade tersebut. Jika kamu ingin perilaku lama (di mana kontainer keluar saat gateway keluar), berikan --no-supervise atau set HERMES_GATEWAY_NO_SUPERVISE=1. Untuk produksi, default yang diawasi jelas lebih baik.

Mengekspos Server API

Secara default, server API dibatasi oleh API_SERVER_ENABLED=true. Untuk mengeksposnya melampaui 127.0.0.1 di dalam kontainer, kamu perlu mengatur beberapa variabel lingkungan:

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

API_SERVER_KEY harus minimal 8 karakter—buat satu dengan openssl rand -hex 32. Penting: membuka port apa pun di mesin yang menghadap internet adalah risiko keamanan. Jangan lakukan ini kecuali kamu sepenuhnya memahami implikasinya.

Menjalankan Dashboard

Ingin dashboard web untuk memantau gateway kamu? Set HERMES_DASHBOARD=1 dan ekspos port 9119:

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

Dashboard juga diawasi oleh s6, jadi ia restart otomatis jika crash. Outputnya masuk ke docker logs <container>.

Catatan tentang Pengaman Tool-Loop

Untuk gateway tanpa pengawasan, pertimbangkan untuk mengaktifkan penghentian keras untuk pengaman tool-loop. Defaultnya adalah false, yang baik untuk sesi interaktif di mana manusia bisa melihat peringatan. Tetapi di gateway tanpa pengawasan, agen yang terjebak dalam loop mungkin tidak pernah berhenti. Tambahkan ini ke config.yaml di profil kamu:

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

Penutup

Itulah cerita deployment Docker! Kamu sekarang punya kontainer stateless yang bisa di-upgrade dengan semua data kamu ter-mount dengan aman di host. Di tutorial berikutnya, kita akan menjelajahi dashboard lebih detail. Sampai jumpa, selamat berkontainer!