---
id: 10800
title: Author cloud deployment cookbook for shared KB+MC topology
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
assignees:
  - neo-gemini-pro
createdAt: '2026-05-06T08:29:21Z'
updatedAt: '2026-05-06T09:32:46Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10800'
author: neo-opus-ada
commentsCount: 0
parentIssue: 9999
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-06T09:32:46Z'
---
# Author cloud deployment cookbook for shared KB+MC topology

## Context

[#10721](https://github.com/neomjs/neo/issues/10721) (Shared deployment MVP completeness gaps) closes 9/10 → 10/10 with the three PRs landing today (#10797 / #10798 / #10799). [#10691](https://github.com/neomjs/neo/issues/10691) shipped the substrate primitives. [`learn/agentos/SharedDeployment.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/SharedDeployment.md) exists as the operator-facing **reference** doc — it documents what each piece does, how to verify topology, threat models, healthcheck shapes.

What's missing is a **walkthrough cookbook** — a concrete, ordered, end-to-end deployment guide for an external operator standing up KB+MC against a shared cloud-hosted Chroma + reverse proxy + identity-aware deployment. Reference docs answer "what is this?"; cookbooks answer "how do I deploy this from zero?".

This is filed at the operator's directive to (a) provide a starting point for external onboarding, and (b) **deliberately surface gaps** between substrate-shipped state and external-deployable state. The act of writing the cookbook IS the gap audit.

## The Problem

Substrate-complete vs deploy-walkable are different states. Today an external operator cloning `dev` faces these unresolved questions with no canonical answer in repo:

1. **Container packaging.** One image with both server processes (KB + MC), or two images (one per server) deployed as sidecars? Each shape has trade-offs (process supervision vs cloud-native isolation). No documented guidance.
2. **Server-knows-its-URL.** OAuth `redirect_uri` registration, public-endpoint discovery, SSE callback URLs — does each server need to know its public-facing URL at boot? Currently the SSE port is configurable (`SSE_PORT`) but the canonical public URL is not surfaced to the server itself.
3. **Cross-server tool calls.** KB and MC are independent processes that share Chroma but otherwise don't talk to each other directly. Is that the intended deployment model long-term, or is there an evolved shape that needs cross-server RPC?
4. **Two-MCP-server URL strategy.** Operator must expose two distinct HTTPS endpoints (one per MCP server). Reverse-proxy routing pattern, port allocation, hostname-vs-pathname routing — no canonical recipe.
5. **Two embedding providers.** `ai/mcp/server/memory-core/config.template.mjs` exposes both `chromaEmbeddingProvider` (read by KB + MC) and `neoEmbeddingProvider` (read in **exactly one callsite** — `ai/daemons/services/GoldenPathSynthesizer.mjs:81`). The "two providers" model surfaced explicitly in [#10773](https://github.com/neomjs/neo/issues/10773) via `aligned: true/false`. The cookbook-writing pass should challenge whether two-provider is justified or residual config-history; consolidation may become a follow-up ticket.
6. **Config-surface inventory.** Both `memory-core/config.template.mjs` and `knowledge-base/config.template.mjs` carry many env vars (`AUTO_*`, `AUTH_*`, `NEO_*`). No consolidated env-var matrix exists for deployment-time provisioning.
7. **Integration testing infrastructure.** Today our test surface is unit-tested silos (`HealthService.spec.mjs`, `Auth.spec.mjs`, etc.). We have **no staged-stack integration test** exercising KB+MC+Chroma+reverse-proxy+OAuth as a deployed unit. The cookbook should articulate what testing-against-deployed-shape would look like — likely surfaces a separate infrastructure ticket.

The cookbook's *output* is a deployment artifact for external operators. The cookbook's *byproduct* is each gap above becoming a discrete, actionable follow-up ticket.

## The Architectural Reality

- **Existing reference doc:** [`learn/agentos/SharedDeployment.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/SharedDeployment.md) — covers topology modes, healthcheck verification, authentication threat model, async session summarization, migration path. Reference-format, not walkthrough-format.
- **Sibling reference docs to compose:** [`MemoryCore.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/MemoryCore.md) (canonical healthcheck contract), [`KnowledgeBase.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/KnowledgeBase.md), [`MemoryCoreMcpAuth.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/tooling/MemoryCoreMcpAuth.md) (OIDC + stdio dual-path).
- **Config templates:** `ai/mcp/server/memory-core/config.template.mjs`, `ai/mcp/server/knowledge-base/config.template.mjs` — env-var inventory source.
- **`learn/tree.json`:** the canonical taxonomy file. New cookbook entry slots under `AgentOS` parent (sibling to existing `agentos/SharedDeployment` entry).
- **Currently no Docker artifacts in repo** (`docker-compose*` and `Dockerfile*` absent). Cookbook may reference example containerization, but the repo intentionally ships zero infra-as-code today.

## The Fix

Author a new guide at **`learn/agentos/DeploymentCookbook.md`** registered in `learn/tree.json` under `AgentOS` parent, with the following walkthrough structure:

### Section 1 — Prerequisites & Architecture Picture

- Topology diagram: agent harnesses → reverse proxy → KB MCP server + MC MCP server → shared Chroma + per-server SQLite.
- Identity flow: external IdP → reverse proxy → MCP server (OIDC verify or proxy-header-trusted).
- What ships in repo vs what the operator provisions (Chroma instance, OAuth provider, reverse proxy, container runtime).

### Section 2 — Container Packaging

- One-image-two-processes vs two-images sidecar trade-offs.
- Recommended MVP shape (likely: two images, two containers, one shared Chroma — but the cookbook-writing pass should verify by walking through the reasoning).
- Worked example `Dockerfile` skeleton(s) + `docker-compose.yml` reference if appropriate (deferred to a follow-up infrastructure ticket if the cookbook concludes infra-as-code belongs there).

### Section 3 — Reverse Proxy Configuration

- `oauth2-proxy` (or equivalent) topology: terminate OIDC, inject `X-PREFERRED-USERNAME`, strip client-set values of those headers.
- Two-MCP-server URL strategy: hostname-based vs pathname-based routing.
- Health endpoint exposure decisions.

### Section 4 — Identity Provider Setup

- Pointer to the existing OIDC threat model in [`SharedDeployment.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/SharedDeployment.md#authentication).
- OAuth client registration steps, redirect URI strategy, `clientSecret` secrets-management guidance.
- The two paths: server-side OIDC verification vs proxy-header trust mode (`auth.trustProxyIdentity`).

### Section 5 — Shared Chroma Topology

- `NEO_CHROMA_UNIFIED=true` + `engines.kb.chroma.{host,port}` mechanics.
- Provisioning a managed Chroma vs self-hosted; collection-naming contract; operator obligations re: multi-tenant isolation.

### Section 6 — Environment Variable Inventory

- Consolidated matrix of every `NEO_*` / `AUTH_*` / `AUTO_*` env var across both servers, with deployment-mode-specific defaults.
- Gap-surfacing question: should the two `config.template.mjs` files be consolidated for deployment? Either reach a verdict or file a follow-up ticket.

### Section 7 — Healthcheck Verification

- Pointer to [`MemoryCore.md` §Healthcheck Response Shape](https://github.com/neomjs/neo/blob/dev/learn/agentos/MemoryCore.md) (canonical contract).
- Walkthrough of expected `providers.embedding`, `providers.summary`, `providers.auth`, `database.topology`, `identity` blocks for the cloud-deployed shape.

### Section 8 — First-Connection Smoke Test

- Agent harness configuration to point at the deployed URLs.
- Cross-tenant isolation verification (alice/bob query test).
- Auth-rejection probe (request without OIDC token vs with OIDC token vs with proxy header).

### Section 9 — Known Gaps & Follow-Up Tickets

- This section IS the meta-documentation surface. Each gap surfaced during writing gets a sub-bullet pointing to a filed follow-up ticket (provider consolidation, server-knows-its-URL, infra-as-code, integration testing harness, etc.).

## Acceptance Criteria

- [ ] **AC1:** `learn/agentos/DeploymentCookbook.md` authored with all 9 sections above (or a documented justification for omitting / restructuring any section).
- [ ] **AC2:** `learn/tree.json` updated with new entry under `AgentOS` parent, with appropriate ID (e.g., `agentos/DeploymentCookbook`).
- [ ] **AC3:** Cross-link from existing [`SharedDeployment.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/SharedDeployment.md) ("see Cookbook for walkthrough") and from [`MemoryCore.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/MemoryCore.md) where relevant.
- [ ] **AC4:** Section 9 enumerates each gap surfaced during writing, each with a filed follow-up ticket number. **The expected count is 3-6 follow-up tickets**; if zero gaps surface, the cookbook-writing pass was insufficient.
- [ ] **AC5:** Walkthrough is concrete enough that an external operator can follow it from `git clone` → first verified healthcheck against a deployed stack (modulo their own infra provisioning, which is operator-territory).
- [ ] **AC6:** No mention of specific external customers / partners by name (per repo discipline). Generic framing only ("external operator", "team-shared deployment", "partner-trial topology").

## Out of Scope

- **Building Docker / `docker-compose.yml` infra-as-code.** If the cookbook concludes containerization recipes belong in repo, that's a follow-up ticket. The cookbook itself is documentation.
- **Implementing provider consolidation** if the cookbook surfaces it — separate ticket.
- **Building integration test infrastructure** (staged URLs, OAuth fixtures, end-to-end stack tests) — separate ticket.
- **Multi-tenant graph isolation** (tracked under [#10011](https://github.com/neomjs/neo/issues/10011)).
- **Production hardening** (rate limiting, secrets rotation, observability beyond healthcheck) — beyond MVP scope.

## Avoided Traps

- **Rejected: Extend `SharedDeployment.md` instead of creating a sibling cookbook.** Reference and walkthrough are different documentation modes. `SharedDeployment.md` is a reference; mixing walkthrough prose into it would dilute both. Sibling guide preserves separation of concerns.
- **Rejected: Make this an `epic` ticket with the gap-surfaced subs as children.** The cookbook *is* the deliverable; the surfaced gaps become sibling tickets, not children. Epic-shaping would impose unnecessary process overhead (epic-review skill, etc.) for a guide-write.
- **Rejected: Defer cookbook authoring until all surfaceable gaps are pre-known.** Counter-productive — the gap-discovery is the value. Writing forces structured reasoning that lookup-from-memory does not.
- **Rejected: Bundle a partner-specific deployment recipe.** Per repo discipline, no customer-specific naming. The cookbook serves any external operator deploying the shared topology.

## Related

- **Parent epic:** [#9999](https://github.com/neomjs/neo/issues/9999) — Cloud-Native Knowledge & Multi-Tenant Memory Core.
- **Predecessor sub-epic (closing today):** [#10721](https://github.com/neomjs/neo/issues/10721) — Shared deployment MVP completeness gaps. The cookbook depends on its work landing.
- **Predecessor substrate sub-epic:** [#10691](https://github.com/neomjs/neo/issues/10691) — Shared KB/MC Team Deployment MVP (substrate primitives).
- **Reference docs to compose:** [`SharedDeployment.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/SharedDeployment.md), [`MemoryCore.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/MemoryCore.md), [`KnowledgeBase.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/KnowledgeBase.md), [`MemoryCoreMcpAuth.md`](https://github.com/neomjs/neo/blob/dev/learn/agentos/tooling/MemoryCoreMcpAuth.md).
- **Sibling adjacency:** [#10291](https://github.com/neomjs/neo/issues/10291) — Organism self-defense substrate for cloud-phase #9999 (operator-facing concern with overlap on cloud topology).

Origin Session ID: `34c8f800-1855-43ff-aea6-d5e6b9410978`

Retrieval Hint: `query_raw_memories(query="cloud deployment cookbook walkthrough KB MC docker container reverse proxy oauth2-proxy oidc external operator partner-trial topology gap surfacing")`

## Timeline

- 2026-05-06T08:29:22Z @neo-opus-ada added the `documentation` label
- 2026-05-06T08:29:22Z @neo-opus-ada added the `enhancement` label
- 2026-05-06T08:29:22Z @neo-opus-ada added the `ai` label
- 2026-05-06T08:29:23Z @neo-opus-ada added the `architecture` label
- 2026-05-06T08:29:31Z @neo-opus-ada added parent issue #9999
- 2026-05-06T08:31:56Z @neo-gemini-pro assigned to @neo-gemini-pro
- 2026-05-06T08:32:58Z @neo-gemini-pro cross-referenced by #10801
- 2026-05-06T08:33:00Z @neo-gemini-pro cross-referenced by #10802
- 2026-05-06T08:33:02Z @neo-gemini-pro cross-referenced by #10803
- 2026-05-06T08:33:03Z @neo-gemini-pro cross-referenced by #10804
- 2026-05-06T08:33:05Z @neo-gemini-pro cross-referenced by #10805
- 2026-05-06T08:35:09Z @neo-gemini-pro cross-referenced by PR #10806
- 2026-05-06T08:36:17Z @neo-opus-ada cross-referenced by #10807
- 2026-05-06T08:46:47Z @neo-gemini-pro referenced in commit `c08077b` - "docs(agentos): author cloud deployment cookbook (#10800)"
- 2026-05-06T08:49:53Z @neo-opus-ada cross-referenced by #10808
- 2026-05-06T08:52:41Z @neo-gemini-pro referenced in commit `e4dace9` - "docs(agentos): align healthcheck schema and env vars for shared topology (#10800)"
- 2026-05-06T09:30:34Z @neo-gemini-pro referenced in commit `2a47490` - "docs(cookbook): update OAuth reference to 2.1 for taxonomy consistency (#10800)"
- 2026-05-06T09:32:46Z @tobiu referenced in commit `d7c119c` - "docs(agentos): author cloud deployment cookbook (#10800) (#10806)

* docs(agentos): author cloud deployment cookbook (#10800)

* docs(agentos): align healthcheck schema and env vars for shared topology (#10800)

* docs(cookbook): update OAuth reference to 2.1 for taxonomy consistency (#10800)

---------

Co-authored-by: neo-gemini-pro <neo-gemini-pro@users.noreply.github.com>"
- 2026-05-06T09:32:46Z @tobiu closed this issue
- 2026-05-06T09:43:32Z @neo-opus-ada cross-referenced by PR #10811
- 2026-05-06T09:48:47Z @tobiu referenced in commit `5e320f6` - "docs(agentos): polish cookbook Section 7 healthcheck JSON sample (#10800) (#10811)

Three-fold Section 7 polish following the merged PR #10806 cookbook +
PR #10810 provider consolidation:

1. Added providers.auth block to the JSON sample with the canonical
   {configured, oidc.{...}, proxyHeader.{...}} shape from PR #10798
   (#10770 healthcheck observability substrate). Documents the
   trustProxyIdentity-mode operator verification path explicitly.
2. Added providers.summary block (#10724 shape) so operators see all
   three providers.* siblings (embedding, summary, auth) in one place.
3. Updated providers.embedding from the prior dual-shape
   {aligned, chroma, neo} (Option B from PR #10799) to the single-block
   {active, host, model, dimensions} shape per PR #10810 consolidation.
   The dual-shape sample shipped in cookbook PR #10806 before
   PR #10810's merge; this aligns the reference doc with the now-shipped
   substrate.

Plus added #10808 cross-link to Section 9 Known Gaps (filed after
cookbook PR opened; fresh follow-up tracking env-var ergonomics).

Doc-only change; no runtime impact. Per pull-request-workflow §6.1
micro-change exemption ("pure documentation with no runtime impact"),
cross-family approval not strictly required, but routing primary review
to @neo-gemini-pro per round-robin + subsystem-familiarity (she
authored the cookbook).

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-07T07:48:03Z @neo-opus-ada cross-referenced by PR #10880
- 2026-05-07T13:16:28Z @neo-opus-ada cross-referenced by PR #10898

