feat(tools): add microsandbox terminal backend

Adds microsandbox (https://microsandbox.dev) as a terminal backend alongside
docker/singularity/modal/daytona/ssh. Commands run inside a libkrun microVM
with its own kernel — meaningfully stronger isolation than the shared-kernel
container backends, without a cloud dependency or a daemon.

Backend shape is a thin wrapper around the msb CLI: one long-lived sandbox
per environment (msb create), command execution via msb exec, teardown via
msb stop + msb remove. Env-var filtering mirrors the Docker backend —
explicit docker-style microsandbox_forward_env / microsandbox_env lists,
skill passthroughs still filtered through _HERMES_PROVIDER_ENV_BLOCKLIST.

Files:
- tools/environments/microsandbox.py — new MicrosandboxEnvironment backend
- tools/terminal_tool.py — dispatch, container_config keys, image resolution
- hermes_cli/config.py — default microsandbox_* entries + env var sync
- cli-config.yaml.example — 'Option 7' documented config block
- tests/integration/test_microsandbox_terminal.py — skip-if-no-KVM
  integration tests for basic exec, filesystem, isolation, and the
  secret-leak regression

Host requirements: Linux with /dev/kvm readable (or macOS on Apple Silicon)
and msb on PATH or at MSB_PATH. Install: curl -fsSL https://install.microsandbox.dev | sh

Follow-up PR will wire this into the hermes_cli/setup.py wizard.
This commit is contained in:
Krzysztof Woś 2026-04-24 17:12:45 +09:00
parent 5dda4cab41
commit 1f2303d3e2
5 changed files with 531 additions and 4 deletions

View file

@ -226,8 +226,32 @@ terminal:
# daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"
# container_disk: 10240 # Daytona max is 10GB per sandbox
# -----------------------------------------------------------------------------
# OPTION 7: Microsandbox libkrun microVMs (local)
# Commands run in a libkrun microVM with its own kernel.
# Great for: strong isolation from the agent's env and filesystem while keeping
# everything local (no cloud dependency).
# Requires: Linux with /dev/kvm (or macOS on Apple Silicon), `msb` on PATH or
# MSB_PATH set. Install: curl -fsSL https://install.microsandbox.dev | sh
# -----------------------------------------------------------------------------
# terminal:
# backend: "microsandbox"
# cwd: "/root" # Path inside the VM
# timeout: 180
# lifetime_seconds: 300
# microsandbox_image: "python:3.12" # Any OCI image usable by msb
# # Optional: explicitly forward selected env vars into the VM.
# # Values come from your current shell first, then ~/.hermes/.env.
# # Warning: anything forwarded here is visible to commands in the VM.
# # microsandbox_forward_env:
# # - "GITHUB_TOKEN"
# # microsandbox_env:
# # PYTHONUNBUFFERED: "1"
# # microsandbox_volumes: # SOURCE:GUEST_PATH, host path or named volume
# # - "/host/data:/mnt/data"
#
# --- Container resource limits (docker, singularity, modal, daytona -- ignored for local/ssh) ---
# --- Container resource limits (docker, singularity, modal, daytona, microsandbox -- ignored for local/ssh) ---
# These settings apply to all container backends. They control the resources
# allocated to the sandbox and whether its filesystem persists across sessions.
container_cpu: 1 # CPU cores