📄 user-guide/sessions.md

sidebar_position: 7 title: "Sessions" description: "Session persistence, resume, search, management, and per-platform session tracking"

Sessions

Hermes Agent จะบันทึกการสนทนาทุกครั้งเป็นเซสชัน (session) โดยอัตโนมัติ เซสชันช่วยให้สามารถดำเนินการต่อการสนทนา (conversation resume), การค้นหาข้ามเซสชัน (cross-session search), และการจัดการประวัติการสนทนาทั้งหมดได้

How Sessions Work

การสนทนาทุกครั้ง ไม่ว่าจะมาจาก CLI, Telegram, Discord, Slack, WhatsApp, Signal, Matrix, หรือแพลตฟอร์มการส่งข้อความอื่น ๆ จะถูกจัดเก็บเป็นเซสชันพร้อมประวัติข้อความทั้งหมด เซสชันเหล่านี้จะถูกติดตามในระบบเสริมกันสองส่วน:

1. SQLite database (~/.hermes/state.db) - metadata ของเซสชันที่มีโครงสร้าง พร้อมการค้นหาแบบ full-text search ด้วย FTS5
2. JSONL transcripts (~/.hermes/sessions/) - ข้อมูล transcript การสนทนาดิบ รวมถึง tool calls (gateway)

SQLite database จะจัดเก็บข้อมูลดังนี้:

• Session ID, source platform, user ID
• Session title (ชื่อที่เฉพาะเจาะจงและอ่านได้ด้วยมนุษย์)
• ชื่อและ configuration ของ Model
• Snapshot ของ system prompt
• ประวัติข้อความทั้งหมด (role, content, tool calls, tool results)
• Token counts (input/output)
• Timestamps (started_at, ended_at)
• Parent session ID (สำหรับการแยกเซสชันที่เกิดจากการบีบอัดข้อมูล)

Session Sources

แต่ละเซสชันจะถูกติดป้ายกำกับด้วย source platform ของมัน:

CLI Session Resume

สามารถดำเนินการต่อการสนทนาครั้งก่อนจาก CLI ได้โดยใช้ --continue หรือ --resume:

Continue Last Session

# Resume the most recent CLI session
hermes --continue
hermes -c

# Or with the chat subcommand
hermes chat --continue
hermes chat -c

คำสั่งนี้จะค้นหา cli session ล่าสุดจาก SQLite database และโหลดประวัติการสนทนาทั้งหมด

Resume by Name

หากคุณได้ตั้งชื่อให้กับเซสชัน (ดู Session Naming ด้านล่าง) คุณสามารถดำเนินการต่อได้โดยใช้ชื่อ:

# Resume a named session
hermes -c "my project"

# If there are lineage variants (my project, my project #2, my project #3),
# this automatically resumes the most recent one
hermes -c "my project"   # → resumes "my project #3"

Resume Specific Session

# Resume a specific session by ID
hermes --resume 20250305_091523_a1b2c3d4
hermes -r 20250305_091523_a1b2c3d4

# Resume by title
hermes --resume "refactoring auth"

# Or with the chat subcommand
hermes chat --resume 20250305_091523_a1b2c3d4

Session ID จะแสดงเมื่อคุณออกจาก CLI session และสามารถค้นหาได้ด้วย hermes sessions list

Conversation Recap on Resume

เมื่อคุณดำเนินการต่อเซสชัน (resume) Hermes จะแสดงสรุปสั้น ๆ ของการสนทนาครั้งก่อนในแผงสไตล์ (styled panel) ก่อนหน้า prompt สำหรับป้อนข้อมูล:

ส่วนสรุปนี้:

• แสดง ข้อความของผู้ใช้ (● สีทอง) และ การตอบกลับของผู้ช่วย (◆ สีเขียว)
• ตัดทอน ข้อความยาว ๆ (300 ตัวอักษรสำหรับผู้ใช้, 200 ตัวอักษร / 3 บรรทัดสำหรับผู้ช่วย)
• ยุบ tool calls ให้เป็นจำนวนพร้อมชื่อ tool (เช่น [3 tool calls: terminal, web_search])
• ซ่อน system messages, tool results, และ internal reasoning
• จำกัด ที่ 10 การโต้ตอบล่าสุด พร้อมตัวบ่งชี้ "... N earlier messages ..."
• ใช้ สไตล์ที่จางลง เพื่อแยกความแตกต่างจากการสนทนาที่กำลังใช้งาน

หากต้องการปิดการแสดงสรุปและคงพฤติกรรมแบบ minimal one-liner ให้ตั้งค่าใน ~/.hermes/config.yaml:

display:
  resume_display: minimal   # default: full

:::tip Session IDs มีรูปแบบเป็น YYYYMMDD_HHMMSS_<8-char-hex> เช่น 20250305_091523_a1b2c3d4 คุณสามารถดำเนินการต่อได้ทั้งด้วย ID หรือด้วยชื่อ - ทั้งสองแบบใช้ได้กับ -c และ -r :::

Session Naming

กำหนดชื่อที่อ่านได้ด้วยมนุษย์ให้กับเซสชัน เพื่อให้คุณสามารถค้นหาและดำเนินการต่อได้ง่าย

Auto-Generated Titles

Hermes จะสร้างชื่อที่สื่อความหมายสั้น ๆ (3-7 คำ) โดยอัตโนมัติสำหรับแต่ละเซสชันหลังจากมีการโต้ตอบครั้งแรก การทำงานนี้จะเกิดขึ้นใน background thread โดยใช้ auxiliary model ที่รวดเร็ว จึงไม่มีความล่าช้า คุณจะเห็นชื่อที่สร้างโดยอัตโนมัติเมื่อเรียกดูเซสชันด้วย hermes sessions list หรือ hermes sessions browse

การตั้งชื่ออัตโนมัติจะทำงานเพียงครั้งเดียวต่อเซสชัน และจะถูกข้ามหากคุณได้ตั้งชื่อด้วยตนเองแล้ว

Setting a Title Manually

ใช้คำสั่ง slash /title ภายใน chat session ใด ๆ (CLI หรือ gateway):

/title my research project

ชื่อจะถูกนำไปใช้ทันที หากเซสชันยังไม่ได้ถูกสร้างใน database (เช่น คุณรัน /title ก่อนส่งข้อความแรก) มันจะถูกจัดคิวและนำไปใช้เมื่อเซสชันเริ่มต้น

คุณยังสามารถเปลี่ยนชื่อเซสชันที่มีอยู่ได้จาก command line:

hermes sessions rename 20250305_091523_a1b2c3d4 "refactoring auth module"

Title Rules

• Unique - ไม่มีเซสชันใดสองเซสชันที่สามารถมีชื่อเดียวกันได้
• Max 100 characters - เพื่อให้ output ของรายการดูสะอาดตา
• Sanitized - control characters, zero-width chars, และ RTL overrides จะถูกลบออกโดยอัตโนมัติ
• Normal Unicode is fine - emoji, CJK, accented characters ใช้งานได้ทั้งหมด

Auto-Lineage on Compression

เมื่อ context ของเซสชันถูกบีบอัด (ด้วยตนเองผ่าน /compress หรือโดยอัตโนมัติ) Hermes จะสร้างเซสชัน continuation ใหม่ หากเซสชันเดิมมีชื่อ เซสชันใหม่จะได้รับชื่อที่มีลำดับตัวเลขโดยอัตโนมัติ:

"my project" → "my project #2" → "my project #3"

เมื่อคุณดำเนินการต่อด้วยชื่อ (hermes -c "my project") ระบบจะเลือกเซสชันล่าสุดใน lineage ให้โดยอัตโนมัติ

/title in Messaging Platforms

คำสั่ง /title ใช้งานได้ในทุกแพลตฟอร์ม gateway (Telegram, Discord, Slack, WhatsApp):

• /title My Research - ตั้งชื่อเซสชัน
• /title - แสดงชื่อปัจจุบัน

Session Management Commands

Hermes มีชุดคำสั่งจัดการเซสชันที่สมบูรณ์ผ่าน hermes sessions:

List Sessions

# List recent sessions (default: last 20)
hermes sessions list

# Filter by platform
hermes sessions list --source telegram

# Show more sessions
hermes sessions list --limit 50

เมื่อเซสชันมีชื่อ จะแสดงชื่อ, ตัวอย่าง, และเวลาที่ใช้งานล่าสุด:

Title                  Preview                                  Last Active   ID
────────────────────────────────────────────────────────────────────────────────────────────────
refactoring auth       Help me refactor the auth module please   2h ago        20250305_091523_a
my project #3          Can you check the test failures?          yesterday     20250304_143022_e
—                      What's the weather in Las Vegas?          3d ago        20250303_101500_f

เมื่อไม่มีเซสชันใดมีชื่อ จะใช้รูปแบบที่ง่ายกว่า:

Preview                                            Last Active   Src    ID
──────────────────────────────────────────────────────────────────────────────────────
Help me refactor the auth module please             2h ago        cli    20250305_091523_a
What's the weather in Las Vegas?                    3d ago        tele   20250303_101500_f

