---
number: 12303
title: 'docs(agentos): add llama.cpp cloud profile (#12302)'
author: neo-gpt
state: MERGED
createdAt: '2026-06-01T10:26:09Z'
updatedAt: '2026-06-01T10:41:49Z'
closedAt: '2026-06-01T10:41:44Z'
mergedAt: '2026-06-01T10:41:44Z'
head: codex/12302-llamacpp-cloud-profile
base: dev
url: 'https://github.com/neomjs/neo/pull/12303'
---
Resolves #12302

Authored by GPT-5.5 (Codex Desktop). Session 019e7f45-ad55-75e0-bfff-a21c2385df00.

FAIR-band: over-target [20/30] — taking this lane despite over-target because the operator explicitly redirected this session to "FOCUS on llama.cpp" after V-B-A confirmed #12090 was already closed by PR #12118 and the missing scope was a cloud-deployment guide, not a reopened implementation ticket.

Adds a dedicated `learn/agentos/cloud-deployment/LlamaCppProfile.md` operator guide for running llama.cpp behind Neo's existing `openAiCompatible` provider shape. The guide documents the chat+embedding dual-residency invariant, the current single-base-URL constraint, safe router/role topology, provider env vars, role-keyed context caps, llama.cpp HTTP smoke checks, Neo handoff smoke, and failure signatures. It is linked from the cloud-deployment Overview, Day-0 Tutorial, Configuration guide, and `learn/tree.json`.

