A personal fleet of nine Hermes Agent instances running native on a single Mac Mini M4 — one Hermes install, one profile per agent, Telegram bots and Linear Agent Sessions as the human interfaces, self-hosted Honcho for conversational memory, Notion for durable knowledge/reporting, and 1Password as the canonical static-credential plane. No containers for the agents; Docker is kept only for the Honcho and SearXNG services. Host monitoring needs no agent — a dumb launchd watchdog covers it (docs/10 §14.5).
Status: fully deployed — 9/9 agents live under launchd on the Mini. The fleet runs official upstream-clean Hermes Agent v0.20.3 (2026.8.16.2); Linear is a reviewed profile-local plugin (0.8.13 active and behavior-accepted on all nine profiles), while Honcho local authentication is config-only and keeps scoped JWTs in process memory. Linear alone disables direct interim display so completed Codex commentary reaches the official generic on_interim_message plugin hook; Telegram and other surfaces retain their normal display behavior.
The fleet is not game-studio-only. It's a general-purpose personal assistant layer (works for your whole life) plus a game-studio pipeline layered on top. The studio names are flavor; the capabilities underneath are general.
flowchart TB
you["📱 You · Telegram (9 bots)<br/>+ Linear (Derya)"]:::user
you <--> tg(["Telegram cloud"]):::net
you <--> linear(["Linear Agent Sessions"]):::net
subgraph mini["🖥️ Mac Mini M4 · 16 GB · always-on · auto-login"]
direction TB
subgraph hermes["native Hermes · one install · ~/.hermes · launchd"]
direction TB
subgraph gen["🌐 general-use"]
Derya["Derya · general<br/>GPT-5.6-sol"]:::codex
Tuna["Tuna · assistant<br/>GPT-5.6-terra"]:::codex
Doruk["Doruk · researcher<br/>GPT-5.6-sol"]:::codex
end
subgraph studio["🎮 game studio"]
Sarp["Sarp · producer<br/>GPT-5.6-luna"]:::codex
Ozan["Ozan · writer<br/>GPT-5.6-sol"]:::codex
Naz["Naz · coder · Metal GPU<br/>GPT-5.6-sol"]:::codex
Nilay["Nilay · marketing<br/>GPT-5.6-luna"]:::codex
end
subgraph personal["🧑 personal tier"]
Murat["Murat · finance<br/>GPT-5.6-terra"]:::codex
Defne["Defne · health<br/>GPT-5.6-terra"]:::codex
end
end
wd["🐕 watchdog · launchd<br/>5-min health check"]:::wd
subgraph svc["local services · loopback"]
Honcho[("Honcho · :8000<br/>Docker · shared memory")]:::infra
HonchoCodex["Honcho Codex Adapter · :18080<br/>9 surfaces · 4 workload routes · 1 model"]:::svc
SearXNG["SearXNG · :8888<br/>search fallback"]:::svc
end
end
tg <--> hermes
linear <--> tunnel["Cloudflare Named Tunnel<br/>exact-path HMAC webhooks"]:::net
tunnel <--> hermes
gen -. "conversational memory" .-> Honcho
studio -. "conversational memory" .-> Honcho
personal -. "conversational memory" .-> Honcho
gen -. "search fallback" .-> SearXNG
studio -. "search fallback" .-> SearXNG
personal -. "search fallback" .-> SearXNG
wd -. "down/crash alert<br/>(bypasses agents)" .-> tg
Notion[("Notion<br/>knowledge · plans · decisions · reports")]:::knowledge
OnePassword["1Password<br/>canonical static credentials"]:::secret
ext["☁️ Codex · GPT-5.6 primary<br/>DeepSeek · fallback<br/>TinyFish · OpenRouter"]:::ext
hermes --> ext
Honcho -->|"text generation"| HonchoCodex -->|"Codex OAuth"| ext
Honcho -->|"embeddings only"| ext
hermes <--> Notion
OnePassword -. "op:// resolution<br/>at process startup" .-> hermes
OnePassword -. "runtime bearer resolution" .-> HonchoCodex
classDef user fill:#303F9F,stroke:#1A237E,color:#fff
classDef net fill:#1976D2,stroke:#0D47A1,color:#fff
classDef mini fill:#388E3C,stroke:#1B5E20,color:#fff
classDef codex fill:#EF6C00,stroke:#E65100,color:#fff
classDef infra fill:#7B1FA2,stroke:#4A148C,color:#fff
classDef svc fill:#00838F,stroke:#006064,color:#fff
classDef ext fill:#00796B,stroke:#004D40,color:#fff
classDef knowledge fill:#00796B,stroke:#004D40,color:#fff
classDef secret fill:#455A64,stroke:#263238,color:#fff
classDef wd fill:#D32F2F,stroke:#B71C1C,color:#fff
style mini fill:#ECEFF1,stroke:#90A4AE,color:#263238
style hermes fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20
style gen fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1
style studio fill:#FFF3E0,stroke:#FFB74D,color:#E65100
style personal fill:#F3E5F5,stroke:#BA68C8,color:#4A148C
style svc fill:#E0F7FA,stroke:#26C6DA,color:#006064
Colours: orange = GPT-5.6/Codex agents · purple = Honcho · teal = local services · red = watchdog · indigo = you · blue = network · dark-teal = external APIs/knowledge · slate = credential plane. All nine agents use GPT-5.6 via Codex as primary; DeepSeek V4 Flash is the profile-level fallback.
| Plane | System | Canonical responsibility |
|---|---|---|
| Hot/local context | MEMORY.md, USER.md, session SQLite |
Compact prompt facts and exact per-profile conversation recall |
| Conversational memory | Honcho | Derived user/peer models and semantic conversation context |
| Human work control | Linear | Issues, assignee/delegate, dependency, execution state, checkpoints, acceptance, and closure |
| Durable knowledge/reporting | Notion | Bilgi Kütüphanesi, plans, decisions, candidate pools, runbooks, and reports |
| Credentials | 1Password | Static provider, bot, webhook, and integration secrets resolved at startup |
Nine native profiles in one Hermes install. Slug = the functional name (constant, ASCII, what the directory/peer/bot-username use). Display = the persona shown in Telegram (flavor only — titles don't fence capability). Profile art is pixel-art, one cohesive crew.
🌐 General-use — your whole life, not just games
 Derya general |
 Tuna assistant |
 Doruk researcher |
🎮 Game-studio pipeline — specialists
 Nilay marketing |
 Sarp producer |
 Ozan writer |
 Naz coder |
🧑 Personal tier — separate life domains
 Murat finance |
 Defne health |
| Display | Slug | Mode | What it actually does | Model |
|---|---|---|---|---|
| Derya | general |
always-on | Your main line for anything — work and life: questions, planning, brainstorming, hand-offs. (Themed as founder/creative director.) | GPT-5.6-sol (Codex) → ds-flash fb |
| Tuna | assistant |
always-on | Studio + personal day: calendar, reminders, errands, morning digest covering both | GPT-5.6-terra (Codex) → ds-flash fb |
| Doruk | researcher |
always-on | Research any domain, cites sources; also runs the weekly game-scout cron | GPT-5.6-sol (Codex) → ds-flash fb |
These three you'd want even with no game studio. Start here for day-to-day use.
| Display | Slug | Mode | What it actually does | Model |
|---|---|---|---|---|
| Sarp | producer |
on-demand | Scores raw game ideas on a rubric (buildable / loop / discovery / monetization); kills hype | GPT-5.6-luna (Codex) → ds-flash fb |
| Ozan | writer |
on-demand | Drafts & edits — game PRDs, store copy, prose (general writing too) | GPT-5.6-sol (Codex) → ds-flash fb |
| Naz | coder |
on-demand | Godot/GDScript game code — the studio's code-runner (native for Metal GPU + the editor; fenced) | GPT-5.6-sol (Codex) → ds-flash fb |
| Nilay | marketing |
always-on | Go-to-market: Steam page, wishlists, devlog/social cadence, ASO, outreach (briefs Ozan for copy) | GPT-5.6-luna (Codex) → ds-flash fb |
Names are a (mildly sarcastic) Turkish game-studio crew; each comic persona reinforces its role rather than fighting it. ("On-demand" = usage pattern; all 9 gateways run 24/7 under launchd.)
Beyond the studio, each life domain gets its own profile (own SOUL/memory/bot; Honcho means it already knows who you are). Built so far:
| Display | Slug | Does | Model |
|---|---|---|---|
| Murat | finance |
Markets & finance analyst — analyzes read-only Google-Sheet/CSV/statement data, scans news/Reddit/finance sites (BIST + global), crunches numbers with fenced code_execution. Not investment advice. |
GPT-5.6-terra (Codex) → ds-flash fb |
| Defne | health |
Health & fitness coach — workout/nutrition logging, calorie/macro estimate from food photos (ballpark), trend tracking. Not medical advice. | GPT-5.6-terra (Codex) → ds-flash fb |
All nine profiles are host-code-capable by design (accepted 2026-07-19). Hermes v0.19.0 resolves both
terminalandexecute_codeon every profile; approvals areofffleet-wide. The old “only general/coder/finance can run code” design was superseded — the fleet is uniformly tooled, and security relies on persona guardrails, credential stripping, Tirith ongeneralandresearcher, and the website blocklist oncoderandfinance(docs/09 §13).
🔍 Web stack — all 9 agents: every agent searches via TinyFish (MCP, OAuth 2.1 PKCE — no API key) with SearXNG as automatic fallback. None is walled off from the web and search never hard-fails; an outage on either side degrades to the other. Wired uniformly by scripts/wire-tinyfish.sh — docs/08.
Linear is the human-visible command and discussion surface; Hermes remains the conversation and execution engine. Nine profile-local native platform instances receive signed Agent Session webhooks on dedicated 127.0.0.1 ports, convert them to Hermes MessageEvents, and write activities and lifecycle state back through Linear GraphQL. Cloudflare Named Tunnel is the narrow public ingress and routes only each profile's exact /linear/webhook path to loopback. Tailscale remains private/admin mesh and Remote Desktop transport; the retired Funnel sidecar is not a fallback.
The adapter verifies raw-body HMAC signatures, replay age, OAuth-pinned organization identity, rotating current/previous secrets, body limits, and separate pre-auth rate limits. SQLite semantic dedup keys use session/activity identity rather than Linear's subscription-level webhookId; human started -> completed closure reconciliation uses live actor/team/delegate read-back and a durable exactly-once final-activity ledger without rerunning the deliverable or mutating terminal state. Explicit OPS commands arriving on another channel are durably reserved and routed only to an active native AgentSession; otherwise the source channel fails closed and asks for a real Linear mention. A fresh human mention after an earlier manager session is accepted when Linear creates a distinct session ID. Tool calls publish secret-safe ephemeral thought progress from the plugin's pre_tool_call hook; no gateway-heartbeat core patch is required. Source, deployment, security, rollback, and test instructions: integrations/linear-hermes-platform/README.md.
Discovery-first: you don't commit to a game, you let the fleet surface and score opportunities, then prototype the one you pick.
flowchart LR
scout["Doruk · researcher<br/>weekly game-scout cron"]:::gen
-->|raw opportunities| score["Sarp · producer<br/>score on rubric, rank, kill hype"]:::studio
-->|ranked shortlist| pick(("🧑 You<br/>pick one")):::user
pick -->|chosen idea| prd["Ozan · writer<br/>lean 2-page PRD"]:::studio
-->|spec| build["Naz · coder<br/>Godot prototype · Metal GPU"]:::studio
build -->|a real build| gtm["Nilay · marketing<br/>Steam page · wishlists · launch"]:::gen2
classDef gen fill:#388E3C,stroke:#1B5E20,color:#fff
classDef gen2 fill:#388E3C,stroke:#1B5E20,color:#fff
classDef studio fill:#EF6C00,stroke:#E65100,color:#fff
classDef user fill:#303F9F,stroke:#1A237E,color:#fff
Only the discovery end (Doruk's scout) runs today; the rest of the chain has work once you start a real game (Phase C).
kanbancan auto-promote cards across this pipeline, but it's off until recurring hand-offs are real (docs/12).
The agent routing is deliberately simple: GPT-5.6 is primary on all nine profiles and DeepSeek is the only profile-level fallback. OpenRouter is used separately for vision fallback and Honcho embeddings; all nine Honcho text-generation surfaces use the local Codex adapter.
flowchart LR
all9["all 9 agents + cron jobs"]:::codex -->|primary| Codex["Codex OAuth · gpt-5.6 sol/terra/luna<br/>ChatGPT sub · profile-local auth stores"]:::codex
Codex -. "only agent fallback<br/>(quota window / outage)" .-> DeepSeek["DeepSeek · V4 Flash<br/>direct API · pay-per-token"]:::fallback
Honcho["Honcho memory workers"]:::infra -->|"9 text surfaces"| Routes["4 workload routes<br/>dialectic · summary · deriver · dream"]:::route
Routes -->|"weighted 8 · 4 · 2 · 1"| HCA["Honcho Codex Adapter<br/>loopback · typed config"]:::svc
HCA -->|"one upstream · gpt-5.6-luna<br/>Codex OAuth"| Codex
Honcho -->|"embeddings only"| ORd["OpenRouter<br/>text-embedding-3-small"]:::ext
classDef codex fill:#EF6C00,stroke:#E65100,color:#fff
classDef fallback fill:#1565C0,stroke:#0D47A1,color:#fff
classDef ext fill:#00796B,stroke:#004D40,color:#fff
classDef route fill:#5D4037,stroke:#3E2723,color:#fff
classDef svc fill:#00838F,stroke:#006064,color:#fff
classDef infra fill:#7B1FA2,stroke:#4A148C,color:#fff
- GPT-5.6 via Codex OAuth — primary for all nine agents and their crons. Live tiers:
gpt-5.6-solfor general/coder/researcher/writer ·gpt-5.6-terrafor assistant/finance/health ·gpt-5.6-lunafor marketing/producer. Each profile has its own writable0600 auth.jsonOAuth store; refresh/writeback is profile-local. - Reasoning effort —
mediumfor general/assistant/coder/finance/health/researcher/writer ·lowfor marketing/producer. The GPT-5.6 Sol profiles stay atmediumto control quota and cost. - DeepSeek V4 Flash (direct API key, pay-per-token, ~$0.14/$0.28 per M) — the fallback on every profile: quota-window exhaustion or a Codex outage degrades the fleet to Flash instead of stalling it.
- Auxiliary routing — all Hermes text auxiliary tasks use
auto, inheriting the profile's main GPT-5.6 model with DeepSeek as fallback. Vision also uses GPT-5.6 (terrafor Derya; otherwise the profile's own tier) withopenrouter:google/gemini-2.5-flashas fallback. Honcho's nine text-generation surfaces use the loopback Codex adapter; only embeddings remain on OpenRouter.
Full routing + the per-agent fallback chains: docs/04.
The earlier draft ran one Docker container per agent across two Macs. Dropped — full reasoning in docs/01. In short: this is single-tenant, one person, one machine, so the container isolation tax buys little; and coder needs the Mac's Metal GPU + the Godot editor, which a macOS container can't provide (no GPU passthrough). One native install also makes agent-to-agent coordination local (no HTTP/Tailscale) and the kanban board natively available if ever wanted. The trade — no kernel boundary between profiles — is managed by uniform tooling (all nine profiles host-code-capable, gated by persona guardrails), credential stripping, Tirith pre-exec scanning on general and researcher, and the website blocklist on coder and finance (docs/09).
The plan is split by concern. Original section numbers (## 1 … ## 17) are preserved, so inline cross-references like "Section 13.7" resolve across files.
- Architecture & Isolation — native single-install multi-profile; what isolation we keep and give up
- Agents — Roster, Specs & SOULs — the nine agents, dual-use vs studio + personal tier, comic SOULs
- Telegram Bots — bots, names, and 1Password-backed token wiring
- Model Providers — GPT-5.6/Codex primary, DeepSeek-only fallback, auxiliary routing
- Deployment — directories, profiles, phases, toolset hygiene, launchd
- Networking — Telegram needs no ports; Tailscale optional for the dashboard
- Memory — Hermes, Honcho & Notion boundary — hot memory, session recall, conversational memory, and durable knowledge
- Web Search — TinyFish & SearXNG — TinyFish MCP (OAuth) primary + SearXNG fallback, all 9 agents
- Security & Sandboxing — native guardrails; all nine profiles are host-code-capable
- Operations — evaluation, native upgrade, watchdog, startup ping, open questions
- Game Development Workstream — discovery-first pipeline
- Agent-to-Agent Communication — local coordination, Notion knowledge, Honcho context, and kanban
- Deployment Runbook — the what, in order, with a live build log of what's done
- Upgrade & Maintenance — the brew-upgrade checklist (plist/FDA traps), hardened backups, watchdog v2, session-store hygiene, config-git rollback, skill-consolidation blast radius
- Linear native platform adapter — Agent Sessions, OAuth, signed webhook ingress, semantic dedup, Stop lifecycle, tests and rollback
- Codex usage Telegram command — canonical
/codex_usageplugin, official rate-limit RPC, nine-profile restore installer and tests - Honcho Codex OAuth adapter — local OpenAI-compatible transport from Honcho inference routes to Hermes Codex OAuth, with tests, probes and rollback
- Credential Management — 1Password canonical architecture, exceptions, rotation and incident response
- Notion — Knowledge & Reporting Plane — durable knowledge, plans, decisions, reports, auth boundary, and hygiene
# 1. Telegram: @BotFather → /newbot ×9 (general_<you>_bot … health_<you>_bot; slug-based, rename-safe)
# 2. store each bot/provider credential in the correct 1Password item and map it by ID:
hermes -p <profile> secrets onepassword set TELEGRAM_BOT_TOKEN 'op://<vault-id>/<item-id>/<field-id>'
hermes -p <profile> secrets onepassword status
# repeat only for credentials that profile needs; see docs/15-credential-management.md
# 3. install Hermes natively + bring up one profile, then the rest:
# follow docs/13-deployment-runbook.md (keys → install → bots → Phase A/B/C)
# 4. web stack — TinyFish (primary, OAuth) + SearXNG (fallback), all agents:
./scripts/wire-tinyfish.sh # per-profile OAuth (own browser consent each — tokens are NOT shared) + SearXNG fallback + restart
# 5. verify the shared Notion OAuth/CLI plane without printing credential state:
NOTION_KEYRING=0 NOTION_HOME=/Users/YOU/.hermes/profiles/general/home/.notion ntn whoami
# 6. fleet-wide Telegram /codex_usage command (dry-run, then apply; no restart performed):
python3 integrations/codex-usage/install.py
python3 integrations/codex-usage/install.py --apply1Password is the single source of truth for static credentials. Profile configs contain only ID-based op:// references. Bootstrap identity and writable OAuth stores — including the shared Notion CLI OAuth state — are the documented local 0600 exceptions; see Credential Management and Notion — Knowledge & Reporting.
flowchart LR
A["Phase A ✅<br/>native install · Derya + Doruk<br/>launchd · watchdog · scout cron"]:::done
--> B["Phase B ✅<br/>Tuna · Naz · Ozan · Sarp · Nilay<br/>Honcho · SearXNG · TinyFish · fallback"]:::done
--> C["Phase C ⏳<br/>first real game:<br/>idea → PRD → Godot prototype"]:::next
classDef done fill:#388E3C,stroke:#1B5E20,color:#fff
classDef next fill:#7B1FA2,stroke:#4A148C,color:#fff
- Phase A ✅ — native install, Derya + Doruk under launchd, per-profile state proven, watchdog live-tested, weekly game-scout cron delivering.
- Phase B ✅ — all nine agents live; self-hosted Honcho shared memory (cross-agent recall proven); all 9 agents on TinyFish (OAuth) primary + SearXNG fallback —
⚠️ OAuth tokens are per-profile, never copied. Agent model fallback is DeepSeek V4 Flash; OpenRouter remains the vision-fallback and Honcho-worker route. - Phase C ⏳ — when you start a real game: a picked idea → lean PRD (Ozan) → Godot prototype (Naz) on the Mini's GPU → go-to-market (Nilay).
Pending follow-ups (all pull, none blocking): Sarp weekly score-cron once digests accumulate.
flowchart TB
root["📦 hermes-setup"]:::root
root --> readme["README.md · this file"]:::doc
root --> docs["docs/ · 01-15<br/>architecture · operations · live runbooks"]:::doc
root --> scripts["scripts/"]:::svc
root --> integrations["integrations/<br/>native adapters + Codex usage command"]:::svc
integrations --> lin["linear-hermes-platform/<br/>native Linear platform adapter"]:::svc
integrations --> cu["codex-usage/<br/>fleet-wide /codex_usage plugin + installer"]:::svc
integrations --> hc["honcho-codex-adapter/<br/>typed config + compatibility-gated backend"]:::svc
scripts --> sb["setup-bots.sh<br/>retired plaintext fan-out path"]:::svc
scripts --> wt["wire-tinyfish.sh<br/>TinyFish MCP (per-profile OAuth) + SearXNG fallback · all 9"]:::svc
scripts --> no["notify-online.sh<br/>per-bot 'online' ping at fleet boot (launchd)"]:::svc
scripts --> bs["profile-backup-quick.sh<br/>daily native quick snapshots · all 9 profiles"]:::svc
scripts --> bh["backup-honcho.sh<br/>atomic Honcho pg_dump + gzip verification"]:::svc
scripts --> ex["bot-tokens.env.example<br/>retired migration reference"]:::svc
classDef root fill:#303F9F,stroke:#1A237E,color:#fff
classDef doc fill:#1976D2,stroke:#0D47A1,color:#fff
classDef svc fill:#00838F,stroke:#006064,color:#fff
State that lives outside the repo: 1Password vault items (canonical static credentials), ~/.hermes/profiles/<slug>/ (each agent's config with ID-based op:// references, SOUL, sessions, memory, writable OAuth stores, SQLite ledgers and local state-snapshots/), profile-scoped Keychain bootstrap identities consumed by the official 1Password SDK, the nine deployed Linear plugin copies, the deployed ~/.hermes/plugins/codex-usage copy and profile symlinks (canonical credential-free sources are in this repo), ~/.hermes/honcho.json, ~/.hermes/scripts/, ~/.hermes/services/honcho-stack/ (Docker), verified Honcho dumps in ~/.hermes/backups/honcho/, and launchd plists in ~/Library/LaunchAgents/ai.hermes.*. Local quick snapshots are rollback state, not off-host disaster recovery.
- 1Password is canonical. Never put real credentials in the repository, chat, clipboard, Notion, Linear,
config.yaml,bot-tokens.env, or profile.envfiles. Hermes resolves ID-basedop://references at startup. Only the 1Password bootstrap identity and refresh/writeback OAuth stores remain local0600exceptions (details). - Native = no container boundary, 9/9 shell-capable by design. A
terminal/execute_codecommand runs on your real Mac. All nine profiles resolve both tools; approvals areoff. The live compensating controls are persona guardrails + credential stripping, Tirith ongeneralandresearcher, and the website blocklist oncoderandfinance— not a shell-restriction policy (details). - Telegram is the default front door and needs no open ports (gateways connect outbound). All nine profiles additionally accept Linear Agent Session webhooks through exact-path Cloudflare Named Tunnel routes; each native adapter still binds only its dedicated
127.0.0.1port and validates HMAC, replay age, organization identity and rate limits. Don't expose the optional Hermes HTTP API/dashboard publicly (details). - Services bind loopback only — Honcho
127.0.0.1:8000, Honcho Codex Adapter127.0.0.1:18080, SearXNG127.0.0.1:8888, and Linear adapters127.0.0.1:8787–8793,8796–8797; Cloudflare is the narrow exact-path public ingress, not a LAN listener, while Tailscale remains private/admin mesh. - When something breaks: gateway-down alerting is a dumb launchd watchdog, no agent involved (docs/10 §14.5); the fleet-wide stop + key-rotation drill is docs/09 §13.8.