Metadata-Version: 2.5
Name: hermes-mordred
Version: 0.3.0a2
Summary: Privacy-preserving plugin bundle for the Hermes agent (NousResearch/hermes-agent)
Project-URL: Documentation, https://github.com/mordredagent/hermes-mordred/tree/main/docs
Project-URL: Source, https://github.com/mordredagent/hermes-mordred
Author: InternetMaximalism
License: MIT
License-File: LICENSE
Keywords: agent,hermes,keyvault,privacy,tor,vpn
Requires-Python: >=3.11
Requires-Dist: hermes-agent>=0.13.0
Requires-Dist: packaging>=23
Requires-Dist: psutil>=7.2.2
Requires-Dist: ruamel-yaml>=0.18
Provides-Extra: dev
Requires-Dist: mypy==2.1.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff==0.15.13; extra == 'dev'
Provides-Extra: ethereum
Requires-Dist: argon2-cffi>=23; extra == 'ethereum'
Requires-Dist: blake3>=0.4; extra == 'ethereum'
Requires-Dist: cryptography>=42; extra == 'ethereum'
Requires-Dist: eth-account>=0.13; extra == 'ethereum'
Requires-Dist: eth-hash[pycryptodome]>=0.5; extra == 'ethereum'
Requires-Dist: eth-keys>=0.6; extra == 'ethereum'
Requires-Dist: rlp>=4; extra == 'ethereum'
Provides-Extra: extension
Requires-Dist: aiohttp-socks>=0.10; extra == 'extension'
Requires-Dist: aiohttp>=3.9; extra == 'extension'
Requires-Dist: cryptography>=42; extra == 'extension'
Requires-Dist: requests[socks]>=2.32; extra == 'extension'
Requires-Dist: urllib3>=2; extra == 'extension'
Provides-Extra: integration
Requires-Dist: aiohttp-socks>=0.10; extra == 'integration'
Requires-Dist: anthropic>=0.40; extra == 'integration'
Requires-Dist: boto3>=1.34; extra == 'integration'
Requires-Dist: google-genai>=1.20; extra == 'integration'
Requires-Dist: httpx[socks]>=0.27; extra == 'integration'
Requires-Dist: openai>=1.40; extra == 'integration'
Requires-Dist: requests[socks]>=2.32; extra == 'integration'
Provides-Extra: keyvault
Requires-Dist: argon2-cffi>=23; extra == 'keyvault'
Requires-Dist: blake3>=0.4; extra == 'keyvault'
Requires-Dist: cryptography>=42; extra == 'keyvault'
Provides-Extra: macos
Requires-Dist: argon2-cffi>=23; extra == 'macos'
Requires-Dist: blake3>=0.4; extra == 'macos'
Requires-Dist: cryptography>=42; extra == 'macos'
Requires-Dist: pyobjc-framework-quartz>=10.0; extra == 'macos'
Requires-Dist: pyobjc-framework-security>=10.0; extra == 'macos'
Requires-Dist: pyobjc-framework-systemconfiguration>=10.0; extra == 'macos'
Requires-Dist: sqlcipher3-wheels>=0.5.4; extra == 'macos'
Provides-Extra: messaging
Requires-Dist: qrcode>=7.4; extra == 'messaging'
Provides-Extra: telegram
Requires-Dist: aiohttp-socks>=0.10; extra == 'telegram'
Requires-Dist: aiohttp>=3.9; extra == 'telegram'
Requires-Dist: cryptography>=42; extra == 'telegram'
Requires-Dist: python-socks[asyncio]>=2.4; extra == 'telegram'
Requires-Dist: requests[socks]>=2.32; extra == 'telegram'
Requires-Dist: telethon<2,>=1.40; extra == 'telegram'
Requires-Dist: urllib3>=2; extra == 'telegram'
Provides-Extra: tor-control
Requires-Dist: stem<2,>=1.8.0; extra == 'tor-control'
Description-Content-Type: text/markdown

# hermes-mordred