Export Sessions

# Export all sessions to a JSONL file
hermes sessions export backup.jsonl

# Export sessions from a specific platform
hermes sessions export telegram-history.jsonl --source telegram

# Export a single session
hermes sessions export session.jsonl --session-id 20250305_091523_a1b2c3d4

ไฟล์ที่ export จะมี JSON object หนึ่ง object ต่อบรรทัด พร้อม metadata เซสชันทั้งหมดและข้อความทั้งหมด

Delete a Session

# Delete a specific session (with confirmation)
hermes sessions delete 20250305_091523_a1b2c3d4

# Delete without confirmation
hermes sessions delete 20250305_091523_a1b2c3d4 --yes

Rename a Session

# Set or change a session's title
hermes sessions rename 20250305_091523_a1b2c3d4 "debugging auth flow"

# Multi-word titles don't need quotes in the CLI
hermes sessions rename 20250305_091523_a1b2c3d4 debugging auth flow

หากชื่อถูกใช้งานโดยเซสชันอื่นอยู่แล้ว จะแสดงข้อผิดพลาด

Prune Old Sessions

# Delete ended sessions older than 90 days (default)
hermes sessions prune

# Custom age threshold
hermes sessions prune --older-than 30

# Only prune sessions from a specific platform
hermes sessions prune --source telegram --older-than 60

# Skip confirmation
hermes sessions prune --older-than 30 --yes

:::info Pruning จะลบเฉพาะเซสชันที่ สิ้นสุดแล้ว (เซสชันที่ถูกยุติอย่างชัดเจนหรือรีเซ็ตอัตโนมัติ) เซสชันที่ใช้งานอยู่จะไม่ถูกลบเด็ดขาด :::

Session Statistics

hermes sessions stats

Output:

Total sessions: 142
Total messages: 3847
  cli: 89 sessions
  telegram: 38 sessions
  discord: 15 sessions
Database size: 12.4 MB

สำหรับการวิเคราะห์เชิงลึกยิ่งขึ้น - การใช้ token, การประมาณค่าใช้จ่าย, การแจกแจง tool, และรูปแบบกิจกรรม - ให้ใช้ hermes insights

Session Search Tool

Agent มี tool session_search ในตัวที่ทำการค้นหา full-text search ทั่วทุกการสนทนาที่ผ่านมาโดยใช้ engine FTS5 ของ SQLite

How It Works

1. FTS5 ค้นหาข้อความที่ตรงกันและจัดอันดับตามความเกี่ยวข้อง
2. จัดกลุ่มผลลัพธ์ตามเซสชัน และเลือก N เซสชันที่ไม่ซ้ำกันที่ดีที่สุด (ค่าเริ่มต้น 3)
3. โหลดการสนทนาของแต่ละเซสชัน, ตัดทอนให้เหลือประมาณ 100K ตัวอักษร โดยเน้นบริเวณที่ตรงกับผลลัพธ์
4. ส่งไปยัง fast summarization model เพื่อสรุปที่เน้นเฉพาะจุด
5. ส่งคืนสรุปต่อเซสชันพร้อม metadata และบริบทโดยรอบ

FTS5 Query Syntax

การค้นหาสนับสนุน syntax ของ FTS5 มาตรฐาน:

• Simple keywords: docker deployment
• Phrases: "exact phrase"
• Boolean: docker OR kubernetes, python NOT java
• Prefix: deploy*

When It's Used

Agent จะถูกสั่งให้ใช้ session search โดยอัตโนมัติ:

"When the user references something from a past conversation or you suspect relevant prior context exists, use session_search to recall it before asking them to repeat themselves."

Per-Platform Session Tracking

Gateway Sessions

ในแพลตฟอร์มการส่งข้อความ เซสชันจะถูกระบุด้วย session key ที่กำหนดโดย deterministic key ซึ่งสร้างขึ้นจาก source ของข้อความ:

เมื่อ Hermes ไม่สามารถรับ participant identifier สำหรับแชทที่ใช้ร่วมกันได้ มันจะย้อนกลับไปใช้เซสชันที่ใช้ร่วมกันเพียงเซสชันเดียวสำหรับห้องนั้น

Shared vs Isolated Group Sessions

โดยค่าเริ่มต้น Hermes ใช้ group_sessions_per_user: true ใน config.yaml ซึ่งหมายความว่า:

• Alice และ Bob สามารถคุยกับ Hermes ในช่อง Discord เดียวกันได้โดยที่ประวัติ transcript ไม่ถูกแชร์กัน
• งานที่ใช้ tool หนัก ๆ ของผู้ใช้คนหนึ่งจะไม่ทำให้ context window ของผู้ใช้คนอื่นปนเปื้อน
• การจัดการ interrupt ยังคงเป็นแบบต่อผู้ใช้แต่ละคน เนื่องจาก key ของ running-agent ตรงกับ isolated session key

หากคุณต้องการ "room brain" ที่ใช้ร่วมกันแทน ให้ตั้งค่า:

group_sessions_per_user: false

สิ่งนี้จะย้อนกลับกลุ่ม/ช่องให้เป็นเซสชันที่ใช้ร่วมกันเพียงเซสชันเดียวต่อห้อง ซึ่งช่วยรักษาบริบทการสนทนาที่ใช้ร่วมกัน แต่ก็แชร์ token costs, interrupt state, และ context growth ด้วย

Session Reset Policies

Gateway sessions จะถูกรีเซ็ตโดยอัตโนมัติตามนโยบายที่กำหนดค่าได้:

• idle - รีเซ็ตหลังจากไม่มีกิจกรรมเป็นเวลา N นาที
• daily - รีเซ็ตในเวลาที่กำหนดในแต่ละวัน
• both - รีเซ็ตเมื่อถึงเงื่อนไขใดเงื่อนไขหนึ่งก่อน (idle หรือ daily)
• none - ไม่เคยรีเซ็ตอัตโนมัติ

ก่อนที่เซสชันจะถูกรีเซ็ตอัตโนมัติ Agent จะได้รับโอกาสในการบันทึกความทรงจำหรือทักษะที่สำคัญใด ๆ จากการสนทนานั้น

เซสชันที่มี active background processes จะไม่ถูกรีเซ็ตอัตโนมัติ ไม่ว่านโยบายจะเป็นอย่างไร

Storage Locations

SQLite database ใช้ WAL mode สำหรับ concurrent readers และ single writer ซึ่งเหมาะกับสถาปัตยกรรม multi-platform ของ gateway เป็นอย่างดี

Database Schema

ตารางหลักใน state.db:

• sessions - metadata เซสชัน (id, source, user_id, model, title, timestamps, token counts). Titles มี unique index (อนุญาตให้มี NULL title, เฉพาะ non-NULL เท่านั้นที่ต้อง unique).
• messages - ประวัติข้อความทั้งหมด (role, content, tool_calls, tool_name, token_count)
• messages_fts - ตารางเสมือน FTS5 สำหรับ full-text search ทั่ว content ของข้อความ

Session Expiry and Cleanup

Automatic Cleanup

• Gateway sessions จะรีเซ็ตอัตโนมัติตามนโยบายที่กำหนดค่า
• ก่อนรีเซ็ต Agent จะบันทึก memories และ skills จากเซสชันที่กำลังจะหมดอายุ
• เซสชันที่สิ้นสุดแล้วจะยังคงอยู่ใน database จนกว่าจะถูก prune

Manual Cleanup

# Prune sessions older than 90 days
hermes sessions prune

# Delete a specific session
hermes sessions delete <session_id>

# Export before pruning (backup)
hermes sessions export backup.jsonl
hermes sessions prune --older-than 30 --yes

:::tip Database จะขยายตัวช้า ๆ (โดยทั่วไป: 10-15 MB สำหรับหลายร้อยเซสชัน) การ prune มีประโยชน์หลักในการลบการสนทนาเก่า ๆ ที่คุณไม่ต้องการสำหรับการเรียกคืนข้อมูล (search recall) :::

📄 user-guide/security.md

sidebar_position: 8 title: "Security" description: "Security model, dangerous command approval, user authorization, container isolation, and production deployment best practices"

Security

Hermes Agent ถูกออกแบบด้วยโมเดลความปลอดภัยแบบลึกหลายชั้น (defense-in-depth security model) หน้านี้ครอบคลุมขอบเขตความปลอดภัยทุกส่วน ตั้งแต่การอนุมัติคำสั่ง การแยกส่วนคอนเทนเนอร์ ไปจนถึงการอนุญาตสิทธิ์ผู้ใช้บนแพลตฟอร์มการส่งข้อความ

Overview

โมเดลความปลอดภัยประกอบด้วยเจ็ดชั้น:

