Matrix integration in the Electron app — options & tradeoffs

[dmarzzz]

Context

The OS app currently talks to swf-node over 127.0.0.1:7777 for peer search. Open question: how should the app talk to the cohort Matrix server (mtrx.shaperotator.xyz, Phala TEE, source at teleport-computer/shape-rotator-matrix)?

Prior art worth re-reading first:

• docs/MATRIX.md (currently on a worktree, not main) — onboarding flow, signup-code mechanics, and the explicit warning that programmatic E2EE is hard: mautrix-python is the recommended SDK; matrix-nio dead-ended on cross-signing.
• apps/os/swf-node.js — the supervisor pattern (state machine, IPC events, bundled binary) we'd likely mirror for any in-process daemon.
• matrix-bot-setup skill — currently a stub.

Two distinct use cases that should be named up front, because they pull in opposite directions:

• A. User-facing client: render rooms, send messages, read history in the OS app's renderer.
• B. Agent / bot channel: the app (or a sidecar) acts as the user's automated identity — posts status, listens for commands, reacts to events.

(A) cares about UX, (B) cares about reliable E2EE on a headless account. Same homeserver, very different shapes.

---

Client-side options

1. matrix-js-sdk in the renderer

Cheapest path. npm i matrix-js-sdk, instantiate in renderer, sync over HTTPS.

• 👍 ~1 day to working send/receive.
• 👎 Credentials + E2EE store live in renderer IndexedDB. With our current preload (contextIsolation on, no nodeIntegration), the SDK works in-browser fine, but secrets aren't isolated from page JS.
• 👎 E2EE in JS is the known-hard area docs/MATRIX.md calls out. For headless/agent use (B), this is the worst option.

2. matrix-js-sdk in main, IPC bridge to renderer

Mirrors the swf-node supervisor pattern.

• A matrix-node.js module in main owns the MatrixClient, persists tokens in userData/, exposes IPC (matrix:login, matrix:send, matrix:onTimeline) alongside the existing getSwfNodeStatus etc.
• E2EE via @matrix-org/matrix-sdk-crypto-wasm, WASM bundled through electron-builder extraResources (same mechanism as the swf-node binary).
• 👍 Tokens out of renderer; matches existing architecture.
• 👎 Still the JS-crypto path docs/MATRIX.md warns against. Likely fine for (A), risky for (B).
• Est: 2–3 days for login + room list + send/receive; +1–2 for E2EE.

3. mautrix-python sidecar, supervised like swf-node

Bundle a Python mautrix process as an extra resource; main spawns + supervises it; renderer talks to its local HTTP/WS surface.