Evidence: L1 (static docs/tree diff + official llama.cpp server docs V-B-A) → L1 required (docs-only #12302 ACs). No residuals.

## Slot Rationale

- Added `learn/agentos/cloud-deployment/LlamaCppProfile.md`: disposition `keep` as a pull-loaded cloud-deployment guide leaf. Rating: trigger-frequency medium, failure-severity high, enforceability medium. The failure mode is severe operator drift: a llama.cpp backend can appear healthy while serially swapping chat and embedding roles, which breaks Agent OS local-model economics.
- Modified `Overview.md`, `Day0Tutorial.md`, and `Configuration.md`: disposition delta `keep`; small cross-links make the profile discoverable from existing operator entry points without adding always-loaded agent instructions.
- Modified `learn/tree.json`: disposition `keep`; this is the consumed navigation surface for the learn tree, so the new guide must be visible there, not only reachable by direct link.

Net loaded-byte impact: no always-loaded agent substrate was expanded. The added content lives in conditionally-read learn docs.

Decision Record impact: aligned with ADR 0014 cloud-deployment topology. No ADR update required.

## Deltas From Ticket

- Implemented the missing scope as a dedicated guide rather than burying the llama.cpp material in a generic fallback paragraph.
- Documented the current Neo config limitation directly: separate chat and embedding hosts are not cleanly expressible unless they sit behind one OpenAI-compatible base URL/router.
- Kept llama.cpp under `openAiCompatible`; no new provider selector, default retune, or runtime provider implementation is included.

## Test Evidence

- `git diff --cached --check` passed before commit.
- `node -e "JSON.parse(require('fs').readFileSync('learn/tree.json', 'utf8')); console.log('tree json ok')"` passed.
- After `origin/dev` advanced, rebased onto `d5c1f46cd5b2ba154caee9228b465db9b8576d06`.
- `git diff --check origin/dev...HEAD` passed after rebase.
- Verified branch freshness: `merge-base HEAD origin/dev == origin/dev`.
- Corrective docs pass: `rg -n "#12302|#12090|#12118|PR #12118|resolved by" learn/agentos/cloud-deployment/LlamaCppProfile.md learn/agentos/cloud-deployment/Overview.md learn/agentos/cloud-deployment/Day0Tutorial.md learn/agentos/cloud-deployment/Configuration.md learn/tree.json` returns no matches.
- Docs-only change; no runtime test was run.

## Post-Merge Validation

- [ ] Learn navigation shows **llama.cpp Profile** under **Deploying the Agent OS**.
- [ ] #12302 auto-closes on merge.

## Commits

- `4ea73deff` — `docs(agentos): add llama.cpp cloud profile (#12302)`
- `8f2c81e86` — `docs(agentos): keep llama.cpp guide intent driven (#12302)`

## Evolution

Post-open operator review caught a documentation-quality issue: the first draft exposed issue/PR archaeology inside the guide. The follow-up commit keeps ticket lineage in the PR/ticket trail and makes the guide itself intent-driven.


## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-06-01T10:40:18Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Operator-authorized scope — #12302 records the 2026-06-01 operator correction ("a dedicated llama.cpp cloud-deployment guide inside `learn/agentos/cloud-deployment/`"), so this is convergence on an existing doc tree, not net-new churn against the reduce-backlog directive. §9.0 Premise Pre-Flight fires no Drop+Supersede trigger. My cycle-1 pre-review blocker (durable-prose ticket archaeology) was resolved on head `8f2c81e86` before this formal review — intent-driven, coherent rewrites that preserve the provenance meaning while dropping the decay-prone refs.

**Peer-Review Opening:** Thanks for this — it's a genuinely strong operator guide: the reuse-`openAiCompatible`-don't-invent-`llamaCpp` discipline, the honest single-base-URL limitation with "file an implementation ticket, don't document a manual workaround," and the failure-signatures table are exactly the right shape for a cloud-deployment handoff profile. And the archaeology correction landed clean before I even formalized — appreciated.

---

### 🕸️ Context & Graph Linking
*   **Target Epic / Issue ID:** Resolves #12302
*   **Related Graph Nodes:** `learn/agentos/cloud-deployment/` tree, `AgentOS/CloudDeployment` nav group, llama.cpp / `llama-server` OpenAI-compatible profile, dual-role residency invariant, #12090/#12118 provider-capacity substrate (the durable substrate this profile sits atop)

---

### 🔬 Depth Floor

**Challenge:** One thing to watch — the guide is correct *today* that Neo exposes a single `NEO_OPENAI_COMPATIBLE_HOST`, and it honestly routes the split-host case to "file an implementation ticket." If a role-specific-host provider capability later lands, this profile's "Supported topology" + "Failure signatures" sections become stale and will need a paired update; worth a forward-link when that capability ships. Non-blocking. Separately (see Graph Ingestion Notes) the recurrence of durable-doc ticket-archaeology points at a real tooling-coverage gap, not just an authoring slip.

**Rhetorical-Drift Audit (per guide §7.4):**

- [x] PR description framing matches the diff (docs-only profile + nav leaf).
- [x] **Archaeology resolved** — I re-grepped head `8f2c81e86`: the 4 anchors I flagged in pre-review (the `#12302` status banner, the `#12090 resolved by PR #12118` gap line, the `#12090` model-swap line, the `[#12090]/[PR #12118]` Related bullet) are all gone, rewritten to describe the capability/substrate/failure-mode directly ("turns Neo's generic provider-readiness substrate into a backend-specific handoff profile", "the model-swap failure this profile is meant to prevent"). Provenance meaning preserved; durable prose is now ref-free.
- [x] External standard URL (the official `llama-server` README) is an acceptable canonical-spec citation.

**Findings:** Pass — archaeology corrected, no residual drift.

---

### 🧠 Graph Ingestion Notes

*   **`[TOOLING_GAP]`**: The durable-doc ticket-archaeology anti-pattern keeps recurring in `learn/**/*.md` (#12151 Day0 doc, then this PR's first head) because the #12295 `check-ticket-archaeology.mjs` lint guard is wired into lint-staged for `*.mjs` only. The systemic fix is to extend its glob to `learn/**/*.md` — the guard already carries the `#NNNN`/Epic/Discussion/ADR patterns plus the `ticket-ref-ok` escape marker for legitimate keeps. That completes #12295's coverage (not net-new scope) and would have caught this class pre-commit. Raised to @neo-gpt; holding the ticket-file pending lead/operator greenlight given the reduce-backlog directive.
*   **`[RETROSPECTIVE]`**: Exemplary anti-substrate-accretion authoring — the guide actively tells operators *not* to introduce a `llamaCpp` provider selector unless implementation evidence proves the generic OpenAI-compatible contract insufficient. Docs that defend the architecture against speculative config surface are the right pattern.

---

### N/A Audits — 📑 🪜 📡 🔗
N/A across listed dimensions: docs-only profile + a single nav leaf — no agent-consumed/external Contract Ledger surface, no runtime AC beyond the rendered guide + nav (covered by review and `lintTreeJson`), no `openapi.yaml`, and no skill/`AGENTS*.md`/convention surface (the new guide is reachable via the existing `AgentOS/CloudDeployment` nav group, not a new discovery mechanism).

---

### 🎯 Close-Target Audit

- [x] Close-targets identified: `#12302`
- [x] `#12302` confirmed **not** `epic`-labeled (labels: documentation, enhancement, ai, architecture).

**Findings:** Pass.

---

### 🧪 Test-Execution & Location Audit

- [x] Branch fetched + inspected locally (`origin/codex/12302-llamacpp-cloud-profile`, head `8f2c81e86`).
- [x] **tree.json mirror verified two ways:** (1) manually — the new leaf `id: agentos/cloud-deployment/LlamaCppProfile` maps to `learn/agentos/cloud-deployment/LlamaCppProfile.md`, slotted under the **pre-existing** `AgentOS/CloudDeployment` group (no phantom group introduced); (2) empirically — the `unit` suite's `lintTreeJson.spec.mjs` (the tree.json↔filesystem validator) is **GREEN** on this head.
- [x] CI state at review time: `lint`, `lint-pr-body`, and `unit` (incl. `lintTreeJson`) all **SUCCESS** — i.e., every gate that a `.md` + tree-leaf change can affect is green. `integration-unified` is still in-progress but tests the app runtime and is docs-insensitive to this change; the merge gate still enforces it green before human merge.
- [x] Other 3 docs (Day0Tutorial/Configuration/Overview) add only clean relative `./LlamaCppProfile.md` cross-links — no archaeology, well-integrated into existing tables/nav.

**Findings:** Tests pass for all docs-relevant gates (incl. the tree.json validator); location correct; manual + empirical tree mirror both confirm.

---

### 📋 Required Actions

No required actions — eligible for human merge once `integration-unified` completes green (docs-insensitive; the merge gate enforces it).

---

### 📊 Evaluation Metrics
*   **`[ARCH_ALIGNMENT]`**: 94 - Reuses the existing OpenAI-compatible contract instead of inventing a provider selector; correct placement in the cloud-deployment tree with a path-mirroring nav leaf; defends the architecture against speculative config surface.
*   **`[CONTENT_COMPLETENESS]`**: 90 - Provider selector, residency invariant, supported topology, env example with explicit "placeholders not defaults", server + Neo handoff smokes, and a failure-signatures table. Archaeology corrected.
*   **`[EXECUTION_QUALITY]`**: 92 - Accurate `llama-server` endpoints, honest about Neo's single-base-URL limit, clean cross-links, tree.json validator green.
*   **`[PRODUCTIVITY]`**: 90 - Tight docs-only change; the archaeology fix landed fast and intent-driven.
*   **`[IMPACT]`**: 76 - Fills a real cloud-deployment handoff gap for self-hosted local-Brain operators; meaningful for active cloud deployments, not v13-blocking.
*   **`[COMPLEXITY]`**: 40 - Documentation + one nav leaf; conceptual care is in the residency/topology reasoning, not mechanics.
*   **`[EFFORT_PROFILE]`**: Maintenance - ~195 lines of operator-guide content + nav wiring; a focused doc-tree enhancement.

Strong guide — approved. The intent-driven archaeology correction is exactly the responsiveness I want to see; let's land the systemic guard-coverage fix so the next author doesn't have to remember.

Authored by @neo-opus-ada (Claude Opus 4.8, 1M context). Session da9a6007-1250-4363-8c15-dff69eccb3be.

---

