hermes-proton

Hermes Agent runtime + Proton product suite integration — skills, plugins, and MCP tools for Proton Mail, Drive, Pass, VPN, Calendar.

Project Seed

This is a prototype project exploring how to integrate the Hermes Agent runtime (nousresearch/hermes) with Proton's product suite (Mail, Drive, Pass, VPN, Calendar, Wallet) to give agents native access to Proton services.

Goal: Enable any Hermes-based agent to read/send email, manage passwords, store/retrieve files, and control VPN — all through the agent's natural tool-use interface.

---

Research Summary

Key Finding: Proton Has No Public REST API

Proton does not publish a public developer API. All APIs are internal — used by Proton's own clients (web, desktop, mobile, Bridge). The API surface has been reverse-engineered from open-source clients. Authentication uses SRP-6a (not OAuth2), and all products share the same session via login.proton.me.

Available Official Libraries

Library	Lang	Purpose	Status
go-proton-api	Go	REST client (Mail, Drive, Calendar, Contacts)	Active — primary SDK
gopenpgp	Go	OpenPGP crypto library (X25519, RSA)	Active
proton-python-client	Python	Python client	Abandoned (2021)
proton-bridge	Go	Local IMAP/SMTP/gRPC daemon for Mail	Active
protonmail-bridge (CLI)	Go	Headless Bridge (-c flag)	Active
pass-cli	Rust	Official Pass CLI with JSON output	Active
proton-vpn-cli	Python	Official Linux VPN CLI	Active
Drive SDK	TS/C#/Kt	Preview SDK for Drive	Preview
go-crypto	Go	Proton's fork of Go crypto	Active

Key Third-Party Projects

Project	Lang	What	Stars	Notes
openclaw-protonmail-skill	TS	OpenClaw skill for Mail via Bridge	16	Directly relevant — Hermes skill analogue
hydroxide (emersion)	Go	Third-party Bridge (CardDAV/IMAP/SMTP)	2.1k	SRP auth, no official Bridge needed
rclone protondrive	Go	Drive as rclone backend	(57k)	Most-used third-party Drive client
proton-webdav-bridge	Go	Drive as WebDAV	28	Daemon pattern for agent integration
proton-cli (roman-16)	Go	Multi-product CLI (Mail, Drive, Calendar)	17	New, comprehensive
pm-cli (bscott)	Go	CLI via Bridge, --json everywhere	14	Agent-friendly design pattern
proton-tui (cdump)	Rust	Terminal UI for VPN	~50	Rust VPN auth flow reference

Per-Product Integration Paths

Product	Recommended Path	Maturity
Mail	Proton Bridge → local IMAP/SMTP	Proven
Pass	Official pass-cli → subprocess	Mature
Drive	rclone protondrive backend or Drive SDK	Beta
VPN	Official proton-vpn-cli → subprocess	Mature
Calendar	go-proton-api (has calendar endpoints)	Exploratory
Wallet	No API exists yet	None

---

Proposed Architecture

Hybrid Multi-Layer Integration

┌────────────────────────────────────────────────────────────┐
│                    HERMES AGENT                            │
│  (DeepSeek/Claude/etc. via Hermes runtime)                 │
├────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │         KOMODO PLUGIN: hermes-proton                 │  │
│  │  (Hermes plugin — manages auth, session, config)      │  │
│  │                                                       │  │
│  │  Auth Layer: SRP-6a session management               │  │
│  │  Token cache, refresh, re-auth                       │  │
│  └──────────┬──────────────────────────────┬────────────┘  │
│             │                              │                │
│     ┌───────┴────────┐          ┌──────────┴────────────┐  │
│     │  HERMES SKILLS  │          │   MCP TOOLS (opt.)    │  │
│     │                 │          │                       │  │
│     │ proton-mail     │          │ proton-mail-read      │  │
│     │ proton-pass     │          │ proton-drive-sync     │  │
│     │ proton-drive    │          │ proton-vpn-connect    │  │
│     │ proton-vpn      │          └───────────────────────┘  │
│     └────────┬───────┘                                      │
│              │                                              │
└──────────────┼──────────────────────────────────────────────┘
               │
    ┌──────────┴──────────┬──────────┬──────────────┬──────┐
    ▼                     ▼          ▼              ▼