• 👍 Uses the SDK we already know works for our headless accounts (knock-approver is the reference impl).
• 👍 Cleanly separates (A) renderer client from (B) agent identity.
• 👎 Adds Python to our build matrix — non-trivial for Win/Linux packaging (we already ship Python-derived swf-node binaries, so the muscle exists, but it's another moving part).
• Est: 3–5 days end-to-end.

---

Server-side options (we own the homeserver)

These don't replace a client-side choice — they make whichever client-side option we pick dramatically easier.

4a. Pantalaimon E2EE proxy

Pantalaimon is a Matrix-developed transparent proxy that handles E2EE itself and exposes the plain client-server API.

• Bundle a per-user Pantalaimon either (i) on the homeserver host as a per-account proxy or (ii) shipped inside the OS app and run locally.
• Renderer (option 1) or main-process client (option 2) speaks plain HTTP, no crypto WASM, no key store.
• 👍 Eliminates the JS E2EE problem entirely.
• 👎 If hosted alongside the homeserver, keys live there — degrades the E2EE threat model (though the TEE deployment recovers some of it). If shipped locally, we're packaging Python anyway, at which point option 3 becomes more attractive.

4b. Application Service registration

Register the OS app's machine identity as an Application Service on mtrx.shaperotator.xyz.

• AS users get a privileged token, can puppet namespaced users (@_srwk_*:mtrx.shaperotator.xyz), and live in non-E2EE namespaces by convention.
• Good fit for (B) agent channel: status broadcasts, presence, structured events to a dedicated #srwk-bot-noise room.
• 👎 Requires homeserver config (operator action, low cost since we control it).
• 👎 Not a fit for (A) — humans still want E2EE in cohort rooms.

4c. Non-encrypted cohort rooms

Configure #announcements, #general, #bot-noise as non-encrypted from the start.

• 👍 Any Matrix client (including option 1 in the renderer) works with zero crypto work.
• 👍 The homeserver is in a TEE — transport confidentiality is provided by TLS + the attestation story, so the marginal value of E2EE on top is debatable for cohort-wide rooms.
• 👎 DMs and small-group rooms still want E2EE; this is rooms-by-room.
• 👎 Reversal is hard once messages exist — needs to be a setup-time decision.

4d. Custom shim API on the homeserver host

A small service co-located with Synapse exposing cohort-opinionated endpoints (POST /srwk/status, GET /srwk/feed, etc.) that proxy to the Matrix client-server API with an AS token.

• 👍 Renderer becomes trivial — just fetch() calls, no Matrix SDK at all.
• 👎 We're now maintaining a bespoke API. Couples us tighter to the cohort homeserver and makes it harder to ever federate this with off-cohort Matrix accounts.

4e. Sliding Sync proxy

Run matrix-org/sliding-sync alongside Synapse.

• Orthogonal to the E2EE question, but makes building a custom client cheaper — incremental room-list sync instead of full /sync deltas.
• Worth doing eventually regardless of which client option we pick.

---

Recommendation

For (A) user-facing client: option 2 (matrix-js-sdk in main, IPC bridge) combined with 4c for cohort-wide rooms. The crypto WASM path is fine if the only rooms that need it are DMs and small groups. Mirrors our existing supervisor pattern; tokens stay out of the renderer.

For (B) agent channel: option 3 (mautrix-python sidecar) gated by 4b (Application Service namespace). This is the path the knock-approver already validated; the AS registration prevents agent-noise from leaking into human-encrypted rooms.

Net work: roughly 1 week for (A) end-to-end, plus separate scoping for (B). Server-side changes (4b/4c) are operator actions on teleport-computer/shape-rotator-matrix — small cost, large payoff.

Open questions

• Is the AS namespace something Andrew is willing to grant per app, or does this need a cohort-wide convention first?
• Are cohort rooms currently E2EE? (If yes, 4c isn't retroactive; if no, we've already paid the decision.)
• Do we want one shared bot identity per user, or one per app surface (OS app vs. field-kit rotate vox etc.)?

cc @amiller for server-side feasibility on 4b/4c.

[dmarzzz]

Architecture proposal: cohort-OS unified surface

A design doc for the next layer of Shape Rotator OS: a single app that hosts Matrix chats, agent runtimes (Centaur-shaped), private transcripts, and gated access to cohort databases — all unified by object-capability authorization as the single primitive.

This is a proposal, not a decision. Open questions are tagged at the bottom.

---

Design thesis

Every protected thing in this system — a transcript, a database row, a Matrix room, an LLM API key, a Centaur tool, a published bundle — is reached by presenting an unforgeable capability token, not by "user X has role Y." The token is the authority. It's attenuated when delegated to agents, time-bounded by default, revocable, and bound to the cohort's identity layer (Matrix). Centaur's existing iron-proxy pattern is already an object-capability in disguise — formalizing the model lets us reuse one auth mechanism across humans, agents, and tools.

---

Six planes

┌──────────────────────────────────────────────────────────────────────┐
│                       Shape Rotator OS (Electron)                    │
│   ┌──────────────┐  ┌───────────────┐  ┌──────────────────────────┐  │
│   │ Matrix pane  │  │ Agent threads │  │ Transcripts + DB consoles│  │
│   └──────┬───────┘  └───────┬───────┘  └────────────┬─────────────┘  │
│          │                  │                       │                │
│   ┌──────┴──────────────────┴───────────────────────┴─────────────┐  │
│   │  Local cap-wallet (encrypted, OS keychain unlock per session) │  │
│   └───────────────────────────┬──────────────────────────────────-┘  │
└───────────────────────────────┼──────────────────────────────────────┘
                                │  HTTPS + capability header
                ┌───────────────┼───────────────────┐
                │               │                   │
        ┌───────▼──────┐  ┌─────▼──────┐   ┌────────▼──────────┐
        │   Identity   │  │ Authority  │   │    Resource       │
        │  (Matrix HS) │◄─┤  (mint /   │   │ (transcripts, db, │
        │              │  │   revoke)  │   │  tools, blobs)    │
        └──────────────┘  └─────┬──────┘   └────────▲──────────┘
                                │                   │
                                │  delegated caps   │
                          ┌─────▼───────────────────┴────────┐
                          │       Execution (Centaur)        │
                          │  ┌────────────┐  ┌────────────┐  │
                          │  │ sandbox pod│  │ iron-proxy │  │
                          │  │  (agent)   │──┤ (cap-aware)│──┼──→ outbound
                          │  └────────────┘  └────────────┘  │
                          └──────────────────────────────────┘
                          ┌──────────────────────────────────┐
                          │ Ingress: Matrix bridge, Slack,   │
                          │ Electron app, /api               │
                          └──────────────────────────────────┘

Identity — mtrx.shaperotator.xyz is canonical. The Authority service trusts Matrix's user IDs and uses Matrix access tokens (or signed challenges over m.login.application_service for app-presented identity) as the proof-of-user.

Authority — A small service that mints, attenuates, and revokes capabilities. Stateless except for the revocation list and the root signing key (sealed in TEE alongside the homeserver).

Resource — Anything gated. Transcripts service, db-credential broker, Centaur tool gateway, object-store signed-URL minter, future-arbitrary cohort services. All speak the same cap header.

Execution — Centaur, modified so iron-proxy is cap-aware: it carries delegated caps for the sandbox and attaches them to outbound requests, verifying caveats locally before egress.

Ingress — Matrix bridge bot (mautrix-python, modelled on the knock-approver), Slack (Centaur's existing path), and direct API from the Electron app.

App — The OS app holds a local cap wallet: an encrypted at-rest store of the user's root caps, unlocked per-session via OS keychain. Renderer never sees raw caps; main process attaches them to outbound IPC the same way the existing swf-node agent token works.

---

The capability primitive

Choice: macaroons. Battle-tested (libmacaroons in C/Python/Go/Rust), well-understood semantics, supports first-party and third-party caveats, no need for a PKI per resource. We considered UCANs (DID-based, more modern, native to the decentralized identity stack) — they're a strong "future evolution" candidate if the cohort ever decentralizes off a single homeserver. For now, one Authority service issuing macaroons is simpler.

Anatomy of a cap (conceptual):

macaroon {
  location:  cohort.shape-rotator.xyz
  identifier: cap_01HXYZ... (random; lookup key in Authority revocation index)
  caveats:
    - user = @dmarz:mtrx.shaperotator.xyz
    - resource = transcripts:*
    - op IN (read, list)
    - subject_owner IN (@dmarz:mtrx.shaperotator.xyz)
    - exp = 2026-05-22T00:00:00Z
    - nonce = nb_01HXY... (for revocation)
  signature: HMAC chain bound to root cohort key
}

Caveat language — keep it dumb. First-party caveats are key/value or simple comparisons, evaluated by each resource. Avoid Datalog-style policy languages early; revisit if expressiveness becomes the bottleneck.

Presentation — Authorization: Macaroon <base64-token> on every protected request. Resources verify signature locally using a shared verification key (HMAC with the Authority's root key, distributed to resources at deploy time and rotated quarterly).

Delegation — Cap holders can mint narrower caps by appending caveats. The signature chain ensures attenuation is one-way: you can never widen, only narrow.

Revocation — Two-tier:

• Soft (cheap, eventually-consistent): nonce in a published bloom filter / sorted list. Resources fetch every few minutes. Fine for "user lost a device" or "interviewee withdrew consent next week."
• Hard (expensive, strongly-consistent): Authority verifies-with-online-check via a third-party caveat (requires Authority signature within 30s). Used for high-stakes resources like production DB write caps.

---

Subsystem: transcripts

Storage — Object store (Phala-host disk for v0; R2/S3 if we outgrow). Each transcript is { id, content_blob_url, sealed_metadata, owner, subject, created_at, consent_state }. Content is symmetrically encrypted; the symmetric key is wrapped per-recipient by the Authority and stored alongside the cap grant — not on the blob. This means a leaked blob is useless without an active cap exchange.

Data model

transcript {
  id: tr_01HXYZ
  owner: @dmarz:mtrx.shaperotator.xyz
  subject: @amiller:mtrx.shaperotator.xyz   # the interviewee
  blob_url: s3://transcripts/tr_01HXYZ.enc
  blob_key_wrap: { recipient_cap_id → wrapped_key }
  consent_state: { granted_at, revoked_at?, scope }
  metadata: { interview_date, tags, references[] }
}

Access pattern (read)

1. Caller presents read(transcripts:tr_01HXYZ) cap to Transcripts service.
2. Service verifies cap signature + caveats + revocation status.
3. Service mints a short-lived signed URL (TTL: 60s) for the blob.
4. Service returns { signed_url, wrapped_dek }.
5. Caller fetches blob, unwraps DEK via Authority (one round-trip; could be cached for session).
6. Caller decrypts content locally.

Consent surface — The subject (interviewee) holds a permanent consent cap for their own transcripts. It exposes: list-readers (who currently has access), revoke-reader (adds a nonce to the revocation list), and freeze (mark transcript as "no new readers"). This is a first-class UI in the OS app's Transcripts pane when viewing a transcript you're the subject of.

Backup & key recovery — Authority's root key is shamir-split across cohort stewards (Andrew + 2 others, threshold 2-of-3). Same as the cohort-keys.json story but with explicit recovery procedure.

---

Subsystem: database credentials

Pattern: short-lived broker, not stored credentials. Centaur's iron-proxy already proves the model — agents reference creds by placeholder, proxy resolves them on the wire. We extend it to humans-in-the-app and to per-row caveats.

Components

• Cred Broker — a service that holds long-lived DB connection details and issues short-lived DB tokens (e.g., Postgres SET ROLE with an expiry, or per-request connection from a pool that's pinned to a row-level-security context).
• DB-side enforcement — Postgres RLS policies keyed off the SET-ROLE the broker chooses. The cap tells the broker which role to grant; the broker tells Postgres; Postgres enforces.
• Audit log — every cred exchange + every query the broker brokers is logged to an append-only store. Queryable by stewards.

Worked flow: agent runs an analytics query

1. User in OS app: "Find every cohort member who hasn't been interviewed yet."
2. App requests an attenuated cap from local wallet:
   • parent: user's db.cohort.read cap
   • attenuations: tables IN (people, interviews), cols NOT IN (private_notes), exp = now + 5min, purpose = 'agent: identify-uninterviewed'
3. App calls POST /agent/spawn with the cap in the request body (not stored in sandbox env).
4. Centaur routes the cap to the sandbox's iron-proxy companion.
5. Agent in sandbox issues SELECT ... FROM cohort_db.people p LEFT JOIN ... against http://db.local/query.
6. iron-proxy intercepts, validates cap caveats against the SQL (parse + match against allowed tables/cols — small policy engine), gets a short-lived role token from Cred Broker, forwards.
7. Postgres RLS enforces the role constraints.
8. Result returns through proxy to sandbox to agent to thread events.
9. Cap expires; sandbox can't reuse it.

The sandbox never has connection strings, role passwords, or even direct network access to the DB host. Only the proxy does, and only with caps that match.

---

Why object capabilities are the right primitive here

Three properties that make this not over-engineering:

1. Delegation is the everyday case, not the exception. Every time the user spawns an agent, they're delegating some of their authority. Caps make this explicit and bounded. ACLs make every delegation a configuration change.
2. Attenuation is local. A user delegating "search my interviews from 2026" to an agent doesn't need to call Authority — they just append a caveat and re-sign. Authority is hit only for mint and revoke.
3. No ambient authority. A bug in an agent can't reach for "the cohort DB" because the sandbox has no ambient identity. It can only do what its caps let it do. This is the same property that makes the iron-proxy pattern feel right; we're just naming it.

The alternative — adding RBAC or ABAC to every resource — works, but you'll end up writing the same policy-as-claim model badly six times across six services. One cap library, one verification routine, six resources.

---

Implementation phases

Phase 0 — pick the primitive (1 week)

• Pin macaroons vs. biscuit vs. UCAN with a small spike. Macaroons recommended.
• Stand up Authority service skeleton with mint/verify/revoke endpoints, in-memory.
• Define the caveat vocabulary (initial set: user, resource, op, exp, nonce, purpose).
• Bind Authority to Matrix identity via homeserver-trusted access tokens.

Phase 1 — cap-aware Centaur (2 weeks)

• Fork iron-proxy (or contribute upstream) to read caps from request context, validate caveats, attach on outbound.
• Modify /agent/spawn to accept caps; /agent/execute to scope them to thread lifetime.
• Sandbox image gains a cap("name") helper analogous to secret("name").
• Backwards-compatible: caps absent → fall back to current iron-proxy secret model.

Phase 2 — Transcripts service (2 weeks)

• Bare service: object store + Postgres metadata + cap-gated read/list/grant.
• Encrypt-at-rest; key wrap per cap grant.
• Consent surface (subject sees & revokes their own readers).
• OS app Transcripts pane: list, view, grant, revoke, see-who-can-see.

Phase 3 — Cred Broker + DB access (2 weeks)

• Broker service issues short-lived tokens; RLS policies on the cohort DB.
• iron-proxy gains SQL-aware caveat enforcement.
• OS app DB console: caps-gated query pane, audit log view.

Phase 4 — Matrix client + agent threads side-by-side in the app (~3 weeks)

• Per issue Matrix integration in the Electron app — options & tradeoffs #120 options 2 + 4b: matrix-js-sdk in main, IPC bridge, MSC/AS namespace for agent-noise rooms.
• Agent threads as a peer pane; cross-link from Matrix messages (!ask from a room kicks an agent thread).

Phase 5 — local cap wallet (parallel-izable, ~1 week)

• OS keychain integration, encrypted at-rest cap store, session unlock.
• Deviceauthz: each device gets its own root cap chain so revocation is per-device.

Total: ~10–11 weeks of focused work for the full picture. Each phase is independently useful; (0) and (1) are the unlock for everything else.

---

Risks and open questions

Risks

• Cap leakage = full access for that cap's scope until revoked. Mitigations: short default TTLs, device-bound root caps, soft-revocation list polling. But this is the same risk as JWTs and we accept it there.
• Caveat language sprawl. Adding a new caveat is a coordination problem across all resources. Mitigation: keep the vocabulary closed and versioned; major-version bump for breaking adds.
• Authority is a SPOF. Mitigation: read path doesn't need Authority (caps verify locally); only mint + revoke. Stewards can mint offline if Authority is down.
• Operator burden. Three new services (Authority, Transcripts, Cred Broker) plus modified Centaur. Real cost. Sequence so the cohort-shared TEE deploy story doesn't grow unmanageably.

Open questions

1. Root key custody. Shamir-split among stewards (2-of-3) seems right, but who are the 3? Andrew + ?
2. Per-resource verification keys. One root + HMAC-derived per-resource sub-keys, or independent keys per resource? First is simpler, second is more compartmentalized.
3. Caveat enforcement for SQL. Are we prepared to ship a small SQL parser + policy engine in iron-proxy? Or do we lean on Postgres RLS exclusively and treat caps as a row-key selector?
4. Cap revocation UX. When a user revokes "interviewee Bob's access to my transcripts," does that fan out across all of Bob's outstanding delegations? Macaroons say yes (revoke the nonce, all derivatives die). Worth confirming this is the desired semantic.
5. Off-cohort identities. Some interviewees aren't in the cohort and don't have Matrix accounts. They need consent caps without an mtrx.shaperotator.xyz user ID. Either: external identity binding (email + DID), or: their consent caps are held in trust by the steward.
6. Does the Electron app embed any of these services for offline use, or is it strictly a client? Strict client is simpler. Offline-capable means we're back in the local-Centaur conversation from earlier.

---

TL;DR

One auth primitive (capabilities) across one identity layer (Matrix). Three new services (Authority, Transcripts, Cred Broker), one modified service (cap-aware Centaur/iron-proxy), one expanded app surface (OS app with Matrix + agents + transcripts + DB consoles). Phased so each step is shippable on its own. Object capabilities aren't a crazy idea here — they're the model that already matches how Centaur thinks about secrets, just generalized.

[dmarzzz]

Update 1 — Centaur reuse: it's better than expected

Checked the actual repo (paradigmxyz/centaur). The earlier design assumed we'd be writing this from scratch. We won't be.

Licensing

Apache-2.0 OR MIT, dual-licensed. The LICENSE file uses SPDX dual-license syntax (SPDX-License-Identifier: Apache-2.0 OR MIT), which is why GitHub's API reports NOASSERTION — but the file text is explicit: "Licensed under either of Apache License, Version 2.0 / MIT license at your option." Strictly more permissive than just MIT. Clean to embed, fork, modify, redistribute.

The intended deployment shape: three nested repos

From docs/pages/what-is-centaur.mdx and docs/pages/extend/overlay.mdx:

1. paradigmxyz/centaur — the kernel (control loop, workflow engine, sandbox lifecycle). Use as-is.
2. Org overlay repo — shared business logic (tools, workflows, skills, personas, prompts). Mounted via env vars (TOOL_DIRS=/app/tools:/app/overlay/org/tools, same for WORKFLOW_DIRS). No fork.
3. App repos — Slackbot, Matrix bridge, etc. that wire an overlay to a frontend.

This is exactly what we want. We never modify the kernel for the common case.

What we get for free (running the kernel)

Component	Path	Notes
API	services/api	FastAPI + Postgres, the spawn/message/execute/events/release lifecycle
iron-proxy	services/iron-proxy	mitmproxy-based, addon system available for hooks
Sandbox	services/sandbox	K8s pods + warm pool
Slackbot	services/slackbot	Reference ingress; keep, replace, or peer with a Matrix bridge
Harnesses	harness/claude, harness/codex	Claude Code + Codex ready to run inside the sandbox
Tool catalog	tools/{business,comms,crypto,infra,media,personas,productivity,research}	Starter tools across categories
SDK	centaur_sdk/	Python client lib
Deploy	contrib/chart/	Helm chart

What's overlay-shaped (no fork, just a separate repo)

• Cohort-specific tools — tools/cohort/{transcripts,db,matrix-ops,...}.py
• Cohort-specific workflows under workflows/
• Cohort skills under .agents/skills/
• Personas / prompts / system messages

What's net-new services (sit alongside Centaur, the overlay's tools call them)

• Authority (cap mint/verify/revoke) — independent service
• Transcripts content service — independent
• Cred Broker — independent

Where forking might bite — but probably doesn't

• Cap-aware iron-proxy. Three options in order of cost:

  • (a) Run a small cap-validation sidecar in front of iron-proxy. Validates the macaroon + caveats; iron-proxy then does its existing credential injection downstream. Zero kernel modification.
  • (b) Contribute a hook upstream — mitmproxy already supports addons, so this is structurally easy. Likely accepted upstream since "external authz" is a common ask.
  • (c) Fork iron-proxy. Only if (a) and (b) fail.

  Plan of record: ship (a) for v0, attempt (b) once stable, never (c).

• Matrix ingress. Add services/matrix-bridge as a peer to services/slackbot (mautrix-python, modelled on the cohort's existing knock-approver). The kernel API doesn't care which ingress it gets called from. Could be contributed upstream as a second reference ingress.

• Cap-passing through the API. The API already accepts metadata in spawn/message; caps fit as a header (Authorization: Macaroon ...) and propagate into the sandbox env the same way secret() placeholders do today. No kernel change expected.

Revised phase plan

Phase 1 ("cap-aware Centaur") in the previous comment compresses meaningfully:

• Phase 0 (1w) — pick primitive (macaroons), stand up Authority skeleton, bind to Matrix identity. Unchanged.
• Phase 1 (1w, was 2w) — deploy Centaur kernel via Helm, create the org overlay repo skeleton, ship the cap-validation sidecar in front of iron-proxy.
• Phase 2 (2w) — Transcripts service + first overlay tool (tools/cohort/transcripts.py) that calls it.
• Phase 3 (2w) — Cred Broker + RLS + tools/cohort/db.py.
• Phase 4 (2–3w) — Matrix bridge ingress (services/matrix-bridge) + OS app Matrix pane via matrix-js-sdk in main.
• Phase 5 (1w) — local cap wallet in the OS app (OS keychain, encrypted at rest).

Net: roughly 8–9 weeks instead of 10–11, with zero kernel forks.

---

Update 2 — Hermes is a second execution plane

I missed this in the original design. The OS app already has Hermes — a local-only Q&A surface at apps/os/src/hermes/{index.html,app.js}, opened from the app menu via createHermesWindow in main.js.

What Hermes is today

• Detects Ollama on 127.0.0.1:11434, lists installed models, prefers Hermes-family (hermes3, nous-hermes2, openhermes) but falls back to any model.
• Grounds against the bundled cohort-surface.json (with live fetch from raw.githubusercontent.com as the freshness path).
• Strict CSP — only loopback + GitHub allowed. "local-only · prompts + responses never leave your machine."

Architecturally this is a second execution plane with very different trust properties from Centaur:

	Centaur sandbox	Hermes / local Ollama
Where it runs	K8s pod, isolated	User's OS process space
Network access	Through iron-proxy (mediated)	Direct loopback to Ollama
Credentials	Injected by iron-proxy, never seen by code	None (model has no outbound auth)
Audit trail	Every cap exchange + tool call logged	Currently zero logging
Multi-tenant	Yes, cohort-shared	No, per-user-per-machine
Tool catalog	Full overlay (transcripts, DB, ...)	Just the cohort surface today
Offline	No	Yes

These two planes have to coexist in the unified surface — they're complementary, not redundant. Centaur is for cohort-shared, audited, multi-tenant work; Hermes is for the user's own questions about the user's own data, with the strongest privacy story (nothing ever leaves the machine).

Auth complications when Hermes is added to the cap model

These are the real headaches. None are deal-breakers; each shapes a design choice.

1. Local inference is post-decryption. Caps gate fetching transcripts. Once the OS app has fetched a transcript with a cap, the plaintext sits in the renderer process and is handed to Ollama for grounding. From that moment, the cap layer is bypassed. "Decryption is the revocation event" — once Hermes has seen it, Hermes has seen it forever, even if the cap is revoked the next second. Worth being explicit about this in the cap policy: certain transcripts may have a local_inference_allowed: false caveat, in which case the OS app refuses to feed them to Hermes regardless of read auth.

2. No sandbox = no enforcement. Centaur's caps are enforced because the sandbox can only egress through iron-proxy. Ollama has no such constraint — once a prompt is in the model's context window, the model can do anything with it. We trust the model. Reasonable for open-weight Hermes-family models that we know aren't going to phone home; less reasonable as a general property. Implication: caps issued for local-execution-eligible resources should be narrower than caps for Centaur-execution-eligible resources.

3. Audit blind spot. Centaur logs every cap exchange and tool call. Local Ollama doesn't. If a steward asks "what did user X's agents do with transcript Y?", local Hermes interactions are invisible. Three options:

• Accept it — local inference is fundamentally unauditable; cohort policy reflects this.
• Local audit log — OS app writes a signed log of cap-used-for-local-inference events to a tamper-evident store; uploaded to the Authority service periodically. Not as good as remote audit, but better than nothing.
• Restrict local inference via cap — caps for the most sensitive resources are marked remote_only, so they can't be used to ground local Hermes prompts at all.

4. Cap presentation in a local-process model. Centaur's iron-proxy validates caps at the network boundary. Hermes has no network boundary to the model — it's loopback HTTP to a daemon in the same trust zone. The validation has to happen in the OS app's main process before any data is handed to Ollama. This means the cap wallet must be wired into Hermes (currently it's a renderer-side HTML page with direct fetch). Practical change: Hermes IPCs to main for any data fetch beyond the public cohort surface; main attaches caps, validates response, returns plaintext to Hermes. Ollama call itself remains loopback and uncapped.

5. Identity for posting back. If Hermes generates a useful answer and the user wants to share it ("post Hermes' summary to #cohort"), Hermes itself has no identity — it can't sign as the user. The OS app's main process is the signer (it holds the Matrix access token and the cap wallet). This is fine architecturally but worth saying — Hermes is advisory, never actor.

6. Tool parity, or not. Centaur agents get the full overlay tool catalog (transcripts service, DB broker, matrix-ops). Hermes today has just the cohort surface. Two paths:

• Symmetric — give Hermes a tool-calling loop that calls the same overlay-tool HTTP endpoints (via the main-process cap wallet). Hermes becomes a real local agent with cap-gated tools. Implementation cost: medium; you're building a tool-use loop on top of Ollama (some models support function calling natively, most don't reliably).
• Asymmetric — Hermes stays Q&A-with-cohort-surface, Centaur is for "real" agent work. Implementation cost: zero. Probably right for v0.

Plan of record: stay asymmetric until there's a concrete cohort use case Hermes uniquely solves (offline work being the obvious one).

7. Model trust assumption made explicit. The cap policy implicitly trusts that locally-loaded Ollama models won't exfiltrate via side channels (DNS, encoded outputs that the user later shares, etc.). This is reasonable for open-weight Hermes-family models with no agentic loop. It becomes unreasonable if Hermes later gets tool-calling and outbound HTTP. At that point Hermes effectively needs the same iron-proxy-style network mediation Centaur has — at which point you might as well run it inside a local Centaur sandbox.

8. Multi-user delegation breaks. Caps are designed to be delegable — I give my agent (or another cohort member) a narrower cap, they use it. Local Hermes runs only on the cap-holder's machine. There's no path to "delegate Hermes use to someone else." So caps marked for local-inference are implicitly non-delegable in practice. The cap model should be explicit: if a caveat says local_inference_allowed, delegation drops that caveat in the child cap (you can't pass through what you can't enforce in the delegate's environment).

Where Hermes lands in the architecture

Adding the local execution plane as a co-equal of Centaur's sandbox plane:

┌────────────────────────────────────────────────────────────────────┐
│                     Shape Rotator OS (Electron)                    │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │              Local cap wallet (main process)                │   │
│  └─────────┬───────────────────────────────────────┬───────────┘   │
│            │                                       │               │
│   ┌────────▼─────────┐                   ┌─────────▼─────────┐     │
│   │  Hermes (local)  │                   │ Centaur client    │     │
│   │  ┌────────────┐  │                   │ (matrix pane,     │     │
│   │  │ Ollama 11434│  │                   │  agent threads,   │     │
│   │  └────────────┘  │                   │  transcripts ui)  │     │
│   └──────────────────┘                   └────────┬──────────┘     │
└──────────────────────────────────────────────────-│-────────────-──┘
                                                    │ caps
                                          ┌─────────▼──────────┐
                                          │  Centaur (remote)  │
                                          │  + Authority       │
                                          │  + Transcripts svc │
                                          │  + Cred Broker     │
                                          └────────────────────┘

The cap wallet is the unifying point — both planes pull from it. The main process is the only thing that handles raw caps. Hermes and the Centaur client both get plaintext from the wallet via IPC after caps have been presented and resources fetched.

Open questions Hermes adds

7. local_inference_allowed as a default caveat — opt-in or opt-out? If opt-in (caps default to remote-only), Hermes' usefulness shrinks but the trust model is tighter. If opt-out, the default policy is permissive and tightening it later is hard. I lean opt-in for transcripts (sensitive), opt-out for DB read caps (the data already had to pass RLS, you trust the row).

8. Should the OS app unify the agent thread surface across Centaur and Hermes? A user asking "ask hermes" vs "spawn a centaur agent" vs "ask via my matrix bot identity" are three different routes today. Could be one UI with a backend selector ("run on: local · cohort · matrix-relay"). Open whether that's the right UX or just a confusing abstraction.

9. Does Hermes become a Centaur harness? harness/hermes alongside harness/claude and harness/codex, but configured to run inside a local sandbox container (Docker on the user's machine) rather than K8s. This gives Hermes the same iron-proxy boundary Centaur has, without losing the local-first property. Adds a container runtime to the OS app's dependency footprint though.

---

Summary of where this leaves us

• Centaur is reusable as-is via the overlay system. Dual-licensed Apache-2.0 OR MIT. No kernel fork required for the planned architecture.
• The Phase plan compresses to ~8–9 weeks (down from 10–11).
• Hermes is a second execution plane that needs first-class treatment in the cap model. The main new design constraints are (1) caps may carry a local_inference_allowed caveat, (2) Hermes needs main-process IPC to use the cap wallet, (3) audit is structurally weaker for local execution and policy has to acknowledge that.
• Three more open questions on top of the original six: opt-in vs opt-out for local inference; whether to unify the agent-thread UI across planes; whether Hermes should eventually become a Centaur harness running in a local sandbox.