沙箱後端

源码版本v2026.7.20

職責

agent 要執行命令、跑程式碼,但不能讓任意命令直接打到宿主機。Hermes 的終端工具支援 6 種執行後端,按安全/隔離/成本權衡選擇:Local(本機直跑)、Docker(容器隔離)、SSH(遠端機器)、Singularity(HPC 容器)、Modal(雲沙箱,direct 或 managed)、Daytona(雲開發環境)。容器硬化 + 命名空間隔離,危險命令還經審批回調攔截。

關鍵檔案

• terminal_tool 頭部文件:1-15 — 列出 local / docker / modal / ssh / singularity / daytona 六後端
• Docker host 存取檢測:260-290 — _docker_volume_uses_host_path / _docker_has_host_access(檢測 bind mount 是否暴露宿主路徑)
• Singularity / Modal 匯入:65-90 — _get_scratch_dir(來自 environments/singularity)
• environments/singularity.py — Singularity scratch 目錄與 SIF 快取
• Modal 模式解析:77-137 — coerce_modal_mode / has_direct_modal_credentials / resolve_modal_backend_state(direct vs managed)
• _DEFAULT_BROWSER_PROVIDER:12 — 預設 provider 為 local
• 子代理審批回調:75-103 — _subagent_auto_deny / _subagent_auto_approve(沙箱內執行的危險命令管控)
• tools/daemon_pool.py — 子代理常駐執行緒池(承載沙箱執行)
• tools/ 目錄 — terminal / close_terminal / read_terminal / tool_backend_helpers / environments/

資料流

1. agent 決定執行命令 → tool_call terminal → tools/terminal_tool.py。
2. 按作業設定選後端(local/docker/modal/ssh/singularity/daytona):
   • local:直接宿主執行(最快,預設)
   • docker:tools/terminal_tool.py:260 檢測 bind mount 是否暴露宿主路徑,據此決定權限
   • modal:經 tools/tool_backend_helpers.py:102 解析 direct(使用者自己的 Modal 憑據)還是 managed(網關託管)
   • singularity:經 tools/environments/singularity.py 準備 scratch 與 SIF
   • ssh / daytona:遠端/雲環境
3. 危險命令經審批回調攔截——主迴圈用互動式審批;子代理預設 auto-deny(tools/delegate_tool.py:75),cron/批量可 opt-in auto-approve。
4. 命令輸出回填主迴圈;長任務可背景化(tools/daemon_pool.py)。

小結

沙箱層是「執行隔離 + 危險命令管控」:6 後端覆蓋從本機到 HPC 到雲;Docker 檢測 bind mount 防越權;Modal 區分 direct/managed 憑據;危險命令統一走審批回調。子代理與 cron 走 auto-deny/auto-approve 的非互動路徑。