Metadata-Version: 2.4
Name: hermes-open-sandbox
Version: 0.3.0
Summary: OpenSandbox execution backend for Hermes Agent - secure sandboxed code execution
Project-URL: Homepage, https://github.com/lordqyxz/hermes-open-sandbox
Project-URL: Repository, https://github.com/lordqyxz/hermes-open-sandbox
Project-URL: Issues, https://github.com/lordqyxz/hermes-open-sandbox/issues
Author-email: shiyz <yz.shi@outlook.com>
License: MIT
License-File: LICENSE
Keywords: code-execution,hermes,hermes-agent,opensandbox,sandbox
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: opensandbox>=0.1.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# hermes-open-sandbox

OpenSandbox execution backend for [Hermes Agent](https://github.com/NousResearch/hermes-agent).

Run Hermes terminal and file tools inside secure, isolated [OpenSandbox](https://github.com/alibaba/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

```bash
# 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:

```python
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

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENSANDBOX_DOMAIN` | `localhost:8080` | OpenSandbox server address |
| `OPENSANDBOX_API_KEY` | (none) | Authentication key |
| `OPENSANDBOX_IMAGE` | `nikolaik/python-nodejs:python3.11-nodejs20` | Container image |
| `OPENSANDBOX_CWD` | `/workspace` | Working directory |
| `OPENSANDBOX_CPU` | `1.0` | CPU cores |
| `OPENSANDBOX_MEMORY` | `5120` | Memory in MiB |
| `OPENSANDBOX_DISK` | `51200` | Disk in MiB |

## Hermes Config Keys

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

| Key | Description |
|-----|-------------|
| `terminal.opensandbox_domain` | Server address |
| `terminal.opensandbox_api_key` | API key |
| `terminal.opensandbox_image` | Container image |

## Manual Uninstall

```bash
# 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
