Architecture — Hermes Max

Technical Stack — Layer by Layer

Click any layer to expand/collapse its components. All layers are deployed per-user on isolated JustAVPS VMs. Shared infrastructure (auth, billing, routing) runs on the main Helium platform.

L1 Agent Core +

Hermes Agent

Nous Research open-source Hermes Agent. ReAct loop with tool use, planning, and self-reflection.

LLM Router

Routes to Claude 3.5 Haiku (default), GPT-4o, Gemini 1.5 Flash. User-selectable via /model command.

Tool Registry

65+ built-in tools. Dynamic registration via MCP. Per-user tool enable/disable via settings.

Skill Engine

Auto-creates reusable skills from successful task patterns. FTS5 search for skill retrieval.

L2 Memory & Persistence +

SQLite (FTS5)

Per-user local database on EBS volume. Full-text search across conversations, skills, and memories.

Conversation Store

Persistent message history with context window management. Automatic summarization for long threads.

User Model

Learned preferences, communication style, recurring tasks, and domain expertise profile.

EBS Volume

40GB (Light) / 80GB (Heavy) encrypted EBS volume. Daily snapshots. Portable across VM resizes.

L3 Messaging Layer +

Platform Bots

Central Helium-operated bots for Telegram, Discord, Slack, WhatsApp. One bot per platform, shared across all users.

Message Router

Routes incoming messages to correct user VM via user_id lookup. Redis pub/sub for low-latency delivery.

Streaming Bridge

SSE stream from VM agent → platform message chunking. Handles Telegram 4096-char limit, Discord 2000-char limit.

Web Chat

React-based chat UI at /hermes-max/chat. WebSocket connection to VM agent. Markdown rendering, file upload.

L4 Integrations & Tools +

Composio MCP

MCP bridge for 14 service connections. OAuth token management, refresh, and scoped permissions per service.

Built-in Tools

Web search, code execution (sandboxed), file I/O, HTTP requests, cron scheduler, email, calendar.

Cron Scheduler

APScheduler on VM. User-defined jobs via /cron command or UI. Persistent across VM restarts.

Sandbox Executor

Isolated Python/Node.js execution environment. Resource limits: 512MB RAM, 30s timeout, no network by default.

L5 Infrastructure (JustAVPS) +

VM Provisioning

JustAVPS API: create, resize, snapshot, terminate. <2min provisioning. Automated via Helium control plane.

Proxy Access

Zero open ports. All access via JustAVPS authenticated proxy. Short-lived tokens (6h TTL) auto-renewed.

Health Monitor

Prometheus + Loki on each VM. Heartbeat every 30s. Auto-restart on failure. Alert on 3 consecutive failures.

Update System

Rolling updates via Ansible. Blue/green per-VM. Canary 5% → 25% → 100% rollout with auto-rollback.

L6 Shared Platform (Helium) +

Auth (Cognito)

AWS Cognito + Supabase. Same user_id across Helium and Hermes Max. JWT tokens, refresh rotation.

Billing (Stripe)

Shared Stripe account. Hermes Max as separate product. Webhook-driven VM lifecycle management.

Control Plane API

NestJS service managing VM fleet. Provisioning, health checks, billing sync, user-to-VM mapping.

Fleet Dashboard

Internal admin UI. VM status grid, health metrics, cost tracking, manual intervention tools.

Backend Domain Structure

hermes/provisioning VM lifecycle: create, resize, snapshot, terminate, health-check via JustAVPS API

hermes/messaging Platform bot management, message routing, streaming bridge, webhook handlers

hermes/integrations Composio OAuth flows, MCP tool registration, token refresh, connection status

hermes/billing Stripe subscription management, usage metering, invoice line items, webhook processing

hermes/monitoring Fleet health aggregation, alerting rules, auto-restart triggers, incident logging

hermes/updates Ansible playbook execution, canary rollout management, rollback triggers

API Surface

Endpoint	Method	Auth	Description
`/api/hermes/instance`	`GET`	Bearer	Get current user's VM status, uptime, resource usage
`/api/hermes/subscribe`	`POST`	Bearer	Create subscription + provision VM. Body: {plan: "light"\|"heavy"}
`/api/hermes/chat`	`POST`	Bearer	Send message to agent. Returns SSE stream of response chunks
`/api/hermes/connections`	`GET`	Bearer	List all service connections and their OAuth status
`/api/hermes/connections/:service`	`POST`	Bearer	Initiate OAuth flow for a service. Returns auth_url
`/api/hermes/connections/:service`	`DELETE`	Bearer	Revoke OAuth token and disconnect service
`/api/hermes/cron`	`GET/POST/DELETE`	Bearer	CRUD for scheduled jobs. POST body: {cron, prompt, enabled}
`/api/hermes/settings`	`GET/PATCH`	Bearer	Agent settings: model, personality, tool toggles, memory config
`/api/hermes/usage`	`GET`	Bearer	Token usage, tool calls, uptime for current billing period
`/webhooks/stripe/hermes`	`POST`	Stripe-Sig	Stripe webhook: payment events → VM lifecycle actions
`/webhooks/telegram`	`POST`	Bot-Token	Telegram update webhook → message router
`/webhooks/discord`	`POST`	Discord-Sig	Discord interaction webhook → message router

Database Schema

Two databases: (1) Central PostgreSQL on Helium platform — fleet management, billing, user-to-VM mapping. (2) Per-user SQLite on VM EBS volume — conversations, memory, skills, cron jobs.

hermes_instances Central PostgreSQL · VM fleet registry

Column	Type	Notes
id	UUID	Primary key
user_id	UUID	FK → helium.users.id
plan	ENUM	'light' \| 'heavy'
vm_id	VARCHAR	JustAVPS VM identifier
vm_ip	INET	Internal IP (not exposed)
proxy_token	VARCHAR	Short-lived access token (6h TTL)
status	ENUM	'provisioning' \| 'running' \| 'suspended' \| 'terminated'
stripe_subscription_id	VARCHAR	Stripe subscription reference
created_at	TIMESTAMPTZ	Provisioning timestamp
last_heartbeat	TIMESTAMPTZ	Updated every 30s by health monitor

hermes_connections Central PostgreSQL · OAuth service connections

Column	Type	Notes
id	UUID	Primary key
instance_id	UUID	FK → hermes_instances.id
service	VARCHAR	'google' \| 'notion' \| 'github' \| etc.
access_token	TEXT	Encrypted at rest (AES-256)
refresh_token	TEXT	Encrypted at rest
scopes	TEXT[]	Granted OAuth scopes
expires_at	TIMESTAMPTZ	Token expiry for auto-refresh
connected_at	TIMESTAMPTZ	Initial connection timestamp

conversations Per-user SQLite (VM) · Message history

Column	Type	Notes
id	INTEGER	Auto-increment PK
platform	TEXT	'web' \| 'telegram' \| 'discord' \| 'slack' \| 'whatsapp'
role	TEXT	'user' \| 'assistant' \| 'tool'
content	TEXT	Message content (FTS5 indexed)
tool_calls	JSON	Tool invocations and results
tokens_used	INTEGER	Token count for billing
created_at	INTEGER	Unix timestamp

skills Per-user SQLite (VM) · Learned skill patterns

Column	Type	Notes
id	INTEGER	Auto-increment PK
name	TEXT	Skill identifier (FTS5 indexed)
description	TEXT	What this skill does
steps	JSON	Ordered list of tool calls and prompts
trigger_patterns	TEXT	Regex/keyword patterns that activate this skill
use_count	INTEGER	Times successfully executed
created_at	INTEGER	Unix timestamp