System Architecture

                            ┌─────────────────────────────────────────────┐
                            │               GOOGLE WORKSPACE               │
                            │  (alice@co.com, bob@co.com, ... x25)         │
                            │         ┌───────────────────┐                │
                            │         │  Google Chat Bot  │                │
                            │         │  "Hermes Team"    │                │
                            │         └────────┬──────────┘                │
                            └──────────────────┼───────────────────────────┘
                                               │ Cloud Pub/Sub
                                               ▼
  ┌─────────────────────────────────────────────────────────────────────────────────┐
  │                           GCP COMPUTE ENGINE (1 VM)                              │
  │                                                                                  │
  │  ┌──────────────────────────────────────────────────────────────────────────┐   │
  │  │                     PORTAINER (DOCKER MANAGEMENT)                         │   │
  │  │                      Port 9443 (web UI)                                   │   │
  │  └──────────────────────────────────────────────────────────────────────────┘   │
  │                                                                                  │
  │  ┌──────────────────────────────────────────────────────────────────────────┐   │
  │  │                      DOCKER COMPOSE STACK                                 │   │
  │  │                                                                           │   │
  │  │  ┌──────────────────────────────────────────────────────────────────┐    │   │
  │  │  │  CONTAINER 1: HERMES GATEWAY (multiplex mode)                    │    │   │
  │  │  │  ┌───────────────────────────────────────────────────────────┐  │    │   │
  │  │  │  │  GATEWAY PROCESS (1)                                        │  │    │   │
  │  │  │  │  ├── Google Chat adapter (Pub/Sub → events)                 │  │    │   │
  │  │  │  │  ├── Profile Router (email → profile mapping)              │  │    │   │
  │  │  │  │  └── Session Dispatch (per-profile agent loop)              │  │    │   │
  │  │  │  │                                                             │  │    │   │
  │  │  │  │  PROFILES:                                                  │  │    │   │
  │  │  │  │  ├── alice  → HERMES_HOME=/profiles/alice                  │  │    │   │
  │  │  │  │  │            Model: bedrock/us.anthropic.claude-sonnet-4    │  │    │   │
  │  │  │  │  │            Tirith: /workspaces/alice/**                  │  │    │   │
  │  │  │  │  │            Honcho peer: alice                            │  │    │   │
  │  │  │  │  │            Google OAuth: alice@co.com token              │  │    │   │
  │  │  │  │  │                                                          │  │    │   │
  │  │  │  │  ├── bob    → HERMES_HOME=/profiles/bob                    │  │    │   │
  │  │  │  │  ├── carol  → HERMES_HOME=/profiles/carol                  │  │    │   │
  │  │  │  │  └── ... x25                                                │  │    │   │
  │  │  │  └───────────────────────────────────────────────────────────┘  │    │   │
  │  │  └──────────────────────────────────────────────────────────────────┘    │   │
  │  │                                                                           │   │
  │  │  ┌────────────────────────┐  ┌──────────────────────┐  ┌──────────────┐  │   │
  │  │  │  CONTAINER 2: HONCHO   │  │  CONTAINER 3:        │  │  CONTAINER 4:│  │   │
  │  │  │  API (port 8000)       │  │  PostgreSQL + pgvector│  │  Redis Cache │  │   │
  │  │  └────────────────────────┘  └──────────────────────┘  └──────────────┘  │   │
  │  └──────────────────────────────────────────────────────────────────────────┘   │
  │                                                                                  │
  │  VOLUMES:                                                                       │
  │  ├── profiles/alice/  → Alice's HERMES_HOME (config, memory, skills, secrets)   │
  │  ├── profiles/bob/    → Bob's HERMES_HOME                                        │
  │  ├── profiles/...     → 23 more                                                  │
  │  ├── workspaces/      → Per-user project dirs (Tirith-scoped)                    │
  │  ├── shared/          → Team-wide read-only assets                               │
  │  └── honcho-db/       → PostgreSQL data volume                                    │
  └─────────────────────────────────────────────────────────────────────────────────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          │                          │
                    ▼                          ▼                          ▼
  ┌─────────────────────────┐  ┌──────────────────────────┐  ┌──────────────────────────┐
  │     AWS BEDROCK         │  │      GOOGLE DRIVE        │  │    HONCHO WORKSPACE       │
  │  (Claude, Nova, Llama)   │  │  (Team docs + per-user)  │  │  (Shared team context)    │
  │  IAM auth via AWS SDK   │  │  OAuth2 per-user tokens   │  │  + Per-peer private mem   │
  └─────────────────────────┘  └──────────────────────────┘  └──────────────────────────┘

Request Flow (Alice sends a message)

Key Design Decisions

Data Flow, Permissions & Routing

This diagram tracks every data type through the system — where it enters, where it's stored, who can access it, and how it's authenticated at each hop.

  ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
  │                                                                                                  │
  │                            DATA FLOW MAP — where chats, docs, and memories go                    │
  │                                                                                                  │
  └──────────────────────────────────────────────────────────────────────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐                       ┌─────────────────────┐
        │              │              │                       │                     │
        ▼              ▼              ▼                       ▼                     ▼
  ┌──────────┐  ┌──────────┐  ┌──────────┐            ┌──────────────┐   ┌──────────────┐
  │  CHATS   │  │   DOCS   │  │ MEMORIES │            │  AWS BEDROCK  │   │ GOOGLE DRIVE │
  │          │  │          │  │          │            │  (LLM infra)  │   │ (file store)  │
  └─────┬────┘  └─────┬────┘  └─────┬────┘            └──────┬───────┘   └──────┬───────┘
        │              │              │                       │                  │
        ▼              │              │                       │                  │
  ┌─────────────┐      │              │          ┌────────────┴────┐   ┌─────────┴────────┐
  │ Google Chat │      │              │          │  IAM role on   │   │  Per-user OAuth  │
  │ API → Pub/Sub      │              │          │  GCP VM        │   │  token per email │
  │ (SA auth)   │      │              │          └─────────────────┘   └──────────────────┘
  └──────┬──────┘      │              │
         │             │              │
         ▼             │              │
  ┌────────────────────────────────────────────────────────────────────────────┐
  │  HERMES GATEWAY (multiplex, single process)                                 │
  │                                                                             │
  │  1. Google Chat adapter pulls event from Pub/Sub                           │
  │     Auth: SA key JSON (mounted file)                                        │
  │                                                                             │
  │  2. Profile router: pre_gateway_dispatch hook                               │
  │     Maps user email → profile name                                          │
  │     Auth: Google Workspace identity (verified by Chat API)                   │
  │                                                                             │
  │  3. Session dispatch: creates isolated session per profile                  │
  │     Session key: agent:{profile}:google_chat:{dm|space}:{id}                │
  │     Auth: session key → namespaced DB                                       │
  └────────────────────────────────┬───────────────────────────────────────────┘
                                   │
          ┌────────────────────────┼────────────────────────┐
          │                        │                        │
          ▼                        ▼                        ▼
  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
  │  ALICE profile    │  │  BOB profile     │  │  23 more...      │
  │  HERMES_HOME:     │  │  HERMES_HOME:    │  │                  │
  │  /profiles/alice/ │  │  /profiles/bob/  │  │                  │
  └────────┬─────────┘  └────────┬─────────┘  └──────────────────┘
           │                      │
           │        ┌─────────────┼──────────────────────────────────────────┐
           │        │             │                                          │
           ▼        ▼             ▼                                          │
  ┌──────────────────────────────────────────────────────┐                    │
  │              AGENT LOOP (per profile)                 │                    │
  │                                                       │                   │
  │  ┌──────────────┐    ┌──────────────┐                 │                   │
  │  │ CHAT FLOW    │    │ FILE FLOW    │                 │                   │
  │  │              │    │              │                 │                   │
  │  │ User msg →   │    │ User asks    │                 │                   │
  │  │ SOUL.md →    │    │ about doc →  │                 │                   │
  │  │ model →      │    │ Drive API →  │                 │                   │
  │  │ tool exec →  │    │ OAuth token  │                 │                   │
  │  │ response     │    │ → file data  │                 │                   │
  │  └──────┬───────┘    └──────┬───────┘                 │                   │
  │         │                   │                          │                   │
  │         ▼                   ▼                          │                   │
  │  ┌──────────────────────────────────┐                  │                   │
  │  │ MEMORY FLOW                      │                  │                   │
  │  │                                  │                  │                   │
  │  │ Agent reasons → Honcho API       │                  │                   │
  │  │ → Workspace (team) or peer(user) │                  │                   │
  │  │ → pgvector semantic search      │                  │                   │
  │  │ → Auto-extract via Deriver       │                  │                   │
  │  └──────────────────────────────────┘                  │                   │
  │                                                       │                   │
  │  PERMISSION CHECKS (every tool call):                  │                   │
  │  ├── Tirith: file paths against profile allowlist      │                   │
  │  ├── Honcho: workspace vs peer isolation               │                   │
  │  ├── Drive: OAuth token → file-level access            │                   │
  │  └── Bedrock: IAM role → model invoke permissions      │                   │
  └──────────────────────────────────────────────────────┘                   │
                                                                             │
           ┌─────────────────────────────────────────────────────────────────┘
           ▼
  ┌──────────────────────────────────────────────────────────────────────┐
  │  HONCHO MEMORY (PostgreSQL + pgvector)                               │
  │                                                                       │
  │  ┌──────────────────────────────┐   ┌──────────────────────────────┐  │
  │  │  WORKSPACE: "team"           │   │  PEER: "alice" (private)     │  │
  │  │                              │   │                              │  │
  │  │  What goes in:               │   │  What goes in:               │  │
  │  │  • Team deadlines, status    │   │  • Alice's preferences       │  │
  │  │  • Shared space debates      │   │  • Alice's project notes    │  │
  │  │  • Decisions & reasoning     │   │  • Alice's Drive index       │  │
  │  │  • Cross-user knowledge      │   │  • Alice's session history   │  │
  │  │                              │   │                              │  │
  │  │  Who can read: ALL profiles  │   │  Who can read: Alice only    │  │
  │  │  Who can write: Deriver +    │   │  Who can write: Deriver +    │  │
  │  │    any profile agent         │   │    Alice's agent only        │  │
  │  └──────────────────────────────┘   └──────────────────────────────┘  │
  │                                                                       │
  │  DERIVER (background):                                                 │
  │  Reads every conversation → extracts facts → classifies as            │
  │  team (→ workspace) or personal (→ peer) → generates embeddings       │
  │  → runs dream consolidation (dedup, link, summarize)                  │
  │  Auth: internal Honcho API key                                        │
  └──────────────────────────────────────────────────────────────────────┘

Data Flow Summary by Type

Permission Boundaries

  CAN ALICE ACCESS BOB'S...
  ┌──────────────────────────────┬───────┬───────┐
  │ Resource                      │ Alice │ Bob   │
  ├──────────────────────────────┼───────┼───────┤
  │ Bob's DMs with the bot        │  ❌   │  ✅   │  (session isolation)
  │ Bob's Drive files             │  ❌   │  ✅   │  (OAuth scope: drive.file)
  │ Bob's Honcho private peer     │  ❌   │  ✅   │  (Honcho peer isolation)
  │ Bob's profile configs         │  ❌   │  ✅   │  (Tirith path allowlist)
  │ Bob's workspace files         │  ❌   │  ✅   │  (Tirith path allowlist)
  │ Shared team memory            │  ✅   │  ✅   │  (Honcho workspace peer)
  │ Shared skills directory       │  ✅   │  ✅   │  (read-only volume mount)
  │ AWS Bedrock (LLM)             │  ✅   │  ✅   │  (shared IAM role)
  │ Google Chat bot connection    │  ✅   │  ✅   │  (shared SA key)
  │ Deployer config (Docker, Caddy)│  ❌   │  ❌   │  (deployer profile only)
  └──────────────────────────────┴───────┴───────┘

Data Boundaries & Privacy

A critical architectural property: what data leaves your infrastructure vs what stays entirely within your GCP VM. Every external API call should be justified and bounded.

Self-Hosted Data (Stays on VM)

Data Shared with External Providers

Opting Out of Bedrock Data Retention

By default, AWS retains Bedrock inputs and outputs for up to 30 days for abuse detection. To opt out entirely:

Pros, Cons & Roadmap

Every architectural decision has tradeoffs. This page lays out what the system does well, where it falls short, and what comes next. Use it to decide whether this architecture fits your team and to plan your investment in future improvements.

Roadmap & Future Work

Items ordered by impact. The top three are recommended before scaling beyond 25 users:

Decision Framework

Hermes Multiplex Gateway

The Hermes multiplex gateway is the architectural centerpiece. It runs as a single process that serves all 25 profiles, each with isolated HERMES_HOME, credentials, memory, and session state.

How Multiplex Works

  ONE GATEWAY PROCESS
  ┌─────────────────────────────────────────────────────────────────────┐
  │                                                                     │
  │  GOOGLE CHAT ADAPTER (1 connection, 1 bot token)                    │
  │  Cloud Pub/Sub pull → inbound events                                │
  │                                                                     │
  │         │                                                           │
  │         ▼                                                           │
  │  PROFILE ROUTER                                                     │
  │  ┌──────────────────────────────────────────────────────────────┐   │
  │  │  pre_gateway_dispatch hook:                                   │   │
  │  │  event.source.email → EMAIL_TO_PROFILE[alice@co.com] = alice  │   │
  │  │  stamps source.profile = "alice"                              │   │
  │  └──────────────────────────────────────────────────────────────┘   │
  │         │                                                           │
  │         ▼                                                           │
  │  SESSION DISPATCH                                                   │
  │  ┌──────────────────────────────────────────────────────────────┐   │
  │  │  Session key: agent:alice:google_chat:dm:users/123456789     │   │
  │  │  Isolated from: agent:bob:google_chat:dm:users/987654321     │   │
  │  │  Isolated from: agent:carol:google_chat:dm:users/555666777   │   │
  │  └──────────────────────────────────────────────────────────────┘   │
  │         │                                                           │
  │         ▼                                                           │
  │  PER-PROFILE CONTEXT LOADER                                         │
  │  ┌──────────────────────────────────────────────────────────────┐   │
  │  │  source.profile = "alice" →                                   │   │
  │  │  HERMES_HOME = /home/hermes/profiles/alice/                   │   │
  │  │  Loads: config.yaml, MEMORY.md, USER.md, skills/*,            │   │
  │  │         Honcho peer context, AWS credentials (per-profile)    │   │
  │  └──────────────────────────────────────────────────────────────┘   │
  │         │                                                           │
  │         ▼                                                           │
  │  AGENT LOOP (runs in profile context)                               │
  │  ├── Tirith checks every file tool call against profile allowlist   │
  │  ├── Honcho API call uses profile's peer for memory read/write      │
  │  ├── Bedrock API call uses profile's (or shared) AWS credentials    │
  │  └── Google Drive API call uses profile's OAuth token               │
  │                                                                     │
  └─────────────────────────────────────────────────────────────────────┘

Configuration

# docker-compose.yml (Hermes container)
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    environment:
      - PROFILE=default
      - GATEWAY_MULTIPLEX_PROFILES=true          # Enable multiplex mode
      - AWS_PROFILE=hermes                       # Bedrock IAM profile
    volumes:
      - ./profiles:/home/hermes/profiles         # 25 profile dirs
      - ./workspaces:/home/hermes/workspaces     # Per-user project dirs
      - ./shared:/home/hermes/shared:ro          # Team-wide assets
    ports:
      - 9292:9292

# profiles/alice/config.yaml (per-profile)
model:
  provider: bedrock
  default: us.anthropic.claude-sonnet-4-6

terminal:
  backend: local
  cwd: /home/hermes/workspaces/alice
  tirith:
    fail_open: false
    allowed_paths:
      - /home/hermes/workspaces/alice/**
      - /home/hermes/shared/**

memory:
  provider: honcho

skills:
  external_dirs:
    - /home/hermes/shared/skills/      # Team skills (read-only)

Profile Routing Hook

# plugins/hooks/google_chat_user_mapper.py
"""Maps Google Chat user emails to Hermes profiles."""
import os

EMAIL_TO_PROFILE = {
    'alice@company.com': 'alice',
    'bob@company.com': 'bob',
    'carol@company.com': 'carol',
    # ... 25 entries
}

def pre_gateway_dispatch(event):
    if event.platform != 'google_chat':
        return event
    email = getattr(event.source, 'email', None)
    if email and email in EMAIL_TO_PROFILE:
        event.source.profile = EMAIL_TO_PROFILE[email]
    return event

Tirith Isolation

Tirith enforces per-profile filesystem access at the tool level. When Alice's agent calls terminal, read_file, write_file, or search_files, Tirith checks the path against the profile's allowlist before executing. Any path outside /workspaces/alice/** or /shared/** is blocked.

Google Chat Integration

Google Chat is the user-facing interface. Each team member interacts with a single bot — "Hermes Team" — through Google Chat DMs or shared spaces. The integration uses Cloud Pub/Sub pull subscriptions, meaning the Hermes gateway does not need a public URL, tunnel, or TLS certificate.

Architecture

  USER (Alice)
  │
  ├── Google Chat DM: "@Hermes Team summarize my Drive"
  │
  ▼
  ┌──────────────────────────────────────────────────┐
  │  GOOGLE CHAT API                                 │
  │  Publishes event to Cloud Pub/Sub topic          │
  │  projects/hermes-chat/topics/hermes-events       │
  └──────────────────────────────────────────────────┘
  │
  ▼
  ┌──────────────────────────────────────────────────┐
  │  PUB/SUB PULL SUBSCRIPTION                       │
  │  projects/hermes-chat/subscriptions/hermes-sub   │
  │  Service Account: hermes-chat-sa@...             │
  │  Roles: Pub/Sub Subscriber + Viewer              │
  └──────────────────────────────────────────────────┘
  │
  ▼
  ┌──────────────────────────────────────────────────┐
  │  HERMES GOOGLE CHAT ADAPTER                      │
  │  (inside Hermes gateway container)                │
  │  Polls subscription every 100ms                  │
  │  Parses event → SessionSource                    │
  │  Routes to profile via email mapper              │
  └──────────────────────────────────────────────────┘

  OUTBOUND:
  Agent replies via Chat REST API
  POST https://chat.googleapis.com/v1/spaces/{space}/messages
  Uses same Service Account (acts as the bot)

Setup Summary

Message Behavior

Team Deployment with Multiplex

With GATEWAY_MULTIPLEX_PROFILES=true, a single Google Chat bot serves all 25 team members — each routed to their own profile with isolated memory, session, and credentials. From the user's perspective, it's just a bot in their chat; the routing is invisible.

How Users Interact

What Users Experience

Routing Flow (End to End)

  User sends message in Google Chat
         │
         ▼
  Cloud Pub/Sub → Google Chat adapter
         │
         ▼
  pre_gateway_dispatch hook:
  Checks event.source.email
  ┌──────────────────────────────────────┐
  │  EMAIL_TO_PROFILE = {                │
  │    'alice@co.com': 'alice',          │
  │    'bob@co.com': 'bob',             │
  │    'carol@co.com': 'carol'          │
  │  }                                    │
  │  event.source.profile = matched name  │
  └──────────────────────────────────────┘
         │
         ▼
  Profile scope activates:
  ├── HERMES_HOME = /home/hermes/profiles/alice/
  ├── Session: agent:alice:google_chat:dm:...
  ├── Memory: Honcho workspace + peer alice
  ├── Config: model, Tirith rules, SOUL.md
  └── (Future) Google Drive OAuth token resolved by email
         │
         ▼
  Agent processes → reply via Chat REST API
  POST https://chat.googleapis.com/v1/spaces/{space}/messages

SOUL.md Template for Team Bots

## Google Chat Team Etiquette
- You serve 25 team members. Each has their own private profile.
- In DMs: full agent behavior. You have access to the user's
  private memory, their Drive files, and shared team context.
- In shared spaces: your replies are visible to everyone.
  If a question involves personal data, tell the user:
  "This involves your personal data — could you DM me instead?"
- You CANNOT delete files in Google Drive. Refuse politely.
- You can create new documents in Drive when asked.
- You can share information from team context (Honcho workspace)
  publicly in shared spaces.
- When in doubt about privacy, ask the user to DM you.

Honcho Memory Provider

Honcho is the most important component for team deployment. It's what turns 25 isolated agent profiles into a team that learns collectively. Without it, each user's bot starts fresh every session — no shared context, no cross-user learning, no team knowledge growth.

Why Honcho — Not File-Based Memory

Standard Hermes memory (MEMORY.md, USER.md) and static knowledge stores like Obsidian vaults or plain markdown files can't support a team of 25 users. Here's why Honcho is necessary:

Architecture — Workspace + Peers

  ┌─────────────────────────────────────────────────────────────────────┐
  │                      HONCHO (Container:8000)                        │
  │                                                                     │
  │  WORKSPACE: "hermes-team"                                           │
  │  ┌──────────────────────────────────────────────────────────────┐  │
  │  │  USER PEER: "team"                                           │  │
  │  │  ├── Repository of team-shared facts                          │  │
  │  │  ├── Session summaries from shared spaces                     │  │
  │  │  ├── Team decisions, project status, deadlines                │  │
  │  │  └── Visible to ALL profiles                                  │  │
  │  │                                                               │  │
  │  │  AI PEERS (one per profile):                                  │  │
  │  │  ├── "alice" → Alice's private observations                   │  │
  │  │  │             Her preferences, her project notes,            │  │
  │  │  │             her Google Drive file indices                  │  │
  │  │  ├── "bob"   → Bob's private observations                     │  │
  │  │  └── ... x25                                                  │  │
  │  └──────────────────────────────────────────────────────────────┘  │
  │                                                                     │
  │  DATABASE: PostgreSQL + pgvector                                    │
  │  └──────────────────────────────────────────────────────────────────┘  │
  │                                                                     │
  │  DERIVER (background worker)                                        │
  │  Extracts observations from messages, builds peer representations,  │
  │  generates session summaries, runs dream consolidation              │
  └─────────────────────────────────────────────────────────────────────┘

Configuration

# honcho.json (shared across all profiles via mount)
{
  "baseUrl": "http://honcho:8000",
  "hosts": {
    "hermes": {
      "enabled": true,
      "workspace": "hermes-team",
      "peerName": "team",
      "aiPeer": "hermes",              # Default AI peer
      "recallMode": "hybrid",          # Auto-inject + tools
      "writeFrequency": "async",       # Background writes
      "observationMode": "directional"
    }
  }
}

Each profile references the same honcho.json but Hermes auto-creates a per-profile AI peer (hermes.alice, hermes.bob, etc.) via the --clone pattern during profile creation.

What Gets Stored Where

What This Means For Your Team

Self-Hosted Honcho Stack

services:
  honcho-db:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: honcho
      POSTGRES_PASSWORD: ${HONCHO_DB_PASSWORD}
      POSTGRES_DB: honcho
    volumes:
      - honcho-db:/var/lib/postgresql/data

  honcho-redis:
    image: redis:7-alpine
    volumes:
      - honcho-redis:/data

  honcho-api:
    build: https://github.com/plastic-labs/honcho.git
    depends_on: [honcho-db, honcho-redis]
    environment:
      DB_CONNECTION_URI: postgresql+psycopg://honcho:...
      CACHE_URL: redis://honcho-redis:6379/0
      AUTH_USE_AUTH: "false"
      LLM_OPENAI_API_KEY: ${OPENAI_API_KEY}

AWS Bedrock LLM Provider

All 25 Hermes profiles route their LLM calls through a single AWS Bedrock provider. Hermes supports Bedrock natively via the Converse API — not the OpenAI-compatible endpoint. This gives you full access to IAM authentication, Guardrails, cross-region inference profiles, and all foundation models.

How Auth Works

Configuration

# Hermes config.yaml (global or per-profile)
model:
  provider: bedrock
  default: us.anthropic.claude-3-5-haiku
  # See the full model catalog below for model IDs and pricing

Bedrock Model Catalog — Complete

Every model available on Bedrock as of July 2026, organized by provider. This is the full list from the Bedrock "Models at a glance" page. Prices are per 1M tokens, on-demand Standard tier, US regions.

Your Current Models vs Bedrock

Your team currently runs these models via the opencode-go provider (OpenRouter). Here is exactly how each maps to Bedrock:

Model Selection Guide by Use Case

Cost Estimates for 25 Users (Updated)

Using the recommended model stack above with Haiku as default and selective upgrades:

Security

With Bedrock's IAM auth, there are no API keys to issue or rotate. The VM's IAM role defines what models can be invoked. If the VM is compromised, the IAM role is the blast radius — not individual API keys. Bedrock also supports cross-region inference profiles for automatic failover and load balancing.

Google Drive Integration

Team files live in Google Drive. The architecture supports two access patterns: per-user OAuth tokens for private file access, and a shared service account for team-wide document retrieval.

  GOOGLE DRIVE ACCESS MODEL
  ┌─────────────────────────────────────────────────────────────────────┐
  │                                                                     │
  │  PER-USER ACCESS (via OAuth)                                        │
  │  ┌─────────────────────────────────────────────────────────────┐    │
  │  │  Alice's agent → Alice's OAuth token → Alice's Google Drive  │    │
  │  │  Bob's agent   → Bob's OAuth token   → Bob's Google Drive    │    │
  │  └─────────────────────────────────────────────────────────────┘    │
  │                                                                     │
  │  Access granted when:                                                │
  │  1. User runs /setup-google-drive in their DM                       │
  │  2. Browser OAuth consent flow completes                             │
  │  3. Token stored at ~/.hermes/google_tokens/alice@co.com.json       │
  │  4. Token auto-refreshes, never expires                             │
  │                                                                     │
  │  ──────────────────────────────────────────────────────────────     │
  │                                                                     │
  │  SHARED TEAM ACCESS (via Workspace Service Account)                 │
  │  ┌─────────────────────────────────────────────────────────────┐    │
  │  │  Any profile's agent → Drive SA token → Team Drive/shared    │    │
  │  │  docs folder                                                  │    │
  │  └─────────────────────────────────────────────────────────────┘    │
  │                                                                     │
  │  Service Account has domain-wide delegation authority:              │
  │  - Can access any doc in the team Drive                             │
  │  - Configured via Google Workspace Admin Console                    │
  │  - No per-user consent needed for team docs                         │
  │                                                                     │
  └─────────────────────────────────────────────────────────────────────┘

Setup Sequence

Multi-Account Token Storage

The Google Workspace skill stores tokens at ~/.hermes/google_tokens/<email>.json. The multiplex profile router sets GOOGLE_CHAT_USER_EMAIL as an env var per-turn, which the Google API tooling reads to select the correct token. If no per-user token exists, it falls back to the team service account.

Drive Security: Preventing Accidental Deletion

Google OAuth scopes do not differentiate between create and delete — a token with drive.file or drive scope can delete any file it can access. Three layers of defense prevent accidental document loss:

Layer 1: OAuth Scope Selection

Recommended setup:

• Team Drive (shared): Service Account with drive.readonly — agent can search and read team docs but cannot touch them
• Per-user Drive: User OAuth with drive.file — agent can create and edit files it made, but cannot see or delete existing user files

# In Hermes Google Workspace setup or google_api.py
SCOPES = {
    "team": ["https://www.googleapis.com/auth/drive.readonly"],           # team SA
    "user": ["https://www.googleapis.com/auth/drive.file"]               # per-user OAuth
}

drive.file confines the agent to files it explicitly created or was granted access to. Your existing 5-year-old project spreadsheets are invisible to it. If the agent deletes a draft it made, Drive's 30-day trash provides recovery.

Layer 2: Tool-Level Deletion Stripping

Modify the Hermes Google Workspace skill to remove delete functionality entirely — the agent literally cannot call delete because the tool doesn't exist in its toolset:

# google_api.py — strip all destructive commands
COMMANDS = {
    'search': _drive_search,
    'get': _drive_get,
    # 'delete': _drive_delete,       ← REMOVED
    # 'trash': _drive_trash,         ← REMOVED
    # 'update': _drive_update,       ← REMOVED (optional — keeps edits)
    'create': _drive_create,         # keep if you want doc generation
}

Layer 3: Prompt Hardening

Each profile's SOUL.md includes a non-deletion directive as a behavioral guardrail:

## Google Drive Rules
- You have RESTRICTED access to Google Drive.
- You CANNOT delete, trash, or remove any file.
- You CAN create new files when explicitly asked.
- If a user asks you to delete a file, refuse politely.
- If a user asks you to "clean up" or "remove old files," do not interpret this as delete.
  Instead, state that you cannot perform destructive operations.

Defense in Depth Flow

  User: "delete that spreadsheet"
         │
         ▼
  SOUL.md: "Cannot delete files"           ← Prompt guardrail
         │
         ▼
  Agent looks for delete tool               ← Tool doesn't exist
         │
         ▼
  Google API checks OAuth scope             ← drive.file or readonly
         │
    ┌────┴────┐
    │         │
  readonly  drive.file
    │         │
  403       Checks: did this app CREATE the file?
    │         │
    │    ┌────┴────┐
    │    │         │
    │   Yes       No
    │    │         │
    │  Deletes   403 FORBIDDEN
    │  (trash,    │
    │  30d recover) File safe
    │         │
    └─────────┘
         │
  Even if deleted: 30-day Drive trash recovery

GCP + Portainer Deployment

The entire stack deploys on a single GCP Compute Engine VM, managed through Portainer's web UI. No Kubernetes, no Cloud Run — just Docker Compose on a VM, which is what you know.

Resource Sizing

  GCP COMPUTE ENGINE
  ┌─────────────────────────────────────────────────────────────────┐
  │  e2-standard-4 (4 vCPU, 16GB RAM, 100GB SSD)                   │
  │                                                                 │
  │  ┌──────────────────────────────────────────────────────────┐   │
  │  │  PORTAINER (port 9443)                                    │   │
  │  │  ├── Stack: "hermes-team"                                 │   │
  │  │  │   ├── hermes (image: nousresearch/hermes-agent)        │   │
  │  │  │   │   ports: 9292 (gateway)                            │   │
  │  │  │   │   env: GATEWAY_MULTIPLEX_PROFILES=true              │   │
  │  │  │   │   volumes: profiles/, workspaces/, shared/         │   │
  │  │  │   │                                                    │   │
  │  │  │   ├── honcho-api (build from GitHub)                   │   │
  │  │  │   │   ports: 8000                                       │   │
  │  │  │   │   env: DB_CONNECTION_URI, CACHE_URL, LLM key       │   │
  │  │  │   │                                                    │   │
  │  │  │   ├── honcho-db (image: pgvector/pgvector:pg17)        │   │
  │  │  │   │   volumes: honcho-db:/var/lib/postgresql/data      │   │
  │  │  │   │                                                    │   │
  │  │  │   └── honcho-redis (image: redis:7-alpine)             │   │
  │  │  │       volumes: honcho-redis:/data                      │   │
  │  │  └──────────────────────────────────────────────────────┘   │
  │  └──────────────────────────────────────────────────────────┘   │
  └─────────────────────────────────────────────────────────────────┘

Step-by-Step Deployment

1. Create the GCP VM

gcloud compute instances create hermes-vm \
  --zone=us-central1-a \
  --machine-type=e2-standard-4 \
  --image-family=ubuntu-2404-lts \
  --image-project=ubuntu-os-cloud \
  --boot-disk-size=100GB \
  --boot-disk-type=pd-ssd \
  --tags=portainer,hermes

2. Install Docker + Portainer (startup script)

#!/bin/bash
apt update && apt install -y docker.io docker-compose-v2
systemctl enable docker

docker volume create portainer_data
docker run -d --name portainer --restart always \
  -p 9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

3. Connect Portainer

Open https://<VM_EXTERNAL_IP>:9443. Set admin password. Connect to the local Docker environment. Go to Stacks → Add Stack, paste the docker-compose.yml, and deploy.

4. Firewall Rules

# Allow Portainer web UI (restrict to your IP)
gcloud compute firewall-rules create allow-portainer \
  --allow tcp:9443 \
  --source-ranges YOUR_HOME_IP/32

# Allow Hermes gateway admin API (if needed)
gcloud compute firewall-rules create allow-hermes-api \
  --allow tcp:9292 \
  --source-ranges YOUR_VPN_RANGE/24

docker-compose.yml

version: '3.8'
networks:
  hermes-net:

volumes:
  honcho-db:
  honcho-redis:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    environment:
      - PROFILE=default
      - GATEWAY_MULTIPLEX_PROFILES=true
      - AWS_PROFILE=hermes-team
    env_file:
      - ./hermes.env
    volumes:
      - ./profiles:/home/hermes/profiles
      - ./workspaces:/home/hermes/workspaces
      - ./shared:/home/hermes/shared:ro
      - ./honcho.json:/home/hermes/.hermes/honcho.json
      - ./google-chat-sa.json:/run/secrets/google-chat-sa.json
    ports:
      - "127.0.0.1:9292:9292"
    networks:
      - hermes-net
    restart: unless-stopped

  honcho-db:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: honcho
      POSTGRES_PASSWORD: ${HONCHO_DB_PASSWORD}
      POSTGRES_DB: honcho
    volumes:
      - honcho-db:/var/lib/postgresql/data
    networks:
      - hermes-net
    restart: unless-stopped

  honcho-redis:
    image: redis:7-alpine
    volumes:
      - honcho-redis:/data
    networks:
      - hermes-net
    restart: unless-stopped

  honcho-api:
    build: https://github.com/plastic-labs/honcho.git
    depends_on: [honcho-db, honcho-redis]
    environment:
      DB_CONNECTION_URI: postgresql+psycopg://honcho:${HONCHO_DB_PASSWORD}@honcho-db:5432/honcho
      CACHE_URL: redis://honcho-redis:6379/0
      AUTH_USE_AUTH: "false"
      LLM_OPENAI_API_KEY: ${HONCHO_LLM_KEY}
    networks:
      - hermes-net
    restart: unless-stopped

Directory Layout

/opt/hermes-deploy/
├── docker-compose.yml
├── hermes.env                         # Global env vars
├── honcho.json                        # Honcho config
├── google-chat-sa.json                # GCP SA key
├── profiles/
│   ├── alice/config.yaml
│   ├── alice/.env                     # Per-user secrets
│   ├── alice/SOUL.md
│   ├── alice/honcho.json
│   ├── bob/config.yaml
│   ├── bob/.env
│   ...
├── workspaces/
│   ├── alice/                         # Alice's project files
│   ├── bob/
│   ...
└── shared/
    ├── skills/                        # Team skills repo
    ├── docs/                          # Team documentation
    └── templates/

Backup Strategy

Security Model

The security model uses defense in depth — six layers between a user and another user's data.

Layer 1: Google Workspace Identity

Every user authenticates through Google Workspace. The Chat bot is configured with GOOGLE_CHAT_ALLOWED_USERS — only workspace members can message the bot. An attacker without a valid @company.com account cannot interact with the agent at all.

Layer 2: Profile Isolation

Each user's session runs in its own HERMES_HOME directory. Session keys are namespaced by profile — agent:alice:google_chat:dm:... vs agent:bob:google_chat:dm:.... Alice's conversation history is never loaded into Bob's session.

Layer 3: Tirith Filesystem Authorization

Every file tool call (terminal, read_file, write_file, search_files, patch) is intercepted by Tirith. Paths are checked against the profile's allowlist before execution.

# Alice CAN access:
/workspaces/alice/**
/shared/**
/home/hermes/profiles/alice/config.yaml

# Alice CANNOT access:
/workspaces/bob/**
/home/hermes/profiles/bob/MEMORY.md
/etc/shadow

Layer 4: Honcho Peer Isolation

Honcho uses a workspace + peer model. The user peer (team) is shared across all profiles — this is intentional for team context. Each AI peer (alice, bob, etc.) has private observations that no other peer can query. Honcho's API does not expose cross-peer data.

Layer 5: AWS Bedrock IAM

The VM's IAM role defines the blast radius for LLM access. No API keys in config files. Bedrock Guardrails can be applied to all inference calls for content filtering and topic denial across the entire team.

Layer 6: Per-User Google OAuth Tokens

Each user's Google Drive OAuth token is scoped to their account. Token files are stored in the profile's HERMES_HOME with filesystem permissions. Alice's token cannot read Bob's Drive. Bob's token cannot read Alice's Drive.

Trust Model Summary

Race Conditions & Concurrency

With 25 users sharing one gateway, concurrent operations are the rule, not the exception. This page documents every race condition in the system, its risk level, and the mitigation. The fundamental principle: messages should queue at the right layer — the Pub/Sub adapter drains immediately into an internal work queue rather than serializing unrelated users.

Architecture: Internal Work Queue

Contrary to the default GOOGLE_CHAT_MAX_MESSAGES=1 which serializes the entire adapter, the correct design uses a higher flow control limit and an internal dispatch queue:

  Pub/Sub subscription ──────────────────────────────────────────────┐
         │                                                            │
         │  GOOGLE_CHAT_MAX_MESSAGES=10 (drains quickly)               │
         ▼                                                            │
  ┌─────────────────────────────────────────────┐                     │
  │  Google Chat Adapter (single pull loop)      │                     │
  │  ├── Polls Pub/Sub every 100ms               │                     │
  │  ├── Receives up to 10 messages per poll     │                     │
  │  ├── For each: apply email mapper → set      │                     │
  │  │   source.profile → enqueue to dispatch    │                     │
  │  └── NEVER blocks on LLM calls               │                     │
  └─────────────────────┬───────────────────────┘                     │
                        │                                             │
                        ▼                                             │
  ┌─────────────────────────────────────────────┐                     │
  │  Internal Dispatch Queue (list + lock)       │                     │
  │                                              │                     │
  │  ┌──────────┐  ┌──────────┐  ┌──────────┐   │                     │
  │  │ Alice:   │  │ Bob:     │  │ Carol:   │   │                     │
  │  │ "summar  │  │ "deploy  │  │ "what's  │   │                     │
  │  │ ize Q3"  │  │ my app"  │  │ the ETA" │   │                     │
  │  └────┬─────┘  └────┬─────┘  └────┬─────┘   │                     │
  │       │             │             │          │                     │
  │       │    ┌────────┘             │          │                     │
  │       │    │                      │          │                     │
  │       ▼    ▼                      ▼          │                     │
  │  ┌─────────────────────────────────────┐     │                     │
  │  │  Session Dispatcher                 │     │                     │
  │  │  ├── Identifies profile per msg     │     │                     │
  │  │  ├── Routes to active or new session│     │                     │
  │  │  └── For deployer profile:          │     │                     │
  │  │      └── Acquires lockfile first    │     │                     │
  │  └─────────────────────────────────────┘     │                     │
  └─────────────────────────────────────────────┘                     │
                        │                                             │
          ┌─────────────┼─────────────┐                               │
          ▼             ▼             ▼                               │
  ┌────────────┐ ┌────────────┐ ┌────────────┐                        │
  │ Alice's    │ │ Bob's      │ │ Carol's    │                        │
  │ agent loop │ │ agent loop │ │ agent loop │                        │
  │ (LLM call) │ │ (LLM call) │ │ (LLM call) │                        │
  │ ═══════╗   │ │            │ │            │                        │
  │ ║ RUN  ║   │ │ ═══════╗   │ │            │                        │
  │ ╚══════╝   │ │ ║ RUN  ║   │ │ ═══════╗   │                        │
  │            │ │ ╚══════╝   │ │ ║ RUN  ║   │  ← all concurrent       │
  │            │ │            │ │ ╚══════╝   │                        │
  └────────────┘ └────────────┘ └────────────┘                        │
        │              │              │                               │
        ▼              ▼              ▼                               │
  ┌─────────────────────────────────────────────────────────────┐     │
  │  Chat REST API (outbound)                                    │     │
  │  Each agent replies independently. No ordering guarantees    │     │
  │  needed — each user sees only their own conversation.        │     │
  └─────────────────────────────────────────────────────────────┘     │
                                                                      │
  Serialized operations (lockfile):
  ┌──────────────────────────────────────────────┐                    │
  │  deployer profile only:                      │                    │
  │  - Deploy plugin/app                         │                    │
  │  - Edit Caddyfile                            │                    │
  │  - Modify shared skills                       │                    │
  │  These wait for the lock. All other ops free. │                    │
  └──────────────────────────────────────────────┘

Race Condition Matrix

Mitigation 1: Deployer Lockfile (Essential)

This lockfile prevents two deploy operations from running simultaneously. The deployer skill acquires the lock before starting and releases it on completion or failure:

#!/usr/bin/env python3
# deployer_lock.py — included in deployer profile's skill
import os, time, json, sys

LOCK_PATH = "/opt/data/.deployer.lock"
TIMEOUT = 180  # seconds — max deploy time

def acquire_lock(timeout=TIMEOUT):
    start = time.time()
    while True:
        if not os.path.exists(LOCK_PATH):
            with open(LOCK_PATH, 'w') as f:
                json.dump({"pid": os.getpid(),
                           "start": time.time(),
                           "user": os.environ.get("GOOGLE_CHAT_USER_EMAIL", "unknown")}, f)
            return True
        # Check if lock is stale (> timeout)
        try:
            with open(LOCK_PATH) as f:
                data = json.load(f)
            if time.time() - data.get("start", 0) > TIMEOUT:
                os.remove(LOCK_PATH)
                continue  # retry
        except (json.JSONDecodeError, FileNotFoundError):
            os.remove(LOCK_PATH)
            continue
        if time.time() - start > timeout:
            return False  # timeout
        time.sleep(1)

def release_lock():
    if os.path.exists(LOCK_PATH):
        os.remove(LOCK_PATH)

# Usage in deployer skill:
# if not acquire_lock():
#     return "Another deploy is in progress. Try again in a few minutes."
# try:
#     # ... deploy logic ...
# finally:
#     release_lock()

Mitigation 2: Pre-Commit Health Check

The auto-commit cron should only commit when the system is healthy. A broken gateway or active errors means in-flight edits could be captured mid-write:

#!/bin/bash
# /opt/data/scripts/auto-commit.sh — with health check
cd /opt/data

# 1. Check gateway health
if ! curl -sf http://localhost:9292/health > /dev/null 2>&1; then
  echo "[$(date)] Gateway unhealthy — skipping auto-commit"
  exit 1
fi

# 2. Check no recent errors in last 5 minutes
if journalctl -u hermes-gateway --since "5 min ago" 2>/dev/null | grep -qi "error\|critical\|traceback"; then
  echo "[$(date)] Recent gateway errors — skipping auto-commit"
  exit 2
fi

# 3. Commit if changes exist
git add -A
if ! git diff --cached --quiet; then
  git commit -m "Auto-commit: $(date +%Y%m%d-%H%M%S) — health check passed"
  echo "[$(date)] Auto-commit succeeded"
else
  echo "[$(date)] No changes to commit"
fi

Mitigation 3: Dedicated Cron Peer in Honcho

Cron jobs should write observations to a separate Honcho peer to avoid interleaving with user session data:

# In cron job's honcho.json (override per cron profile)
{
  "baseUrl": "http://honcho:8000",
  "hosts": {
    "hermes": {
      "workspace": "hermes-team",
      "peerName": "team",              # shared workspace — same as user sessions
      "aiPeer": "cron-worker",         # DIFFERENT from user sessions ("alice", "bob")
      "observationMode": "directional" # cron writes facts, but doesn't read user memory
    }
  }
}

This means cron-extracted facts live in the same workspace peer (visible to all users), but are attributed to the cron-worker AI peer rather than interleaving with alice's session observations. When Alice queries "any updates?", the agent searches the workspace peer — both cron and user contributions appear as team knowledge.

Mitigation 4: Pub/Sub Flow Control Configuration

# In Hermes .env — correct adapter settings for concurrent team use
GOOGLE_CHAT_MAX_MESSAGES=10        # Drain Pub/Sub quickly, don't serialize
GOOGLE_CHAT_MAX_BYTES=16777216     # 16 MiB cap on in-flight bytes
# No per-session serialization — the internal queue handles ordering

With MAX_MESSAGES=10, the adapter pulls up to 10 messages per poll. Each is enqueued to the internal dispatch queue independently. Alice's long LLM call (8 seconds) does not block Bob's message from being dispatched to his own profile's agent loop. The only serialization is within a single user's session — Alice's second message waits for her first to complete, which is correct conversational behavior.

Decision Matrix: What Needs Serialization

Deploying Apps & Plugins

The deployer profile is a privileged Hermes profile that non-technical users interact with via natural language to deploy apps, plugins, and skills. Instead of teaching 25 people to use Docker, Portainer, or the GCP Console, they simply tell the bot what they want. The deployer handles the infrastructure.

What Is the Deployer Profile?

The deployer is a standard Hermes profile with elevated permissions. It has:

The Three Tiers of Deployment

Deployer Security Model

Gate 1: Who Can Deploy

# profiles/deployer/config.yaml
multiplex:
  deployer:
    allowed_deployers:
      - alice@company.com
      - bob@company.com
      - carol@company.com
    # Users not on this list receive: "You are not authorized to deploy.
    # Ask your admin to add your email to the deployer allowlist."

Gate 2: Lockfile (Prevents Concurrent Deploys)

  # Every deploy operation starts with:
  from deployer_lock import acquire_lock, release_lock
  if not acquire_lock(timeout=180):
      return "Another deploy is in progress. Try again in a few minutes."
  try:
      # ... deploy logic ...
  finally:
      release_lock()

See the Race Conditions page for the full lockfile implementation.

Gate 3: Tirith Constraints

# Shared between deployer and deployer-specific config
terminal:
  tirith:
    fail_open: false
    allowed_paths:
      - /opt/data/plugins/**
      - /opt/data/shared/skills/**
      - /opt/data/deployments/**
      - /tmp/deploy/**
    allowed_commands:
      - docker compose -f *
      - docker compose up -d *
      - gcloud run deploy *
      - git clone *
      - npm install
      - npm run build
      - curl -X POST *

Deployer SOUL.md Template

The deployer profile's behavior instructions are critical for safe operation. Copy this into profiles/deployer/SOUL.md:

# Deployer Profile — Instructions

## Your Role
You deploy apps, plugins, and skills for team members. You have elevated permissions.
You are the ONLY profile with Docker and gcloud access.

## Identity Verification
- The user's email is available as GOOGLE_CHAT_USER_EMAIL or in the event source
- Check allowed_deployers list in your config before ANY deploy operation
- If the user is not authorized, respond: "You're not authorized to deploy. Ask your admin to add your email."
- Do NOT reveal the allowed_deployers list contents to unauthorized users

## Deploy Workflow (Always Follow This)
1. Verify the user is authorized. If not, reject immediately.
2. Acquire the deployer lock. If another deploy is in progress, tell the user to wait.
3. Ask: "What type of deploy is this?" (plugin/skill/docker app / cloud run)
4. For plugins/skills: ask for the repo URL or file upload
5. For Docker apps: ask for the image name and desired subpath
6. For Cloud Run: ask for the image name and service name
7. Before modifying any file, create a timestamped checkpoint.
8. Deploy. If something fails, roll back from the checkpoint.
9. Test the deploy. Verify the app responds or the plugin loads.
10. Release the lock.
11. Reply with the URL and any credentials (password for Docker apps).

## Security Rules (NEVER Violate)
- NEVER run rm -rf or delete files arbitrarily
- NEVER modify another user's profile configs without their explicit request
- NEVER share credentials in a shared space — only in DMs
- NEVER run untrusted code from unknown repos
- For unknown repos: inspect the code first or ask the admin
- ALWAYS verify a deploy works before telling the user it's done

## Lockfile Protocol
- acquire_lock() before any deploy
- release_lock() in a finally block
- If acquire_lock times out, tell the user "Another deploy is in progress. Try again in a few minutes."
- Do NOT attempt to remove a stale lock without checking it first

Example Interactions

Alice deploys a dashboard plugin

Alice: deploy my team dashboard plugin from github.com/team/order-tracker
…deployer clones, builds, copies, rescans…
Bot: ✅ Deployed "order-tracker" to the dashboard.
  → https://team-vm.nip.io/dashboard/order-tracker
  It should appear in 5-10 seconds. Let me know if you want to change anything.

Bob deploys a Docker app

Bob: deploy my flask inventory app from ghcr.io/team/inventory:v1
Bot: Checking authorization… authorized ✓
  Acquiring deploy lock… got it ✓
  Creating checkpoint… ✓
  Pulling image…
  Adding Caddy route for /apps/inventory/* → inventory:5000… ✓
  Reloading Caddy… ✓
  Testing endpoint… 200 OK ✓
  Releasing lock… ✓
  ✅ Deployed!
  URL: https://team-vm.nip.io/apps/inventory/
  Password: z7kq9m2x
  Share this password with team members who need access.

Carol deploys to Cloud Run with IAP

Carol: deploy my reports app to cloud run from ghcr.io/team/reports:v2
Bot: Authorized ✓ Lock acquired ✓
  Running gcloud run deploy reports…
  Enabling IAP…
  ✅ Deployed to Cloud Run.
  URL: https://reports-xxxxx-uc.a.run.app
  🔒 IAP enabled — open the link and sign in with your @company.com account.

Updating & Removing Deployments

Cost Estimation

This page breaks down every cost in the system — infrastructure, LLM tokens, backups, and optional upgrades. The goal is to give you a predictable monthly budget with no surprises. Total estimated cost for 25 users: ~$160-300/month, or ~$6-12/user/month fully loaded.

2. LLM Inference (AWS Bedrock) — ~$160-220/mo

Variable cost based on usage. The dominant cost driver is the model tier used, not the number of users.

Bedrock Model Pricing (July 2026)

Per-User Breakdown by Usage Tier

Team-Level Projection

Optimizing: Per-Profile Model Routing

Control costs by setting model routing per profile. A power user who needs Sonnet gets it. A light user who only asks simple questions stays on Haiku:

# profiles/light-user/config.yaml — keep costs low
bedrock:
  default_model: anthropic.claude-3-5-haiku-20241022
  # No Sonnet override — all messages use Haiku
  # Est. cost: ~$2/mo

# profiles/power-user/config.yaml — ramp up when needed
bedrock:
  default_model: anthropic.claude-3-5-haiku-20241022
  overrides:
    - model: anthropic.claude-3-5-sonnet-20241022
      when: task_type == "coding" OR tool_count > 5 OR context > 6000
    - model: anthropic.claude-3-opus-20240229
      when: task_type == "document_review" OR user_query contains "deep analysis"
  # Est. cost: ~$20-25/mo

# profiles/deployer/config.yaml — complex operations need brains
bedrock:
  default_model: anthropic.claude-3-5-sonnet-20241022
  # Est. cost: ~$30-40/mo (but only 1 user)

Background Tasks (Cron Jobs)

Use Nova Lite ($0.06/M input) for all scheduled cron jobs — backup verification, checkpoint cleanup, disk monitoring, auto-commits. These don't need reasoning power:

# honcho.json for cron profile
hermes cron create \
  --name "check-disk" \
  --schedule "daily at 6am" \
  --prompt "Run /opt/data/scripts/check-disk.sh and report if usage > 80%" \
  --profile cron-worker \
  --model provider=bedrock,model=amazon.nova-lite-v1.0

# Cost: ~$0.50-1/mo for all cron jobs combined

3. Storage & Backups — ~$1/mo

4. Optional Upgrades

5. Full Monthly Breakdown

6. What $100/Mo/User Gets You

If you budget $100/user/month for Bedrock, that's $2,500/mo total for 25 users. Here's what that buys:

To burn $100/user/month, every message would need to use Opus (the most expensive model). With intelligent routing (Haiku default, Sonnet/Opus only when needed), real costs are $5-10/user/month. Your $100/user gut estimate likely came from SaaS agent platforms that charge per-seat licensing — Bedrock has no per-seat fee, you pay only for tokens consumed.

7. Cost Tracking & Alerts

Set up budget alerts to avoid surprises:

User Onboarding

Admin Setup (One Time, ~1 Hour)

Phase 1: GCP Infrastructure

Phase 2: Google Chat Bot

Phase 3: AWS Bedrock

Phase 4: Profiles

User Setup (~5 Minutes Each)

Onboarding Checklist

Cost Summary

Hermes Team Deployment — Architecture & Deployment Guide
Hermes v0.18+ · Multiplex Mode · AWS Bedrock · Google Chat · Honcho · GCP

Backup & Recovery Strategy

All backups use GCP native services — no third-party tools, no external storage providers. The strategy protects every data layer from accidental deletion to total VM loss. Recovery is designed to be executed by a non-technical admin via the GCP Console (no CLI required).

What Needs Backing Up

  BACKUP TARGETS
  ┌─────────────────────────────────────────────────────────────────────┐
  │                                                                     │
  │  VM (e2-standard-4)                                   █████████████│
  │  ┌─────────────────────────────────────┐             █  DAILY VM  █│
  │  │ Honcho PostgreSQL (pg_dump) ────────┼──►           █  SNAPSHOT  █│
  │  │ Profile configs (rsync) ────────────┼──►           █ (optional) █│
  │  │ Hermes state (rsync) ───────────────┼──►           █████████████│
  │  │ Plugins & skills (rsync) ──────────┼──►                          │
  │  └─────────────────────────────────────┘         ██████████████████│
  │                                                  █  CLOUD STORAGE █│
  │                                                   █  BUCKET        █│
  │                                                   █  - pg_dump.sql █│
  │                                                   █  - profiles/   █│
  │                                                   █  - state/     █│
  │                                                   █  - plugins/   █│
  │                                                   █  7-day retention█│
  │                                                   █  30-day archival█│
  │                                                   ██████████████████│
  │                                                                     │
  │  ┌─────────────────────────────────────┐          ██████████████████│
  │  │ CLOUD SQL (optional upgrade)        │          █  MANAGED PITR  █│
  │  │ Point-in-time recovery: 7 days      │          █  automatic     █│
  │  │ Built-in HA: cross-zone             │          ██████████████████│
  │  └─────────────────────────────────────┘                            │
  └─────────────────────────────────────────────────────────────────────┘

Backup Schedule

Setup: Cloud Storage Bucket

Implementation

A. Database Backups (Every 6 Hours)

The most critical backup — Honcho's PostgreSQL contains all team knowledge. A six-hour cadence means at most half a day of lost conversations:

#!/bin/bash
# /opt/data/scripts/backup-db.sh
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
BUCKET="gs://hermes-team-backups-<project>/db/"

docker exec honcho-db pg_dump -U honcho honcho \
  --no-owner --no-acl \
  | gzip > /tmp/honcho-$TIMESTAMP.sql.gz

gsutil cp /tmp/honcho-$TIMESTAMP.sql.gz $BUCKET
gsutil cp /tmp/honcho-$TIMESTAMP.sql.gz $BUCKET"latest.sql.gz"  # overwrite for easy restore

rm /tmp/honcho-$TIMESTAMP.sql.gz

B. Profile & State Backups (Daily)

#!/bin/bash
# /opt/data/scripts/backup-profiles.sh
DATE=$(date +%Y%m%d)
BUCKET="gs://hermes-team-backups-<project>/profiles/"

gsutil -m rsync -r /opt/data/profiles $BUCKET"$DATE/"
gsutil -m rsync -r /opt/data/.hermes $BUCKET"state/$DATE/"
gsutil -m rsync -r /opt/data/plugins $BUCKET"plugins/$DATE/"

C. VM Disk Snapshot (Daily)

gcloud compute snapshots create hermes-vm-daily-$(date +%Y%m%d) \
  --source-disk=hermes-vm \
  --source-disk-zone=us-central1-a \
  --storage-location=us-central1

D. Schedule with Cron Jobs (Agent-Managed)

Each backup script runs via a Hermes cron job. The agent handles the scheduling, the scripts do the actual work. No external cron system needed.

hermes cron create \
  --name "db-backup" \
  --schedule "every 6h" \
  --prompt "Run /opt/data/scripts/backup-db.sh" \
  --profile deployer

hermes cron create \
  --name "profile-backup" \
  --schedule "daily at 2am" \
  --prompt "Run /opt/data/scripts/backup-profiles.sh" \
  --profile deployer

hermes cron create \
  --name "vm-snapshot" \
  --schedule "daily at 3am" \
  --prompt "Run gcloud compute snapshots create hermes-vm-daily-\$(date +%Y%m%d) --source-disk=hermes-vm --source-disk-zone=us-central1-a --storage-location=us-central1" \
  --profile deployer

Recovery Procedures

Scenario 1: Database Corruption or Accidental Delete

Time to recover: ~10 minutes. Tools needed: GCP Console only.

Scenario 2: Individual User Profile Corruption

Time to recover: ~5 minutes. No other users affected.

Scenario 3: Total VM Loss (VM deleted, region disaster)

Time to recover: ~45 minutes. Everything is replaceable because all data is in Cloud Storage.

Scenario 4: Cryptographic Key Loss

If the Google Chat SA key or Google Drive OAuth client secret is lost, services stop working. These cannot be restored from backup — they must be re-created:

Automated Verification

Backups are worthless if they can't be restored. A cron job that verifies backup integrity weekly:

#!/bin/bash
# /opt/data/scripts/verify-backup.sh
# Runs weekly. Tests that the latest DB dump is valid.
LATEST=$(gsutil ls gs://hermes-team-backups-<project>/db/ | tail -1)
gsutil cp "$LATEST" /tmp/verify.sql.gz
gunzip -t /tmp/verify.sql.gz && echo "✅ DB dump is valid" || echo "❌ DB dump corrupt"
rm /tmp/verify.sql.gz

# Verify profile configs exist for all 25 users
for name in $(ls /opt/data/profiles/); do
  if [ -f "/opt/data/profiles/$name/config.yaml" ]; then
    echo "✅ $name config found"
  else
    echo "❌ $name config MISSING"
  fi
done

Optional Upgrade: Cloud SQL for Honcho

For zero-effort backups with point-in-time recovery, migrate the Honcho database from the container to GCP Cloud SQL. This replaces the pg_dump cron with Google-managed backups:

When to upgrade: When the team has been using the system for 3+ months and the accumulated knowledge makes even 6 hours of potential data loss unacceptable. Until then, the container + pg_dump cron is sufficient.

Checkpoints & Version Control

Backups protect against VM loss. Checkpoints and git version control protect against the more common threat: the agent or a user making a mistake that corrupts configs, skills, or state. A bad config change, a typo in a SOUL.md, a plugin that overwrites a shared file — these happen far more often than server failures. This page covers git-tracking configs for instant rollback, pre-operation checkpoints, and patterns for undoing agent-caused damage.

Threat Model: What Actually Goes Wrong

Git Repository Structure

All configuration files live in a git-tracked directory. This is distinct from data files (which go to Cloud Storage backups) — configs change frequently and need per-line attribution and rollback:

/opt/data/
├── config.yaml              # git-tracked
├── Caddyfile                # git-tracked
├── honcho.json              # git-tracked
├── docker-compose.yml       # git-tracked
├── profiles/                # git-tracked (configs only)
│   ├── alice/
│   │   ├── config.yaml      # git-tracked
│   │   ├── .env             # git-tracked (no secrets — those are in GCP Secret Manager or mounted files)
│   │   └── SOUL.md          # git-tracked
│   ├── bob/
│   └── ...
├── shared/                  # git-tracked
│   ├── skills/              # git-tracked
│   └── docs/                # git-tracked
├── plugins/                 # git-tracked (manifests + code)
├── scripts/                 # git-tracked
├── .git/                    # auto-committed via cron
├── checkpoints/             # pre-operation snapshots (not in main git — managed separately)
│   ├── alice-20260715-140231/
│   └── shared-skills-20260715-140500/
└── data/                    # NOT git-tracked — backed up to Cloud Storage
    ├── google_tokens/
    └── session_db/

Auto-Commit Cron

A cron job on the deployer profile commits all tracked changes every 4 hours. This creates an audit trail of who changed what (the commit author is the profile name):

#!/bin/bash
# /opt/data/scripts/auto-commit.sh
# Runs every 4 hours via Hermes cron. Commits all tracked file changes.
cd /opt/data

# Stage all tracked files
git add -A

# Check if there are changes
if ! git diff --cached --quiet; then
  git commit -m "Auto-commit: $(date +%Y-%m-%dT%H:%M:%S%z) — profile: ${HERMES_PROFILE:-unknown}"
  # Optional: push to a private git remote if you want off-machine redundancy
  # git push origin main
fi

hermes cron create \
  --name "auto-commit" \
  --schedule "every 4h" \
  --prompt "Run /opt/data/scripts/auto-commit.sh" \
  --profile deployer

Recovery Scenarios

Scenario A: Agent Corrupts a Config File

What happened: Alice asked the agent "update my config to use Bedrock Haiku instead of Sonnet." The agent wrote a malformed YAML with wrong indentation. The gateway logs an error and Alice's profile stops loading.

Scenario B: Agent Overwrites a Shared Skill with a Bad Version

What happened: Bob told the agent "improve the deploy skill to handle Docker images better." The agent rewrote the skill badly — it no longer works. All 25 profiles are now using the broken skill.

Scenario C: Agent Spirals and Creates Thousands of Files

What happened: A cron job or agent task gets stuck in a loop writing files to a profile's workspace. Disk usage spikes.

Scenario D: User Accidentally Deletes a Plugin

What happened: A user with file manager access accidentally moved a plugin directory.

Pre-Operation Checkpoints (Agent-Side)

The deployer profile's skill template includes an automatic checkpoint before any destructive operation:

# skill: deploy-with-checkpoint (template for all deploy operations)

def pre_checkpoint(target_dir: str, operation_name: str):
    """Copy the target directory to /opt/data/checkpoints/ before making changes."""
    import shutil, datetime
    ts = datetime.datetime.now().strftime("%Y%m%d-%H%M%S")
    safe_name = operation_name.replace(" ", "_")
    dest = f"/opt/data/checkpoints/{safe_name}-{ts}/"
    shutil.copytree(target_dir, dest)
    return dest

def on_error_rollback(checkpoint_dir: str, target_dir: str):
    """Restore the target directory from checkpoint on failure."""
    import shutil
    shutil.rmtree(target_dir)
    shutil.copytree(checkpoint_dir, target_dir)

# Usage in any deploy/update skill:
# checkpoint = pre_checkpoint("/opt/data/profiles/alice", "update config")
# try:
#     # ... make changes ...
# except Exception as e:
#     on_error_rollback(checkpoint, "/opt/data/profiles/alice")
#     return f"Operation failed and was rolled back. Error: {e}"

This means the agent automatically snapshots the state before making changes. If the operation errors — syntax error, bad format, network timeout — the checkpoint is restored. If the operation succeeds but the result is wrong, the checkpoint is still available in the checkpoints directory for manual rollback.

Checkpoint Cleanup

Checkpoints accumulate. A weekly cleanup cron keeps only the last 7 days:

#!/bin/bash
# /opt/data/scripts/cleanup-checkpoints.sh
find /opt/data/checkpoints -mindepth 1 -maxdepth 1 -type d -mtime +7 -exec rm -rf {} +
echo "Cleaned up checkpoints older than 7 days"

hermes cron create \
  --name "cleanup-checkpoints" \
  --schedule "weekly on Sunday at 4am" \
  --prompt "Run /opt/data/scripts/cleanup-checkpoints.sh" \
  --profile deployer

The Agent's Own Safeguards

Beyond file and config protection, the Hermes agent itself needs guardrails against its own mistakes:

Quick Reference: Recovery Commands

Installation Quick Start

This is the chronological build plan — from zero to fully operational for 25 team members. Each phase is independent and testable. The system becomes usable after Phase 3. Everything after that is capability expansion.

Dependency Map

  Phase 1 (VM + Docker) ───────────────────────┐
                                               │
  Phase 2 (Google Chat bot) ───────────────────┤
                                               │
  Phase 3 (Multiplex + Profiles + Routing) ◄───┘
        │
        ├──► Phase 4 (Honcho shared memory)
        │
        ├──► Phase 5 (Google Drive per-user)
        │
        └──► Phase 6 (Team Rollout)
                 │
                 └──► Phase 7 (Operations, monitoring, hardening)
  

Critical path: Phase 1 → Phase 2 → Phase 3. Everything else is parallelizable. The system is usable for the team after Phase 3. Phases 4-7 add capability that can be rolled out gradually without disrupting users.

Estimated Timeline