1. User authorization - ใครสามารถพูดคุยกับ agent ได้ (allowlists, DM pairing)
2. Dangerous command approval - การตรวจสอบคำสั่งอันตรายโดยมนุษย์ (human-in-the-loop) สำหรับการดำเนินการที่ทำลายล้าง
3. Container isolation - การแยกส่วนด้วย Docker/Singularity/Modal sandboxing พร้อมการตั้งค่าที่แข็งแกร่ง (hardened settings)
4. MCP credential filtering - การแยกส่วนตัวแปรสภาพแวดล้อม (environment variable isolation) สำหรับ MCP subprocesses
5. Context file scanning - การตรวจจับ prompt injection ในไฟล์โปรเจกต์
6. Cross-session isolation - เซสชันไม่สามารถเข้าถึงข้อมูลหรือสถานะของกันและกันได้; เส้นทางจัดเก็บ cron job ถูกเสริมความแข็งแกร่งเพื่อป้องกัน path traversal attacks
7. Input sanitization - พารามิเตอร์ working directory ใน backends ของเครื่องมือ terminal จะถูกตรวจสอบกับ allowlist เพื่อป้องกัน shell injection

Dangerous Command Approval

ก่อนที่จะดำเนินการคำสั่งใดๆ Hermes จะตรวจสอบคำสั่งนั้นกับรายการรูปแบบ (patterns) อันตรายที่รวบรวมมา หากพบการจับคู่ (match) ผู้ใช้จะต้องอนุมัติอย่างชัดเจน

Approval Modes

ระบบการอนุมัติรองรับสามโหมด ซึ่งกำหนดค่าผ่าน approvals.mode ใน ~/.hermes/config.yaml:

approvals:
  mode: manual    # manual | smart | off
  timeout: 60     # seconds to wait for user response (default: 60)

:::warning การตั้งค่า approvals.mode: off จะปิดการแจ้งเตือนความปลอดภัยทั้งหมด ใช้เฉพาะในสภาพแวดล้อมที่เชื่อถือได้เท่านั้น (CI/CD, containers, ฯลฯ) :::

YOLO Mode

YOLO mode จะข้ามการแจ้งเตือนการอนุมัติคำสั่งอันตราย ทั้งหมด สำหรับเซสชันปัจจุบัน สามารถเปิดใช้งานได้สามวิธี:

1. CLI flag: เริ่มเซสชันด้วย hermes --yolo หรือ hermes chat --yolo
2. Slash command: พิมพ์ /yolo ระหว่างเซสชันเพื่อสลับเปิด/ปิด
3. Environment variable: ตั้งค่า HERMES_YOLO_MODE=1

คำสั่ง /yolo เป็นการ สลับ (toggle) - การใช้งานแต่ละครั้งจะสลับโหมดเปิดหรือปิด:

> /yolo
  ⚡ YOLO mode ON — all commands auto-approved. Use with caution.

> /yolo
  ⚠ YOLO mode OFF — dangerous commands will require approval.

YOLO mode สามารถใช้ได้ทั้งในเซสชัน CLI และ gateway ภายในระบบจะตั้งค่าตัวแปรสภาพแวดล้อม HERMES_YOLO_MODE ซึ่งจะถูกตรวจสอบก่อนการดำเนินการคำสั่งทุกครั้ง

:::danger YOLO mode ปิดการตรวจสอบความปลอดภัยของคำสั่งอันตราย ทั้งหมด สำหรับเซสชัน ใช้เฉพาะเมื่อคุณเชื่อมั่นในคำสั่งที่กำลังถูกสร้างขึ้นอย่างเต็มที่ (เช่น สคริปต์ระบบอัตโนมัติที่ผ่านการทดสอบมาอย่างดีในสภาพแวดล้อมที่ใช้แล้วทิ้ง) :::

Approval Timeout

เมื่อมีการแจ้งเตือนคำสั่งอันตราย ผู้ใช้จะมีเวลาที่กำหนดค่าไว้ในการตอบกลับ หากไม่มีการตอบกลับภายในเวลาที่กำหนด คำสั่งนั้นจะถูก ปฏิเสธ โดยค่าเริ่มต้น (fail-closed)

กำหนดค่า timeout ใน ~/.hermes/config.yaml:

approvals:
  timeout: 60  # seconds (default: 60)

What Triggers Approval

รูปแบบต่อไปนี้จะกระตุ้นการแจ้งเตือนการอนุมัติ (กำหนดไว้ใน tools/approval.py):

:::info Container bypass: เมื่อรันใน docker, singularity, modal, หรือ daytona backends การตรวจสอบคำสั่งอันตรายจะ ถูกข้าม เนื่องจากคอนเทนเนอร์เองคือขอบเขตความปลอดภัย คำสั่งทำลายล้างภายในคอนเทนเนอร์จึงไม่สามารถทำอันตรายต่อ host ได้ :::

Approval Flow (CLI)

ใน CLI แบบโต้ตอบ (interactive CLI) คำสั่งอันตรายจะแสดง prompt การอนุมัติแบบ inline:

  ⚠️  DANGEROUS COMMAND: recursive delete
      rm -rf /tmp/old-project

      [o]nce  |  [s]ession  |  [a]lways  |  [d]eny

      Choice [o/s/a/D]:

สี่ตัวเลือก:

• once - อนุญาตให้ดำเนินการเพียงครั้งเดียวนี้
• session - อนุญาตรูปแบบนี้ตลอดเซสชัน
• always - เพิ่มเข้าใน allowlist ถาวร (บันทึกใน config.yaml)
• deny (default) - บล็อกคำสั่ง

Approval Flow (Gateway/Messaging)

บนแพลตฟอร์มการส่งข้อความ agent จะส่งรายละเอียดคำสั่งอันตรายไปยังแชทและรอให้ผู้ใช้ตอบกลับ:

• ตอบ yes, y, approve, ok, หรือ go เพื่ออนุมัติ
• ตอบ no, n, deny, หรือ cancel เพื่อปฏิเสธ

ตัวแปรสภาพแวดล้อม HERMES_EXEC_ASK=1 จะถูกตั้งค่าโดยอัตโนมัติเมื่อรัน gateway

Permanent Allowlist

คำสั่งที่อนุมัติด้วย "always" จะถูกบันทึกใน ~/.hermes/config.yaml:

# Permanently allowed dangerous command patterns
command_allowlist:
  - rm
  - systemctl

รูปแบบเหล่านี้จะถูกโหลดเมื่อเริ่มต้นระบบและได้รับการอนุมัติโดยอัตโนมัติในทุกเซสชันในอนาคต

:::tip ใช้ hermes config edit เพื่อตรวจสอบหรือลบรูปแบบออกจาก permanent allowlist ของคุณ :::

User Authorization (Gateway)

เมื่อรัน messaging gateway, Hermes จะควบคุมว่าใครสามารถโต้ตอบกับบอทได้ผ่านระบบการอนุญาตสิทธิ์แบบหลายชั้น

Authorization Check Order

เมธอด _is_user_authorized() จะตรวจสอบตามลำดับนี้:

1. Per-platform allow-all flag (เช่น DISCORD_ALLOW_ALL_USERS=true)
2. DM pairing approved list (ผู้ใช้ที่ได้รับการอนุมัติผ่าน pairing codes)
3. Platform-specific allowlists (เช่น TELEGRAM_ALLOWED_USERS=12345,67890)
4. Global allowlist (GATEWAY_ALLOWED_USERS=12345,67890)
5. Global allow-all (GATEWAY_ALLOW_ALL_USERS=true)
6. Default: deny

Platform Allowowlists

ตั้งค่า user ID ที่อนุญาตเป็นค่าที่คั่นด้วย comma ใน ~/.hermes/.env:

# Platform-specific allowlists
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=111222333444555666
WHATSAPP_ALLOWED_USERS=15551234567
SLACK_ALLOWED_USERS=U01ABC123

# Cross-platform allowlist (checked for all platforms)
GATEWAY_ALLOWED_USERS=123456789

# Per-platform allow-all (use with caution)
DISCORD_ALLOW_ALL_USERS=true

# Global allow-all (use with extreme caution)
GATEWAY_ALLOW_ALL_USERS=true

:::warning หาก ไม่มีการกำหนด allowlists และไม่ได้ตั้งค่า GATEWAY_ALLOW_ALL_USERS ผู้ใช้ทุกคนจะถูกปฏิเสธ gateway จะบันทึกคำเตือนเมื่อเริ่มต้นระบบ:

No user allowlists configured. All unauthorized users will be denied.
Set GATEWAY_ALLOW_ALL_USERS=true in ~/.hermes/.env to allow open access,
or configure platform allowlists (e.g., TELEGRAM_ALLOWED_USERS=your_id).

:::

DM Pairing System

สำหรับการอนุญาตสิทธิ์ที่ยืดหยุ่นยิ่งขึ้น Hermes มีระบบ pairing แบบใช้รหัส (code-based pairing system) แทนที่จะต้องระบุ user ID ตั้งแต่แรก ผู้ใช้ที่ไม่ทราบตัวจะได้รับรหัส pairing ชั่วคราวที่เจ้าของบอทจะอนุมัติผ่าน CLI

วิธีการทำงาน:

