Metadata-Version: 2.4
Name: jupyter-hermes-proxy
Version: 0.1.0
Summary: Jupyter server proxy for Hermes Agent dashboard
Project-URL: Homepage, https://github.com/dive4dec/jupyter-hermes-proxy
Project-URL: Bug Tracker, https://github.com/dive4dec/jupyter-hermes-proxy/issues
Author-email: Chung Chan <chung.chan@cityu.edu.hk>
License: MIT
Requires-Python: >=3.12
Requires-Dist: jupyter-server-proxy>=4.0
Description-Content-Type: text/markdown

# jupyter-hermes-proxy

Launch the [Hermes Agent](https://github.com/nousresearch/hermes-agent) dashboard from JupyterLab as a native launcher entry.

## Features

- One-click launch from the JupyterLab launcher panel with a custom Hermes icon
- Automatic port management via [jupyter-server-proxy](https://github.com/jupyter-server/jupyter-server-proxy)
- Works behind reverse proxies (no manual port forwarding needed)
- **Two modes**: spawn a new dashboard, or connect to an existing one
- Configurable Hermes executable path via `HERMES_BIN_PATH`

## Installation

```bash
pip install jupyter-hermes-proxy
```

Then restart JupyterLab. The "Hermes Dashboard" launcher entry will appear automatically.

## Configuration

### Spawn mode (default)

By default the proxy searches for `hermes` in `PATH` and spawns a new dashboard process when you click the launcher.

Override the binary path:

```bash
export HERMES_BIN_PATH=/path/to/hermes
```

### URL mode (connect to existing dashboard)

When Hermes dashboard is already running (e.g. supervised by s6 in Docker), point the proxy at it:

```bash
export HERMES_DASHBOARD_URL=http://127.0.0.1:9119
```

In this mode the proxy **does not spawn a new process** — it simply proxies traffic to the existing dashboard. No `hermes` binary on PATH is required.

## Related Packages

- **[jupyter-ai-hermes](https://github.com/dive4dec/jupyter-ai-hermes)** — Hermes Agent as an ACP persona for Jupyter AI chat, with live notebook context injection and MCP tools for cell management.

Both packages share the same `HERMES_BIN_PATH` environment variable convention.

## Development

```bash
git clone git@github.com:dive4dec/jupyter-hermes-proxy.git
cd jupyter-hermes-proxy
pip install -e .
```

## How It Works

This package registers a server spec under the `jupyter_serverproxy_servers` entry point.

- **Spawn mode**: `jupyter-server-proxy` calls `setup_hermes()` which returns a command that spawns `hermes dashboard` on an ephemeral port and proxies it through the Jupyter server.
- **URL mode**: `setup_hermes()` returns the pre-existing dashboard URL directly, so jupyter-server-proxy connects to it without spawning anything.

## License

MIT
