hermes-open-sandbox

OpenSandbox execution backend for Hermes Agent.

Run Hermes terminal and file tools inside secure, isolated OpenSandbox containers instead of your local machine.

Architecture

hermes-open-sandbox (pip package)         Hermes Agent (after setup)
┌──────────────────────────────┐        ┌─────────────────────────────────┐
│ SandboxConfig                │        │ tools/environments/opensandbox  │
│ OpenSandboxSession           │──delegates──│  - BaseEnvironment subclass    │
│  - pure SDK wrapper          │        │  - auto-generated by CLI        │
│  - zero Hermes deps          │        │                                 │
└──────────────────────────────┘        └─────────────────────────────────┘

The package itself has no dependency on Hermes Agent internals. The thin adapter that bridges Hermes's BaseEnvironment interface is auto-generated into the Hermes installation directory by hermes-open-sandbox-setup.

Quick Start

# 1. Install the package
pip install hermes-open-sandbox opensandbox

# 2. Patch Hermes to register the backend (idempotent)
hermes-open-sandbox-setup

# 3. Configure
hermes config set terminal.backend opensandbox
export OPENSANDBOX_DOMAIN=your-server:8080
export OPENSANDBOX_API_KEY=sk-xxx

# 4. Restart Hermes and use it
hermes

Standalone Usage

You can also use the package directly without Hermes:

from hermes_opensandbox import OpenSandboxSession, SandboxConfig

config = SandboxConfig.from_env(
    domain="your-server:8080",
    api_key="sk-xxx",
)
with OpenSandboxSession(config) as session:
    session.create()
    output, exit_code = session.execute("echo hello")
    print(f"Output: {output}, Exit: {exit_code}")
    session.kill()

Supported Images

Any Docker image that includes bash:

• python:3.11
• nikolaik/python-nodejs:python3.11-nodejs20 (default, includes Node.js)
• ubuntu:22.04
• Custom images from your registry

Environment Variables

Hermes Config Keys

These can be set via hermes config set and take precedence over env vars:

Manual Uninstall

# Remove the wrapper
rm ~/.hermes/hermes-agent/tools/environments/opensandbox.py

# Restore backups
mv ~/.hermes/hermes-agent/tools/terminal_tool.py.bak ~/.hermes/hermes-agent/tools/terminal_tool.py
mv ~/.hermes/hermes-agent/agent/prompt_builder.py.bak ~/.hermes/hermes-agent/agent/prompt_builder.py

License

MIT