# System Map — how the existing stack connects (verified 2026-07-01)

The marketplace composes three live systems plus the m2o fleet. All run as **Coolify apps on
the m2 host**, on the shared `coolify` Docker network — services reach each other by Docker
DNS alias, humans/external agents via Traefik-routed domains.

```
                         ┌────────────────────────── m2 host (Coolify) ──────────────────────────┐
                         │                                                                        │
  operator browser ──►  Guacamole (m2o.machinemachine.ai)                                         │
                         │   │  VNC/RDP via per-desktop guacd:4822                                │
                         │   ▼                                                                    │
                         │  m2o desktops (primus: chris/matrix/m2bd/erlengrund ·                  │
                         │                agent-latest: sdjs/nasr/parlobyg/peter/gunnar)          │
                         │   │ each: Hermes gateway (supervised) + herdr + [openclaw on legacy]   │
                         │   │                                                                    │
                         │   ├── LLM calls ──► m2-gpt gateway (gpt.machinemachine.ai/v1)          │
                         │   │                 Bifrost/FastAPI, multi-tenant keys, per-tenant     │
                         │   │                 budgets/metering, "subconscious" middleware:       │
                         │   │                 injects m2.* memory tools + ambient context ──┐    │
                         │   │                                                               │    │
                         │   └── memory ops ──► memory-api:8000 (agent.memory.system) ◄──────┘    │
                         │                      FastAPI + Qdrant (BGE-M3 hybrid) + memgraph       │
                         │                      + TEI embeddings + redis; agent_id partitions;    │
                         │                      public: memory.machinemachine.ai                  │
                         │                                                                        │
                         │  Forgejo (git.machinemachine.ai) — org m2; fedlearn m2/m2-core (WIP)   │
                         └────────────────────────────────────────────────────────────────────────┘
```

## The three repos

### 1. m2-gpt — github.com/machine-machine/m2-gpt  (local: /home/m2/m2-gpt/m2-gpt)
Multi-tenant **OpenAI-compatible gateway with a subconscious layer**. Any OpenAI-speaking
harness (Hermes, OpenClaw, Claude Code) points `base_url` at `https://gpt.machinemachine.ai/v1`
with a tenant key; the gateway routes to upstreams (SGLang on spark cluster, OpenRouter, GLM)
and injects `m2.*` memory tool-calls + ambient sensation into the prompt. Live:
`{"status":"healthy","gateway":"bifrost"}`; two gateway containers (staging+prod pattern).
**Marketplace relevance:** tenant identity, per-tenant budgets and token metering (the natural
substrate/federation point for `m2-ledger`), admin APIs/UI (React/shadcn — reusable patterns
for a market admin), fleet_standards cascade resolver.

### 2. agent.memory.system — github.com/machine-machine/agent.memory.system  (local: /home/m2/agent.memory.system)
The memory stack behind `memory-api`. Python FastAPI over **Qdrant (BGE-M3 dense+sparse
hybrid) + memgraph (graph) + TEI embeddings + redis**; working/episodic/semantic memory with
consolidation + importance scoring. Deployed twice via Coolify (stacks `z1rlou…` and `vc00o…`
— the known split-brain; fedlearn task T13 is resolving auth + live-endpoint discovery now).
Consumed by: desktops (m2-memory skill, openclaw memory-engine plugin), m2-gpt backings
(`backings/` HTTP client), fedlearn partitions (`fedlearn:submissions|clusters|core-index`).
**Marketplace relevance:** the semantic catalog (`market:catalog` partition), pricing-evidence
recall, Scout intent-matching — all one more partition on proven infra.

### 3. m2o — github.com/machine-machine/m2o  (local: /home/m2/m2o)
The desktop platform: Guacamole gateway + primus image (`desktop/`) + provision.sh +
fleet.json. Every desktop ships **Hermes as primary agent** (supervised gateway, config
rendered on first boot pointing at m2-gpt with `M2_GPT_API_KEY` injected at provision) +
**herdr** baked fleet-wide (v4.4+) + **RDP standard** (v4.5). Legacy agent-latest desktops
additionally run **openclaw** (m2-custom fork) with the memory-engine plugin.
**Marketplace relevance:** the execution surface (installs land in `/agent_home` volumes via
the fedlearn sync path), the co-driving wedge (Guacamole VNC/RDP), Scout host, cargstore host.

## Agent posture
- **Hermes = the gateway-managed primary agent** (every primus desktop; supervised; m2-gpt
  backed). The marketplace's conversational surface (`market-propose` skill) targets Hermes
  FIRST.
- **OpenClaw = open option** (legacy desktops run it; m2-gpt explicitly serves both). Design
  marketplace touchpoints harness-agnostic where cheap: anything speaking OpenAI-wire through
  m2-gpt inherits the subconscious/memory layer, so Scout/propose logic should live behind the
  gateway or as skills, not inside one harness.

## Related moving parts
- **fedlearn MVP (in herd execution now):** builds the rails the marketplace rides —
  schemas, Forgejo `m2/m2-core`, memory-api auth hardening, capture CLI, curator+veto PRs,
  `m2-core-sync` apply path. Plan: `/home/m2/m2o/.planning/federated-learning/PLAN.md`.
- **cargstore** (github.com/machine-machine/cargstore): Electron+React desktop app store
  (Flatpak backend, JSON catalog, one-click installs, agent WebSocket) → evolve into M2 Store.
- **Coolify** (cool.machinemachine.ai): deploys everything above; new marketplace services
  (m2-ledger, catalog indexer, Scout) should be Coolify apps on the `coolify` network. Gotcha:
  the local registry route self-redirects (302), so primus-style images build local-only.
- **spark cluster** (spark1–6): SGLang upstreams for m2-gpt; future Resource inventory.

## Hard constraints inherited
- Tenant isolation (sdjs=GST etc.): client data never crosses into shared catalog/core.
- No secrets in repos/images; keys injected at runtime (M2_GPT_API_KEY pattern).
- Mixed images (primus vs agent-latest): runtime-sync is the only universal install path.
- Host fragility: canary-first rollouts, idempotent + reversible applies, no fleet-wide blast.