[![Latest release (including pre-releases)](https://img.shields.io/github/v/release/mordredagent/hermes-mordred?include_prereleases&sort=date&label=release&color=orange)](https://github.com/mordredagent/hermes-mordred/releases)
[![PyPI](https://img.shields.io/pypi/v/hermes-mordred)](https://pypi.org/project/hermes-mordred/)
[![CI](https://github.com/mordredagent/hermes-mordred/actions/workflows/ci.yml/badge.svg)](https://github.com/mordredagent/hermes-mordred/actions/workflows/ci.yml)

Privacy-preserving plugins for the
[Hermes agent](https://github.com/NousResearch/hermes-agent): hardware-backed
keys, Tor/VPN routing, local-LLM policy enforcement, encrypted audit data,
end-to-end gateway messages, and macOS-integrated at-rest encryption.

Mordred is a cooperative control layer inside Hermes, not an operating-system
sandbox. See the
[specification](https://github.com/mordredagent/hermes-mordred/blob/main/docs/dev/SPEC.md#threat-model--accepted-limitations)
for the security boundary and accepted limitations.

**Status: active alpha.** See the
[latest alpha release and release notes](https://github.com/mordredagent/hermes-mordred/releases).
New users should start with the
**[Quickstart](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/QUICKSTART.md)**.

## The plugin

The package registers one Hermes plugin, `mordred` (a single
`hermes_agent.plugins` entry point), made of these components:

| Component | Purpose |
|---|---|
| `keyvault` | Secure Enclave / TPM-backed key management and at-rest secrets |
| `llm_guard` | Strict-mode local-LLM enforcement |
| `network` | Tor, VPN, and clearnet path management |
| `privacy_check` | Skill-metadata policy enforcement and audit logging |
| `e2e` | Encrypted Slack and Discord gateway commands and replies |
| `wizard` | The `hermes-mordred` CLI |

Hermes (and Hermes Desktop) lists it as one plugin, `mordred`; enabling or
disabling it turns every component on or off together. Releases up to
0.1.0a20 registered six plugins instead (`mordred_network`,
`mordred_privacy_check`, ...). `hermes-mordred plugins migrate` (also run by
`install.sh`, `configure`, and `upgrade`) replaces those names in
`plugins.enabled` / `plugins.disabled` with `mordred`. The `plugins.mordred_*`
settings sections in `config.yaml` keep their names.

## Requirements

- Python 3.11 or newer and `hermes-agent>=0.13.0`.
- macOS or Linux for the established operator workflows. Scoped native Windows
  implementations exist; general Windows product, Windows 11, and live-device
  acceptance remain incomplete. Mobile support is deferred. See
  [Platform Support](docs/dev/SPEC.md#platform-support-v1).
- Transparent `.env`, configuration, and workspace encryption use macOS
  integrations. Memory uses the macOS file vault, a dedicated Linux TPM-wrapped
  key, or dedicated Windows CNG custody. Linux memory works through `setup`,
  `encryption enable all`, and standalone commands; Private Telegram has its
  dedicated flow. Linux setup/all skip env/config file-vault enrollment. Windows
  support is reported per capability.
- Hermes database encryption (`state.db` and the other SQLite stores) is
  macOS-only and requires the separate `databases encrypt` command after memory
  setup. Linux TPM and Windows CNG memory encryption do not encrypt databases.

## Install (users, from PyPI)

Start with an installed Hermes Agent, then run the Mordred installer:

```sh
curl -fsSL https://raw.githubusercontent.com/mordredagent/hermes-mordred/main/scripts/install.sh | bash
hermes-mordred setup
hermes-mordred status
```

`install.sh` only installs the package; `hermes-mordred setup` is what
configures Mordred and creates keys. It runs `configure`, which enables the
`mordred` plugin. Manual configuration is covered by the
[usage guide](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/USAGE.md#2-first-run-quickstart).
Version pins, optional features, inspect-before-running steps, platform
commands, and expected output are documented in the
[Quickstart](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/QUICKSTART.md).

### Keep it up to date

```sh
hermes-mordred update          # newest release, same extras, Hermes's own packages untouched
hermes-mordred update --check  # only tell me
```

Restart the Hermes gateway (or Hermes Desktop) afterwards. Hermes Desktop
users can also press **Update Mordred** on the Mordred page; a notice appears
there when a newer release is known. Details, refusals and the installer
fallback are in the
[usage guide](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/USAGE.md#upgrade-the-installed-package).

### Use it

Use `hermes-mordred status` for the overall state. On macOS, guided setup also
offers agent-memory protection through `hermes-mordred encryption enable memory`.
To protect conversation databases too, follow the
[database encryption steps](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/QUICKSTART.md#encrypt-conversation-databases-macos).
For native Windows, follow the
[TPM workflow and capability limits](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/USAGE.md#native-windows-tpm-workflow).
The complete command reference and security ceremonies live in the
[usage guide](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/USAGE.md).

Once Hermes 0.19.0+ is configured and the plugins are enabled,
`hermes mordred <command>` exposes the same command tree. On older Hermes
versions, or before the first `configure`, keep using `hermes-mordred`.

### Verify discovery

```sh
hermes-mordred plugins list
```

It shows the `mordred` plugin and whether each component registered. Some
Hermes versions omit package entry points from `hermes plugins list`.

## Documentation

Detailed setup, operations, and troubleshooting are maintained in the dedicated
guides:

| Audience | Guide | Covers |
|---|---|---|
| Users | [Quickstart](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/QUICKSTART.md) | Install and first protected setup |
| Users | [Usage guide](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/USAGE.md) | Commands, ceremonies, troubleshooting, upgrades, removal |
| Users | [Extension guide (preview)](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/EXTENSION.md) | Optional browser extension, E2E messaging, wallet bridge |
| Users | [Telegram guide (preview)](https://github.com/mordredagent/hermes-mordred/blob/main/docs/user/TELEGRAM.md) | Read-only private questions, hardware-sealed credentials, platform limits, Venice/local only |
| Developers | [Development setup](https://github.com/mordredagent/hermes-mordred/blob/main/docs/dev/setup.md) | Editable `.venv`, `HERMES_HOME` isolation, validation |
| Developers | [Development index](https://github.com/mordredagent/hermes-mordred/blob/main/docs/dev/README.md) | Maintained sources of truth |

## License

MIT