1. ผู้ใช้ที่ไม่ทราบตัวส่ง DM ไปยังบอท
2. บอทตอบกลับด้วยรหัส pairing 8 ตัวอักษร
3. เจ้าของบอทรัน hermes pairing approve <platform> <code> บน CLI
4. ผู้ใช้จะได้รับการอนุมัติถาวรสำหรับแพลตฟอร์มนั้น

ควบคุมวิธีการจัดการ direct messages ที่ไม่ได้รับอนุญาตใน ~/.hermes/config.yaml:

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore

• pair คือค่าเริ่มต้น DMs ที่ไม่ได้รับอนุญาตจะได้รับข้อความตอบกลับพร้อมรหัส pairing
• ignore จะทิ้ง DMs ที่ไม่ได้รับอนุญาตอย่างเงียบๆ
• ส่วนของแพลตฟอร์มจะเขียนทับค่าเริ่มต้นทั่วโลก ดังนั้นคุณสามารถคงการ pairing ไว้สำหรับ Telegram ในขณะที่ทำให้ WhatsApp เงียบได้

Security features (อิงตามแนวทาง OWASP + NIST SP 800-63-4):

Pairing CLI commands:

# List pending and approved users
hermes pairing list

# Approve a pairing code
hermes pairing approve telegram ABC12DEF

# Revoke a user's access
hermes pairing revoke telegram 123456789

# Clear all pending codes
hermes pairing clear-pending

Storage: ข้อมูล pairing ถูกจัดเก็บใน ~/.hermes/pairing/ ด้วยไฟล์ JSON แยกตามแพลตฟอร์ม:

• {platform}-pending.json - คำขอ pairing ที่รอดำเนินการ
• {platform}-approved.json - ผู้ใช้ที่ได้รับการอนุมัติ
• _rate_limits.json - การติดตาม rate limit และ lockout

Container Isolation

เมื่อใช้ terminal backend ของ docker, Hermes จะใช้การเสริมความแข็งแกร่งด้านความปลอดภัยอย่างเคร่งครัดกับทุกคอนเทนเนอร์

Docker Security Flags

ทุกคอนเทนเนอร์จะรันด้วย flag เหล่านี้ (กำหนดไว้ใน tools/environments/docker.py):

_SECURITY_ARGS = [
    "--cap-drop", "ALL",                          # Drop ALL Linux capabilities
    "--cap-add", "DAC_OVERRIDE",                  # Root can write to bind-mounted dirs
    "--cap-add", "CHOWN",                         # Package managers need file ownership
    "--cap-add", "FOWNER",                        # Package managers need file ownership
    "--security-opt", "no-new-privileges",         # Block privilege escalation
    "--pids-limit", "256",                         # Limit process count
    "--tmpfs", "/tmp:rw,nosuid,size=512m",         # Size-limited /tmp
    "--tmpfs", "/var/tmp:rw,noexec,nosuid,size=256m",  # No-exec /var/tmp
    "--tmpfs", "/run:rw,noexec,nosuid,size=64m",   # No-exec /run
]

Resource Limits

ทรัพยากรคอนเทนเนอร์สามารถกำหนดค่าได้ใน ~/.hermes/config.yaml:

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_forward_env: []  # Explicit allowlist only; empty keeps secrets out of the container
  container_cpu: 1        # CPU cores
  container_memory: 5120  # MB (default 5GB)
  container_disk: 51200   # MB (default 50GB, requires overlay2 on XFS)
  container_persistent: true  # Persist filesystem across sessions

Filesystem Persistence

• Persistent mode (container_persistent: true): Bind-mounts /workspace และ /root จาก ~/.hermes/sandboxes/docker/<task_id>/
• Ephemeral mode (container_persistent: false): ใช้ tmpfs สำหรับ workspace — ทุกอย่างจะสูญหายเมื่อทำความสะอาด

:::tip สำหรับการใช้งาน gateway ในสภาพแวดล้อม Production ให้ใช้ backend docker, modal, หรือ daytona เพื่อแยกคำสั่ง agent ออกจากระบบโฮสต์ของคุณ วิธีนี้จะขจัดความจำเป็นในการอนุมัติคำสั่งอันตรายไปโดยสิ้นเชิง :::

:::warning หากคุณเพิ่มชื่อใน terminal.docker_forward_env ตัวแปรเหล่านั้นจะถูกฉีดเข้าไปในคอนเทนเนอร์โดยเจตนาสำหรับคำสั่ง terminal ซึ่งมีประโยชน์สำหรับ credentials เฉพาะงาน เช่น GITHUB_TOKEN แต่ก็หมายความว่าโค้ดที่รันในคอนเทนเนอร์สามารถอ่านและส่งออกข้อมูลเหล่านั้นได้ :::

Terminal Backend Security Comparison

