# Hermes Local Agent Lanes

Safe local-model support lanes for a cloud owner agent.

This project packages a pattern we use with [Hermes Agent](https://github.com/NousResearch/hermes-agent): keep the strongest cloud model as the **owner** that makes decisions, mutates files, verifies, and reports; route low-risk background work to fast local models through narrow MCP tools.

> Local models should be useful coworkers, not unsupervised operators.

## What this repo shows

- **Local MLX model as a safe MCP support lane** for a cloud owner agent.
- **SSH stdio MCP mounting** so another computer can use the local model without exposing a LAN HTTP port.
- **Support-only boundary guards**: summary/classification/critique/draft are allowed; shell/patch/git/deploy/config/cron/hook/secrets are blocked.
- **Owner router demo** for deciding task intensity and whether support models may be used.
- **Separate quota support lane pattern** for using a secondary coding model as an advisory reviewer/patch-sketcher while the owner agent applies and verifies changes.

## Architecture

```text
Cloud owner agent (Hermes / GPT-class model)
  ├─ owns architecture, mutations, tests, commits, final QC
  ├─ calls narrow local MCP support tools when useful
  │
  └─ Local support lanes
      ├─ MLX/OpenAI-compatible model server on localhost
      ├─ stdio MCP wrapper: support + health tools only
      ├─ optional SSH stdio mount from another computer
      └─ optional coding support lane in read-only/advisory mode
```

## Why this matters

Most local-agent demos fail in one of two ways:

1. They let a weaker local model execute risky actions.
2. They use the expensive frontier model for every low-value summarization or log-reading step.

This repo uses a stricter split:

| Layer | Allowed | Forbidden |
|---|---|---|
| Cloud owner | plan, decide, edit, test, commit, report | surprise paid/external actions |
| Local MCP support | summarize, classify, critique, draft, explain | shell, patch, git, deploy, config, cron, hooks, secrets |
| Secondary coding quota lane | read-only review, patch sketches, bug hypotheses | direct workspace mutation unless owner verifies |

## Quick start

### 1. Run a local OpenAI-compatible model server

Any local server with `/v1/chat/completions` works. Example environment variables:

```bash
export LOCAL_MODEL_BASE_URL="http://127.0.0.1:18085/v1/chat/completions"
export LOCAL_MODEL_NAME="your-local-mlx-model"
```

### 2. Start the MCP server locally

```bash
python3 -m hermes_local_agent_lanes.mcp_support_server
```

### 3. Mount it from a local MCP client

```json
{
  "mcpServers": {
    "local-support-lane": {
      "command": "python3",
      "args": ["-m", "hermes_local_agent_lanes.mcp_support_server"]
    }
  }
}
```

### 4. Mount it from another computer over SSH

This avoids exposing the model server to your LAN:

```json
{
  "mcpServers": {
    "local-support-lane": {
      "command": "ssh",
      "args": [
        "user@your-mac-or-workstation",
        "cd /path/to/hermes-local-agent-lanes && python3 -m hermes_local_agent_lanes.mcp_support_server"
      ]
    }
  }
}
```

## Tools exposed

### `local_support`

Ask the local model for low-risk support only:

- summary
- classification
- critique
- draft
- simple code explanation
- read-only long-context compression

Risky prompts are blocked before reaching the model and return:

```text
TASK_REQUIRES_OWNER_AGENT
```

### `local_support_health`

Checks whether the local model endpoint is reachable.

## Run tests

```bash
python3 -m unittest discover -s tests
```

The tests exercise JSON-RPC MCP initialize/tool listing and the hard boundary guard without requiring a real model.

## Repo status

This is a small pattern repo, not a full Hermes fork. It is intentionally portable and public-safe: no private paths, no credentials, no runtime databases, no model weights.

## See also

- `docs/architecture.md` — deeper design notes
- `examples/mcp-config-ssh.json` — remote MCP mount example
- `examples/owner-router-demo.json` — intensity-routing example
- `src/hermes_local_agent_lanes/owner_router.py` — small callable router demo

## License

MIT