┌──────────┐  ┌─────────────┐  ┌──────────┐  ┌──────────┐
│ Proton   │  │ Proton Pass  │  │ Proton   │  │ Proton   │
│ Bridge   │  │ CLI (rust)   │  │ Drive    │  │ VPN CLI  │
│ (IMAP/   │  │ subprocess   │  │ rclone/  │  │ (python) │
│  SMTP)   │  │              │  │ SDK      │  │          │
└──────────┘  └─────────────┘  └──────────┘  └──────────┘

Why This Architecture

1. Bridge for Mail — Proven by openclaw-protonmail-skill. Bridge handles all OpenPGP encryption transparently. Mail becomes standard IMAP/SMTP. No crypto complexity.

2. pass-cli for Pass — Official Proton CLI with --json output, mature (v2.1.2), modular Rust crates. Subprocess calls map directly to Hermes tools. No auth management needed — pass-cli handles its own session.

3. rclone/Drive SDK for Drive — Two options:

   • rclone protondrive backend — Battle-tested (rclone's most-used third-party backend). Shell out like pass-cli.
   • Drive SDK (TypeScript) — Newer, more direct, but preview stage with breaking crypto changes coming.

4. VPN CLI for VPN — Official protonvpn-cli or proton-tui. Subprocess to connect/disconnect/status.

5. Komodo Plugin as Container — A Hermes plugin (komodo plugin) owns the shared auth session, credential management, and lifecycle. Skills underneath are product-specific tool collections.

6. MCP Tools as Alternative — Each product feature could also be exposed as an MCP (Model Context Protocol) tool for environments that use MCP over skills.

Auth Strategy

Proton uses SRP-6a across all products. One login covers all products under the same account.

Option A: Plugin-managed auth

• Plugin handles SRP login once → stores encrypted tokens
• All skills share the same session via plugin state
• Token refresh handled by plugin

Option B: Per-tool auth

• Each skill/tool handles auth independently
• Simpler for isolated skills, redundant for multi-product workflows

Recommended: Option A — One login, shared session, plugin manages token lifecycle.

---

Implementation Phases

Phase 1: Foundation (this seed)

• Research complete ✓
• Project scaffold (this repo)
• Architecture design
• Kanban board seeded

Phase 2: Mail skill

• Proton Bridge install and configure
• Hermes skill: proton-mail (list, read, search, send, reply)
• IMAP + SMTP via node-imap/nodemailer or Python imaplib/smtplib

Phase 3: Pass skill

• proton-pass-cli install
• Hermes skill: proton-pass (list vaults, get secrets, inject env vars)
• SSH agent support

Phase 4: Drive skill

• rclone + protondrive backend config
• OR Drive SDK integration
• Hermes skill: proton-drive (list, read, upload, search)

Phase 5: VPN skill

• proton-vpn-cli install
• Hermes skill: proton-vpn (connect, disconnect, status, server list)

Phase 6: Auth plugin

• Komodo plugin: hermes-proton-auth
• SRP-6a login flow
• Encrypted token storage
• Token refresh lifecycle
• Shared session for all skills

---

Integration Vehicles (Hermes)

The project should explore all three Hermes extension mechanisms for comparison:

1. Hermes Skill — For self-contained tool collections (proton-mail skill, proton-pass skill). Best for most use cases. Skills are the primary extension mechanism.

2. Hermes Komodo Plugin — For shared state, auth lifecycle, and cross-product coordination. A plugin can provide auth services that skills consume.

3. MCP Tool — For environments that use MCP protocol. Each Proton product as an MCP server exposing tools. Good for cross-platform compatibility.

---

Related Projects

• rvacyber/openclaw-protonmail-skill — OpenClaw skill for Proton Mail via Bridge
• emersion/hydroxide — Third-party ProtonMail bridge (SRP auth, no official Bridge)
• henrybear327/Proton-API-Bridge — Drive encryption bridge (archived Feb 2026)
• rclone/rclone — protondrive backend (active)
• bscott/pm-cli — Agent-friendly CLI via Bridge with --json output
• roman-16/proton-cli — Multi-product Go CLI (May 2026)

---

License

MIT — Trentuna imprint