Environment Variable Passthrough {#environment-variable-passthrough}

ทั้ง execute_code และ terminal จะลบตัวแปรสภาพแวดล้อมที่ละเอียดอ่อนออกจาก child processes เพื่อป้องกันการส่งออกข้อมูลรับรองโดยโค้ดที่สร้างโดย LLM อย่างไรก็ตาม skills ที่ประกาศ required_environment_variables จำเป็นต้องเข้าถึงตัวแปรเหล่านั้นโดยชอบธรรม

How It Works

กลไกสองอย่างช่วยให้ตัวแปรบางตัวผ่านตัวกรอง sandbox ได้:

1. Skill-scoped passthrough (automatic)

เมื่อมีการโหลด skill (ผ่าน skill_view หรือคำสั่ง /skill) และประกาศ required_environment_variables ตัวแปรเหล่านั้นที่ถูกตั้งค่าอยู่ในสภาพแวดล้อมจริงจะถูกลงทะเบียนเป็น passthrough โดยอัตโนมัติ ตัวแปรที่ขาดหายไป (ยังอยู่ในสถานะ setup-needed) จะ ไม่ ถูกลงทะเบียน

# In a skill's SKILL.md frontmatter
required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor

หลังจากโหลด skill นี้แล้ว TENOR_API_KEY จะผ่านไปยัง execute_code, terminal (local), และ remote backends (Docker, Modal) - ไม่ต้องกำหนดค่าด้วยตนเอง

:::info Docker & Modal ก่อน v0.5.1, forward_env ของ Docker เป็นระบบแยกจาก skill passthrough ปัจจุบันทั้งสองถูกรวมเข้าด้วยกัน - ตัวแปร env ที่ประกาศโดย skill จะถูกส่งต่อไปยัง Docker containers และ Modal sandboxes โดยอัตโนมัติโดยไม่จำเป็นต้องเพิ่มใน docker_forward_env ด้วยตนเอง :::

2. Config-based passthrough (manual)

สำหรับ env vars ที่ไม่ได้ประกาศโดย skill ใดๆ ให้เพิ่มพวกมันใน terminal.env_passthrough ใน config.yaml:

terminal:
  env_passthrough:
    - MY_CUSTOM_KEY
    - ANOTHER_TOKEN

Credential File Passthrough (OAuth tokens, etc.) {#credential-file-passthrough}

บาง skill ต้องการ ไฟล์ (ไม่ใช่แค่ env vars) ใน sandbox - ตัวอย่างเช่น Google Workspace จัดเก็บ OAuth tokens เป็น google_token.json ภายใต้ HERMES_HOME ของโปรไฟล์ที่ใช้งาน Skills จะประกาศสิ่งเหล่านี้ใน frontmatter:

required_credential_files:
  - path: google_token.json
    description: Google OAuth2 token (created by setup script)
  - path: google_client_secret.json
    description: Google OAuth2 client credentials

เมื่อโหลดแล้ว Hermes จะตรวจสอบว่าไฟล์เหล่านี้มีอยู่ใน HERMES_HOME ของโปรไฟล์ที่ใช้งานหรือไม่ และลงทะเบียนเพื่อการ mount:

• Docker: Read-only bind mounts (-v host:container:ro)
• Modal: Mounted เมื่อสร้าง sandbox + sync ก่อนคำสั่งทุกครั้ง (จัดการ setup OAuth กลางเซสชัน)
• Local: ไม่ต้องดำเนินการใดๆ (ไฟล์เข้าถึงได้อยู่แล้ว)

คุณยังสามารถระบุไฟล์ credential ด้วยตนเองใน config.yaml:

terminal:
  credential_files:
    - google_token.json
    - my_custom_oauth_token.json

Paths เป็น relative to ~/.hermes/. ไฟล์จะถูก mount ไปที่ /root/.hermes/ ภายในคอนเทนเนอร์

What Each Sandbox Filters

Security Considerations

• Passthrough มีผลเฉพาะกับ vars ที่คุณหรือ skills ของคุณประกาศอย่างชัดเจน - ท่าทีด้านความปลอดภัยเริ่มต้นยังคงไม่เปลี่ยนแปลงสำหรับโค้ดที่สร้างโดย LLM แบบสุ่ม
• Credential files ถูก mount เป็น read-only ใน Docker containers
• Skills Guard สแกนเนื้อหา skill เพื่อหา patterns การเข้าถึง env ที่น่าสงสัยก่อนการติดตั้ง
• Vars ที่ขาดหายไป/ไม่ได้ตั้งค่าจะไม่ถูกลงทะเบียน (คุณไม่สามารถรั่วไหลสิ่งที่ไม่มีอยู่ได้)
• Hermes infrastructure secrets (provider API keys, gateway tokens) ไม่ควรถูกเพิ่มใน env_passthrough - พวกมันมีกลไกเฉพาะ

MCP Credential Handling

MCP (Model Context Protocol) server subprocesses จะได้รับ สภาพแวดล้อมที่ถูกกรอง เพื่อป้องกันการรั่วไหลของข้อมูลรับรองโดยไม่ได้ตั้งใจ

Safe Environment Variables

มีเพียงตัวแปรเหล่านี้เท่านั้นที่ถูกส่งผ่านจาก host ไปยัง MCP stdio subprocesses:

PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR

บวกกับตัวแปร XDG_* อื่นๆ ตัวแปรสภาพแวดล้อมอื่นๆ ทั้งหมด (API keys, tokens, secrets) จะถูก ลบออก

ตัวแปรที่กำหนดอย่างชัดเจนใน env config ของ MCP server จะถูกส่งผ่าน:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."  # Only this is passed

Credential Redaction

ข้อความแสดงข้อผิดพลาดจากเครื่องมือ MCP จะถูกทำความสะอาดก่อนส่งกลับไปยัง LLM รูปแบบต่อไปนี้จะถูกแทนที่ด้วย [REDACTED]:

• GitHub PATs (ghp_...)
• OpenAI-style keys (sk-...)
• Bearer tokens
• พารามิเตอร์ token=, key=, API_KEY=, password=, secret=

Website Access Policy

คุณสามารถจำกัดเว็บไซต์ที่ agent สามารถเข้าถึงได้ผ่าน web และ browser tools ซึ่งมีประโยชน์ในการป้องกันไม่ให้ agent เข้าถึงบริการภายใน, admin panels, หรือ URL ที่ละเอียดอ่อนอื่นๆ

# In ~/.hermes/config.yaml
security:
  website_blocklist:
    enabled: true
    domains:
      - "*.internal.company.com"
      - "admin.example.com"
    shared_files:
      - "/etc/hermes/blocked-sites.txt"

เมื่อมีการร้องขอ URL ที่ถูกบล็อก เครื่องมือจะส่งคืนข้อผิดพลาดที่อธิบายว่าโดเมนนั้นถูกบล็อกตามนโยบาย blocklist จะถูกบังคับใช้ทั่ว web_search, web_extract, browser_navigate, และเครื่องมือที่รองรับ URL ทั้งหมด

ดู Website Blocklist ในคู่มือการกำหนดค่าสำหรับรายละเอียดทั้งหมด

SSRF Protection

เครื่องมือที่รองรับ URL ทั้งหมด (web search, web extract, vision, browser) จะตรวจสอบ URL ก่อนการดึงข้อมูลเพื่อป้องกันการโจมตี Server-Side Request Forgery (SSRF) ที่อยู่ถูกบล็อกรวมถึง:

• Private networks (RFC 1918): 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
• Loopback: 127.0.0.0/8, ::1
• Link-local: 169.254.0.0/16 (รวมถึง cloud metadata ที่ 169.254.169.254)
• CGNAT / shared address space (RFC 6598): 100.64.0.0/10 (Tailscale, WireGuard VPNs)
• Cloud metadata hostnames: metadata.google.internal, metadata.goog
• Reserved, multicast, and unspecified addresses

SSRF protection ทำงานอยู่เสมอและไม่สามารถปิดได้ การล้มเหลวของ DNS จะถูกถือว่าถูกบล็อก (fail-closed) ลำดับการ redirect จะถูกตรวจสอบซ้ำที่แต่ละ hop เพื่อป้องกันการข้ามผ่านด้วยการ redirect

Tirith Pre-Exec Security Scanning

Hermes รวม tirith สำหรับการสแกนคำสั่งระดับเนื้อหาก่อนการดำเนินการ Tirith ตรวจจับภัยคุกคามที่การจับคู่รูปแบบเพียงอย่างเดียวมองข้ามไป:

• Homograph URL spoofing (internationalized domain attacks)
• Pipe-to-interpreter patterns (curl | bash, wget | sh)
• Terminal injection attacks

Tirith ติดตั้งอัตโนมัติจาก GitHub releases ในการใช้งานครั้งแรกพร้อมการตรวจสอบ SHA-256 checksum (และ cosign provenance verification หากมี cosign)

# In ~/.hermes/config.yaml
security:
  tirith_enabled: true       # Enable/disable tirith scanning (default: true)
  tirith_path: "tirith"      # Path to tirith binary (default: PATH lookup)
  tirith_timeout: 5          # Subprocess timeout in seconds
  tirith_fail_open: true     # Allow execution when tirith is unavailable (default: true)

เมื่อ tirith_fail_open เป็น true (ค่าเริ่มต้น) คำสั่งจะดำเนินการต่อหากไม่มีการติดตั้ง tirith หรือหมดเวลา ตั้งค่าเป็น false ในสภาพแวดล้อมความปลอดภัยสูงเพื่อบล็อกคำสั่งเมื่อ tirith ไม่พร้อมใช้งาน

ผลการตัดสินของ Tirith จะรวมเข้ากับ approval flow: คำสั่งที่ปลอดภัยจะผ่านไปได้ ในขณะที่คำสั่งที่น่าสงสัยและถูกบล็อกจะกระตุ้นให้เกิดการอนุมัติจากผู้ใช้พร้อมผลการค้นพบทั้งหมดของ tirith (severity, title, description, safer alternatives) ผู้ใช้สามารถอนุมัติหรือปฏิเสธได้ - ตัวเลือกเริ่มต้นคือปฏิเสธเพื่อรักษาความปลอดภัยในสถานการณ์ที่ไม่มีผู้ดูแล

Context File Injection Protection

Context files (AGENTS.md, .cursorrules, SOUL.md) จะถูกสแกนเพื่อหา prompt injection ก่อนที่จะถูกรวมเข้าใน system prompt ตัวสแกนจะตรวจสอบสำหรับ:

• คำสั่งให้เพิกเฉย/ไม่สนใจคำสั่งก่อนหน้า
• HTML comments ที่ซ่อนอยู่พร้อม keywords ที่น่าสงสัย
• ความพยายามในการอ่าน secrets (.env, credentials, .netrc)
• การส่งออกข้อมูลรับรองผ่าน curl
• Unicode characters ที่มองไม่เห็น (zero-width spaces, bidirectional overrides)

ไฟล์ที่ถูกบล็อกจะแสดงคำเตือน:

[BLOCKED: AGENTS.md contained potential prompt injection (prompt_injection). Content not loaded.]

Best Practices for Production Deployment

Gateway Deployment Checklist

1. Set explicit allowlists - ห้ามใช้ GATEWAY_ALLOW_ALL_USERS=true ใน Production
2. Use container backend - ตั้งค่า terminal.backend: docker ใน config.yaml
3. Restrict resource limits - ตั้งค่า CPU, memory, และ disk limits ให้เหมาะสม
4. Store secrets securely - เก็บ API keys ใน ~/.hermes/.env ด้วยสิทธิ์ไฟล์ที่เหมาะสม
5. Enable DM pairing - ใช้ pairing codes แทนการ hardcoding user IDs เมื่อเป็นไปได้
6. Review command allowlist - ตรวจสอบ command_allowlist ใน config.yaml เป็นระยะ
7. Set MESSAGING_CWD - อย่าปล่อยให้ agent ทำงานจาก directory ที่ละเอียดอ่อน
8. Run as non-root - ห้ามรัน gateway ในฐานะ root
9. Monitor logs - ตรวจสอบ ~/.hermes/logs/ สำหรับความพยายามเข้าถึงที่ไม่ได้รับอนุญาต
10. Keep updated - รัน hermes update เป็นประจำเพื่อรับ security patches

Securing API Keys

# Set proper permissions on the .env file
chmod 600 ~/.hermes/.env

# Keep separate keys for different services
# Never commit .env files to version control

Network Isolation

สำหรับการรักษาความปลอดภัยสูงสุด ให้รัน gateway บนเครื่องหรือ VM แยกต่างหาก:

terminal:
  backend: ssh
  ssh_host: "agent-worker.local"
  ssh_user: "hermes"
  ssh_key: "~/.ssh/hermes_agent_key"

วิธีนี้จะแยกการเชื่อมต่อ messaging ของ gateway ออกจากการดำเนินการคำสั่งของ agent

📄 user-guide/docker.md

sidebar_position: 7 title: "Docker" description: "การรัน Hermes Agent ใน Docker และการใช้ Docker เป็น terminal backend"

Hermes Agent - Docker

มีสองวิธีหลักที่ Docker เข้ามาเกี่ยวข้องกับ Hermes Agent:

1. การรัน Hermes IN Docker - ตัว agent เองจะทำงานภายใน container (เป็นจุดเน้นหลักของหน้านี้)
2. Docker เป็น terminal backend - agent ทำงานบน host ของคุณ แต่จะรันคำสั่งภายใน Docker sandbox (ดูที่ Configuration → terminal.backend)

หน้านี้ครอบคลุมตัวเลือกที่ 1 container จะจัดเก็บข้อมูลผู้ใช้ทั้งหมด (config, API keys, sessions, skills, memories) ในไดเรกทอรีเดียวที่ถูก mount มาจาก host ที่ /opt/data ตัว image เองเป็นแบบ stateless และสามารถอัปเกรดได้โดยการดึงเวอร์ชันใหม่โดยไม่สูญเสียการตั้งค่าใดๆ

Quick start

หากนี่เป็นครั้งแรกที่คุณรัน Hermes Agent ให้สร้าง data directory บน host และเริ่ม container แบบ interactive เพื่อรัน setup wizard:

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

คำสั่งนี้จะนำคุณเข้าสู่ setup wizard ซึ่งจะแจ้งให้คุณป้อน API keys และเขียนลงใน ~/.hermes/.env คุณต้องทำขั้นตอนนี้เพียงครั้งเดียวเท่านั้น ขอแนะนำอย่างยิ่งให้ตั้งค่า chat system สำหรับ gateway เพื่อให้ทำงานได้ในจุดนี้

Running in gateway mode

เมื่อตั้งค่าเรียบร้อยแล้ว ให้รัน container ใน background เพื่อให้เป็น gateway แบบ persistent (เช่น Telegram, Discord, Slack, WhatsApp, ฯลฯ):

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

Port 8642 เปิดเผย OpenAI-compatible API server และ health endpoint ของ gateway เป็นทางเลือกหากคุณใช้แค่ chat platforms (Telegram, Discord, ฯลฯ) แต่จำเป็นหากคุณต้องการให้ dashboard หรือ external tools เข้าถึง gateway

การเปิด port ใดๆ บนเครื่องที่เชื่อมต่ออินเทอร์เน็ตถือเป็นความเสี่ยงด้านความปลอดภัย คุณไม่ควรทำเช่นนั้นหากคุณไม่เข้าใจความเสี่ยงที่เกี่ยวข้อง

Running the dashboard

Web dashboard ที่มาพร้อมกับระบบสามารถรันควบคู่ไปกับ gateway ในฐานะ container แยกต่างหากได้

ในการรัน dashboard เป็น container ของตัวเอง ให้ชี้มันไปยัง health endpoint ของ gateway เพื่อให้สามารถตรวจจับสถานะของ gateway ข้าม 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

แทนที่ $HOST_IP ด้วย IP address ของเครื่องที่รัน gateway container (เช่น 192.168.1.100) หรือใช้ Docker network hostname หากทั้งสอง container แชร์ network เดียวกัน (ดู Compose example ด้านล่าง)

หากไม่มี GATEWAY_HEALTH_URL dashboard จะ fallback ไปที่การตรวจจับ process ภายในเครื่อง ซึ่งจะใช้งานได้ก็ต่อเมื่อ gateway รันอยู่ใน container เดียวกันหรือบน host เดียวกันเท่านั้น

Running interactively (CLI chat)

ในการเปิดเซสชัน chat แบบ interactive กับ data directory ที่กำลังรันอยู่:

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

Persistent volumes

volume /opt/data คือแหล่งข้อมูลความจริง (single source of truth) สำหรับสถานะทั้งหมดของ Hermes มันจะ map ไปยังไดเรกทอรี ~/.hermes/ ของ host และประกอบด้วย:

:::warning ห้ามรัน container gateway ของ Hermes สองตัวพร้อมกันกับ data directory เดียวกันโดยเด็ดขาด - ไฟล์เซสชันและ memory stores ไม่ได้ออกแบบมาสำหรับการเข้าถึงแบบเขียนพร้อมกัน (concurrent write access) การรัน dashboard container ควบคู่ไปกับ gateway นั้นปลอดภัย เนื่องจาก dashboard ทำได้เพียงอ่านข้อมูลเท่านั้น :::

Environment variable forwarding

API keys จะถูกอ่านจาก /opt/data/.env ภายใน container คุณยังสามารถส่ง environment variables ได้โดยตรง:

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

การใช้ flag -e โดยตรงจะเขียนทับค่าจาก .env ซึ่งมีประโยชน์สำหรับการทำ CI/CD หรือการรวมระบบกับ secrets-manager ที่คุณไม่ต้องการให้ keys อยู่บน disk

Docker Compose example

สำหรับการ deploy แบบ persistent ทั้ง gateway และ dashboard การใช้ docker-compose.yaml นั้นสะดวก:

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

  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

เริ่มด้วย docker compose up -d และดู logs ด้วย docker compose logs -f

Resource limits

container ของ Hermes ต้องการทรัพยากรปานกลาง ค่าต่ำสุดที่แนะนำ:

Browser automation (Playwright/Chromium) เป็นฟีเจอร์ที่ใช้หน่วยความจำมากที่สุด หากคุณไม่ต้องการเครื่องมือ browser ก็เพียงพอที่ 1 GB แต่หากเปิดใช้งานเครื่องมือ browser ให้จัดสรรอย่างน้อย 2 GB

การตั้งค่า limits ใน Docker:

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

What the Dockerfile does

image อย่างเป็นทางการนี้สร้างจาก debian:13.4 และรวมถึง:

• Python 3 พร้อม dependencies ทั้งหมดของ Hermes (pip install -e ".[all]")
• Node.js + npm (สำหรับ browser automation และ WhatsApp bridge)
• Playwright พร้อม Chromium (npx playwright install --with-deps chromium)
• ripgrep และ ffmpeg เป็น system utilities
• WhatsApp bridge (scripts/whatsapp-bridge/)

entrypoint script (docker/entrypoint.sh) จะทำการ bootstrap data volume ในการรันครั้งแรก:

• สร้างโครงสร้างไดเรกทอรี (sessions/, memories/, skills/, ฯลฯ)
• คัดลอก .env.example → .env หากไม่มี .env
• คัดลอก config.yaml เริ่มต้นหากขาดหายไป
• คัดลอก SOUL.md เริ่มต้นหากขาดหายไป
• Sync skills ที่ bundle โดยใช้แนวทางแบบ manifest-based (รักษาการแก้ไขของผู้ใช้)
• จากนั้นรัน hermes ด้วย argument ใดๆ ที่คุณส่งมา

Upgrading

ดึง image ล่าสุดและสร้าง container ใหม่ ไดเรกทอรีข้อมูลของคุณจะไม่ถูกแตะต้อง

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

หรือด้วย Docker Compose:

docker compose pull
docker compose up -d

Skills and credential files

เมื่อใช้ Docker เป็น execution environment (ไม่ใช่ methods ด้านบน แต่เมื่อ agent รันคำสั่งภายใน Docker sandbox) Hermes จะทำการ bind-mount skills directory (~/.hermes/skills/) และไฟล์ credential ใดๆ ที่ประกาศโดย skills เข้าไปใน container ในรูปแบบ read-only volumes นี่หมายความว่า script, template, และ reference ของ skill จะพร้อมใช้งานภายใน sandbox โดยไม่ต้องตั้งค่าด้วยตนเอง

การ sync แบบเดียวกันนี้เกิดขึ้นสำหรับ SSH และ Modal backends - skills และ credential files จะถูกอัปโหลดผ่าน rsync หรือ Modal mount API ก่อนคำสั่งแต่ละครั้ง

Troubleshooting

Container exits immediately

ตรวจสอบ logs: docker logs hermes สาเหตุทั่วไป:

• ไฟล์ .env หายไปหรือไม่ถูกต้อง - ให้รันแบบ interactive ก่อนเพื่อทำ setup ให้เสร็จ
• Port conflicts หากรันพร้อมกับการเปิด port

"Permission denied" errors

container จะรันเป็น root โดยค่าเริ่มต้น หาก ~/.hermes/ ของ host ถูกสร้างโดยผู้ใช้ที่ไม่ใช่ root สิทธิ์ควรจะใช้งานได้ หากคุณได้รับข้อผิดพลาด ให้แน่ใจว่า data directory สามารถเขียนได้:

chmod -R 755 ~/.hermes

Browser tools not working

Playwright ต้องการ shared memory ให้เพิ่ม --shm-size=1g เข้าไปในคำสั่ง Docker run ของคุณ:

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

Gateway not reconnecting after network issues

flag --restart unless-stopped จัดการกับความล้มเหลวชั่วคราวส่วนใหญ่ หาก gateway ค้าง ให้รีสตาร์ท container:

docker restart hermes

Checking container health

docker logs --tail 50 hermes          # logs ล่าสุด
docker run -it --rm nousresearch/hermes-agent:latest version     # ตรวจสอบเวอร์ชัน
docker stats hermes                    # การใช้ทรัพยากร

📄 user-guide/git-worktrees.md

sidebar_position: 3 sidebar_label: "Git Worktrees" title: "Git Worktrees" description: "Run multiple Hermes agents safely on the same repository using git worktrees and isolated checkouts"

Git Worktrees

Hermes Agent มักถูกใช้กับ repositories ขนาดใหญ่และมีอายุการใช้งานยาวนาน เมื่อคุณต้องการ:

• รัน multiple agents ในรูปแบบขนาน บน project เดียวกัน หรือ
• ต้องการแยกการ refactor แบบทดลองออกจาก main branch ของคุณ

Git worktrees เป็นวิธีที่ปลอดภัยที่สุดในการให้แต่ละ agent มี checkout ของตัวเอง โดยที่ไม่ต้องทำซ้ำ (duplicate) repository ทั้งหมด

หน้านี้จะแสดงวิธีรวม worktrees เข้ากับ Hermes เพื่อให้แต่ละ session มี working directory ที่สะอาดและแยกส่วนกัน

Why Use Worktrees with Hermes?

Hermes จะถือว่า current working directory เป็น root ของ project:

• CLI: directory ที่คุณรัน hermes หรือ hermes chat
• Messaging gateways: directory ที่กำหนดโดย MESSAGING_CWD

หากคุณรันหลาย agents ใน same checkout การเปลี่ยนแปลงของพวกมันอาจรบกวนกันได้:

• agent ตัวหนึ่งอาจลบหรือเขียนทับไฟล์ที่ agent ตัวอื่นกำลังใช้งานอยู่
• ทำให้ยากต่อการทำความเข้าใจว่าการเปลี่ยนแปลงใดเป็นของ experiment ไหน

ด้วย worktrees, แต่ละ agent จะได้รับ:

• branch และ working directory เป็นของตัวเอง
• Checkpoint Manager history เป็นของตัวเองสำหรับ /rollback

ดูเพิ่มเติม: Checkpoints and /rollback.

Quick Start: Creating a Worktree

จาก main repository ของคุณ (ที่มี .git/) ให้สร้าง worktree ใหม่สำหรับ feature branch:

# From the main repo root
cd /path/to/your/repo

# Create a new branch and worktree in ../repo-feature
git worktree add ../repo-feature feature/hermes-experiment

สิ่งนี้จะสร้าง:

• directory ใหม่: ../repo-feature
• branch ใหม่: feature/hermes-experiment ที่ถูก checkout ใน directory นั้น

ตอนนี้คุณสามารถ cd เข้าไปใน worktree ใหม่และรัน Hermes ที่นั่นได้:

cd ../repo-feature

# Start Hermes in the worktree
hermes

Hermes จะ:

• เห็น ../repo-feature เป็น project root.
• ใช้ directory นั้นสำหรับ context files, code edits, และ tools.
• ใช้ separate checkpoint history สำหรับ /rollback ที่จำกัดขอบเขตเฉพาะ worktree นี้.

Running Multiple Agents in Parallel

คุณสามารถสร้าง worktrees หลายตัว โดยแต่ละตัวมี branch เป็นของตัวเอง:

cd /path/to/your/repo

git worktree add ../repo-experiment-a feature/hermes-a
git worktree add ../repo-experiment-b feature/hermes-b

ใน terminal แยกกัน:

# Terminal 1
cd ../repo-experiment-a
hermes

# Terminal 2
cd ../repo-experiment-b
hermes

แต่ละ process ของ Hermes:

• ทำงานบน branch ของตัวเอง (feature/hermes-a vs feature/hermes-b).
• เขียน checkpoints ภายใต้ shadow repo hash ที่แตกต่างกัน (ได้มาจาก worktree path).
• สามารถใช้ /rollback ได้อย่างอิสระโดยไม่ส่งผลกระทบต่อตัวอื่น.

สิ่งนี้มีประโยชน์อย่างยิ่งเมื่อ:

• รัน batch refactors.
• ทดลองแนวทางที่แตกต่างกันสำหรับงานเดียวกัน.
• จับคู่ session ของ CLI + gateway กับ upstream repo เดียวกัน.

Cleaning Up Worktrees Safely

เมื่อคุณทำ experiment เสร็จแล้ว:

1. ตัดสินใจว่าจะเก็บหรือทิ้ง work ที่ทำไป.
2. หากคุณต้องการเก็บ:
   • Merge branch นั้นเข้ากับ main branch ของคุณตามปกติ.
3. ลบ worktree:

cd /path/to/your/repo

# Remove the worktree directory and its reference
git worktree remove ../repo-feature

หมายเหตุ:

• git worktree remove จะปฏิเสธการลบ worktree ที่มีการเปลี่ยนแปลงที่ยังไม่ได้ commit เว้นแต่คุณจะบังคับ (force) มัน.
• การลบ worktree ไม่ได้ ลบ branch โดยอัตโนมัติ; คุณสามารถลบหรือเก็บ branch ได้โดยใช้คำสั่ง git branch ปกติ.
• ข้อมูล checkpoint ของ Hermes ภายใต้ ~/.hermes/checkpoints/ จะไม่ถูกลบโดยอัตโนมัติเมื่อคุณลบ worktree แต่โดยปกติแล้วจะมีขนาดเล็กมาก.

Best Practices

• One worktree per Hermes experiment
  • สร้าง branch/worktree เฉพาะสำหรับทุกการเปลี่ยนแปลงที่สำคัญ.
  • วิธีนี้ช่วยให้ diffs มีโฟกัสและ PRs มีขนาดเล็กและสามารถตรวจสอบได้.
• Name branches after the experiment
  • เช่น feature/hermes-checkpoints-docs, feature/hermes-refactor-tests.
• Commit frequently
  • ใช้ git commits สำหรับ milestones ระดับสูง.
  • ใช้ checkpoints and /rollback เป็นตาข่ายนิรภัยสำหรับการแก้ไขที่ขับเคลื่อนด้วย tool ระหว่างนั้น.
• Avoid running Hermes from the bare repo root when using worktrees
  • ควรใช้ worktree directories แทน เพื่อให้แต่ละ agent มีขอบเขตที่ชัดเจน.

Using hermes -w (Automatic Worktree Mode)

Hermes มี flag -w ที่สร้างมาให้ ซึ่งจะ สร้าง git worktree ที่ใช้แล้วทิ้งโดยอัตโนมัติ พร้อมกับ branch ของตัวเอง คุณไม่จำเป็นต้องตั้งค่า worktrees ด้วยตนเอง - เพียงแค่ cd เข้าไปใน repo ของคุณแล้วรัน:

cd /path/to/your/repo
hermes -w

Hermes จะ:

• สร้าง worktree ชั่วคราวภายใต้ .worktrees/ ภายใน repo ของคุณ.
• Checkout branch ที่แยกส่วน (เช่น hermes/hermes-<hash>).
• รัน full CLI session ภายใน worktree นั้น.

นี่เป็นวิธีที่ง่ายที่สุดในการได้ worktree isolation คุณยังสามารถรวมมันเข้ากับการ query เดียวได้:

hermes -w -q "Fix issue #123"

สำหรับ agents แบบขนาน ให้เปิดหลาย terminal และรัน hermes -w ในแต่ละตัว — ทุกการเรียกใช้จะได้รับ worktree และ branch เป็นของตัวเองโดยอัตโนมัติ.

Putting It All Together

• ใช้ git worktrees เพื่อให้แต่ละ session ของ Hermes มี checkout ที่สะอาดเป็นของตัวเอง.
• ใช้ branches เพื่อบันทึก history ระดับสูงของการทดลองของคุณ.
• ใช้ checkpoints + /rollback เพื่อกู้คืนจากข้อผิดพลาดภายในแต่ละ worktree.

การรวมกันนี้จะมอบให้คุณ:

• การรับประกันที่แข็งแกร่งว่า agents และ experiments ที่แตกต่างกันจะไม่รบกวนกัน.
• รอบการทำซ้ำที่รวดเร็วพร้อมการกู้คืนที่ง่ายจาก edits ที่ผิดพลาด.
• pull requests ที่สะอาดและสามารถตรวจสอบได้.

📄 user-guide/checkpoints-and-rollback.md

sidebar_position: 8 sidebar_label: "Checkpoints & Rollback" title: "Checkpoints and /rollback" description: "Filesystem safety nets for destructive operations using shadow git repos and automatic snapshots"

Checkpoints and /rollback

Hermes Agent จะทำการ snapshot โปรเจกต์ของคุณโดยอัตโนมัติก่อนการดำเนินการที่อาจทำให้ข้อมูลสูญหาย (destructive operations) และอนุญาตให้คุณกู้คืนด้วยคำสั่งเดียว Checkpoints จะถูกเปิดใช้งานโดยค่าเริ่มต้น (enabled by default) - ไม่มีค่าใช้จ่ายใดๆ เลยแม้ว่าเครื่องมือใดๆ จะไม่ได้ทำการแก้ไขไฟล์ก็ตาม

ระบบป้องกันความปลอดภัยนี้ขับเคลื่อนโดย Checkpoint Manager ภายใน ซึ่งจะเก็บ shadow git repository แยกต่างหากที่ ~/.hermes/checkpoints/ - ทำให้มั่นใจได้ว่า .git ของโปรเจกต์จริงของคุณจะไม่ถูกแตะต้อง

สิ่งที่กระตุ้นการสร้าง Checkpoint

Checkpoints จะถูกสร้างโดยอัตโนมัติก่อนการดำเนินการเหล่านี้:

• File tools - write_file และ patch
• Destructive terminal commands - rm, mv, sed -i, truncate, shred, การเปลี่ยนเส้นทาง output (>) และ git reset/clean/checkout

Agent จะสร้าง checkpoint ได้สูงสุดหนึ่งจุดต่อไดเรกทอรีต่อรอบ (per directory per turn) เพื่อป้องกันไม่ให้การเซสชันที่ยาวนานเกิดการ snapshot มากเกินไป

ข้อมูลอ้างอิงด่วน

Checkpoints ทำงานอย่างไร

ในระดับสูง:

• Hermes จะตรวจจับเมื่อเครื่องมือกำลังจะ แก้ไขไฟล์ ใน working tree ของคุณ
• ในแต่ละรอบการสนทนา (ต่อไดเรกทอรี) มันจะ:
  • กำหนด root project ที่เหมาะสมสำหรับไฟล์
  • เริ่มต้นหรือใช้ซ้ำ shadow git repo ที่ผูกกับไดเรกทอรีนั้น
  • ทำการ stage และ commit สถานะปัจจุบันพร้อมเหตุผลสั้นๆ ที่อ่านเข้าใจได้
• commit เหล่านี้จะก่อให้เกิดประวัติ checkpoint ที่คุณสามารถตรวจสอบและกู้คืนได้ผ่าน /rollback

flowchart LR
  user["User command\n(hermes, gateway)"]
  agent["AIAgent\n(run_agent.py)"]
  tools["File & terminal tools"]
  cpMgr["CheckpointManager"]
  shadowRepo["Shadow git repo\n~/.hermes/checkpoints/<hash>"]

  user --> agent
  agent -->|"tool call"| tools
  tools -->|"before mutate\nensure_checkpoint()"| cpMgr
  cpMgr -->|"git add/commit"| shadowRepo
  cpMgr -->|"OK / skipped"| tools
  tools -->|"apply changes"| agent

การตั้งค่า (Configuration)

Checkpoints เปิดใช้งานโดยค่าเริ่มต้น สามารถกำหนดค่าได้ใน ~/.hermes/config.yaml:

checkpoints:
  enabled: true          # master switch (default: true)
  max_snapshots: 50      # max checkpoints per directory

หากต้องการปิดใช้งาน:

checkpoints:
  enabled: false

เมื่อปิดใช้งาน Checkpoint Manager จะเป็น no-op และจะไม่พยายามดำเนินการ git ใดๆ

การแสดงรายการ Checkpoints

จาก CLI session:

/rollback

Hermes จะตอบกลับด้วยรายการที่จัดรูปแบบซึ่งแสดงสถิติการเปลี่ยนแปลง:

📸 Checkpoints for /path/to/project:

  1. 4270a8c  2026-03-16 04:36  before patch  (1 file, +1/-0)
  2. eaf4c1f  2026-03-16 04:35  before write_file
  3. b3f9d2e  2026-03-16 04:34  before terminal: sed -i s/old/new/ config.py  (1 file, +1/-1)

  /rollback <N>             restore to checkpoint N
  /rollback diff <N>        preview changes since checkpoint N
  /rollback <N> <file>      restore a single file from checkpoint N

แต่ละรายการจะแสดง:

• Short hash
• Timestamp
• Reason (สิ่งที่กระตุ้นการ snapshot)
• Change summary (ไฟล์ที่เปลี่ยนแปลง, การเพิ่ม/การลบ)

การดูตัวอย่างการเปลี่ยนแปลงด้วย /rollback diff

ก่อนที่จะ commit ไปสู่การกู้คืน ควรดูตัวอย่างว่าอะไรเปลี่ยนแปลงไปตั้งแต่ checkpoint:

/rollback diff 1

สิ่งนี้จะแสดงสรุปสถิติ git diff ตามด้วย diff จริง:

test.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test.py b/test.py
--- a/test.py
+++ b/test.py
@@ -1 +1 @@
-print('original content')
+print('modified content')

diff ที่ยาวจะถูกจำกัดไว้ที่ 80 บรรทัดเพื่อป้องกันไม่ให้ terminal ล้น

การกู้คืนด้วย /rollback

กู้คืนไปยัง checkpoint ตามหมายเลข:

/rollback 1

เบื้องหลัง Hermes จะ:

1. ตรวจสอบว่า commit เป้าหมายมีอยู่ใน shadow repo หรือไม่
2. ทำการ snapshot ก่อนการ rollback ของสถานะปัจจุบัน เพื่อให้คุณสามารถ "ยกเลิกการยกเลิก" ได้ในภายหลัง
3. กู้คืนไฟล์ที่ถูกติดตาม (tracked files) ใน working directory ของคุณ
4. ยกเลิกการสนทนาครั้งล่าสุด เพื่อให้ context ของ agent ตรงกับสถานะ filesystem ที่กู้คืนมา

เมื่อสำเร็จ:

✅ Restored to checkpoint 4270a8c5: before patch
A pre-rollback snapshot was saved automatically.
(^_^)b Undid 4 message(s). Removed: "Now update test.py to ..."
  4 message(s) remaining in history.
  Chat turn undone to match restored file state.

การยกเลิกการสนทนาช่วยให้มั่นใจว่า agent จะไม่ "จดจำ" การเปลี่ยนแปลงที่ถูก rollback ซึ่งช่วยป้องกันความสับสนในรอบถัดไป

การกู้คืนไฟล์เดียว

กู้คืนเพียงไฟล์เดียวจาก checkpoint โดยไม่กระทบต่อส่วนอื่นๆ ของไดเรกทอรี:

/rollback 1 src/broken_file.py

สิ่งนี้มีประโยชน์เมื่อ agent ทำการเปลี่ยนแปลงไฟล์หลายไฟล์ แต่มีเพียงไฟล์เดียวที่ต้องการย้อนกลับ

มาตรการความปลอดภัยและประสิทธิภาพ (Safety and Performance Guards)

เพื่อให้การทำ checkpoint ปลอดภัยและรวดเร็ว Hermes จึงใช้มาตรการป้องกันหลายอย่าง:

• Git availability - หากไม่พบ git ใน PATH การทำ checkpoint จะถูกปิดใช้งานอย่างโปร่งใส
• Directory scope - Hermes จะข้ามไดเรกทอรีที่กว้างเกินไป (เช่น root /, home $HOME)
• Repository size - ไดเรกทอรีที่มีไฟล์มากกว่า 50,000 ไฟล์จะถูกข้ามเพื่อหลีกเลี่ยงการดำเนินการ git ที่ช้า
• No-change snapshots - หากไม่มีการเปลี่ยนแปลงใดๆ นับตั้งแต่ snapshot ล่าสุด checkpoint จะถูกข้าม
• Non-fatal errors - ข้อผิดพลาดทั้งหมดภายใน Checkpoint Manager จะถูกบันทึกที่ระดับ debug; เครื่องมือของคุณจะยังคงทำงานต่อไป

Checkpoints อยู่ที่ใด

shadow repo ทั้งหมดจะอยู่ภายใต้:

~/.hermes/checkpoints/
  ├── <hash1>/   # shadow git repo for one working directory
  ├── <hash2>/
  └── ...

แต่ละ <hash> ได้มาจาก absolute path ของ working directory ภายในแต่ละ shadow repo คุณจะพบ:

• Standard git internals (HEAD, refs/, objects/)
• ไฟล์ info/exclude ที่มีรายการ ignore ที่คัดสรรมา
• ไฟล์ HERMES_WORKDIR ที่ชี้กลับไปยัง root project ต้นฉบับ

โดยปกติคุณไม่จำเป็นต้องแตะต้องสิ่งเหล่านี้ด้วยตนเอง

แนวทางปฏิบัติที่ดีที่สุด (Best Practices)

• เปิดใช้งาน checkpoints ไว้ - โดยค่าเริ่มต้นและไม่มีค่าใช้จ่ายใดๆ เมื่อไม่มีการแก้ไขไฟล์
• ใช้ /rollback diff ก่อนกู้คืน - เพื่อดูตัวอย่างว่าอะไรจะเปลี่ยนแปลง เพื่อเลือก checkpoint ที่ถูกต้อง
• ใช้ /rollback แทน git reset เมื่อคุณต้องการยกเลิกเฉพาะการเปลี่ยนแปลงที่เกิดจาก agent เท่านั้น
• รวมกับการใช้ Git worktrees เพื่อความปลอดภัยสูงสุด - ให้เก็บแต่ละเซสชัน Hermes ไว้ใน worktree/branch ของตัวเอง พร้อมด้วย checkpoints เป็นชั้นความปลอดภัยเพิ่มเติม

สำหรับการรัน agent หลายตัวแบบขนานบน repo เดียวกัน โปรดดูคู่มือที่ Git worktrees