---
id: 12094
title: 'Cross-repo env-var documentation follow-up for PR #12092 + PR #12093 (cloud-deployment guides + downstream-deployment env-example + README)'
state: CLOSED
labels:
  - documentation
  - ai
  - architecture
assignees:
  - neo-opus-ada
createdAt: '2026-05-27T13:38:55Z'
updatedAt: '2026-06-07T17:16:28Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12094'
author: neo-opus-ada
commentsCount: 1
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-28T07:37:18Z'
---
# Cross-repo env-var documentation follow-up for PR #12092 + PR #12093 (cloud-deployment guides + downstream-deployment env-example + README)

## Premise

PRs #12092 + #12093 introduce 5 new env vars without corresponding updates to the cloud-deployment documentation + downstream-deployment env-example/README files. Operators reading the existing guides won't know the new vars exist, what their defaults are, or when to override.

New env vars introduced:

| Env var | PR | Default | Purpose |
|---|---|---|---|
| `NEO_OLLAMA_KEEP_ALIVE` | #12093 | `-1` (resident) | Per-request `keep_alive` override in Ollama payload |
| `NEO_OPENAI_COMPATIBLE_KEEP_ALIVE` | #12093 | `-1` (resident) | Per-request `keep_alive` payload field for OpenAI-compat servers that honor the extension (LM Studio, Ollama's `/v1/...` surface) |
| `NEO_ORCHESTRATOR_PROVIDER_READY_ATTEMPTS` | #12092 | `30` | Orchestrator readiness-probe retry cap |
| `NEO_ORCHESTRATOR_PROVIDER_READY_DELAY_MS` | #12092 | `1000` | Between-probe wait |
| `NEO_ORCHESTRATOR_PROVIDER_READY_TIMEOUT_MS` | #12092 | `3000` | Per-probe HTTP timeout |

## Friction: relationship between native + Neo env vars

`NEO_OLLAMA_KEEP_ALIVE` (Neo provider per-request override, default `-1`) is distinct from `OLLAMA_KEEP_ALIVE` (native Ollama server config controlling default cache retention). Operators need to understand the interaction:

- Native `OLLAMA_KEEP_ALIVE` is the Ollama server default for requests that DON'T carry per-request `keep_alive`
- Neo's per-request `keep_alive` (sourced from `NEO_OLLAMA_KEEP_ALIVE` default `-1`) OVERRIDES the server default on every Neo-issued request
- With Neo's `-1` default, the model stays resident regardless of native `OLLAMA_KEEP_ALIVE` value
- Operators tuning native `OLLAMA_KEEP_ALIVE` shorter need to also set `NEO_OLLAMA_KEEP_ALIVE` to match if they want Neo requests to respect the shorter retention

## Prescription

Update both surfaces in parallel per the dogfooding-flywheel pattern (`feedback_first_deployment_direct_client_repo_pattern.md`):

### Neo side

- `learn/agentos/cloud-deployment/Configuration.md` — add the 5 new env vars with defaults + override guidance
- `learn/agentos/cloud-deployment/Overview.md` — brief mention if env-var topology section exists
- `learn/agentos/ConfigSubstrateEnvVarAudit.md` — PR #12093 already added `NEO_OLLAMA_KEEP_ALIVE` + `NEO_OPENAI_COMPATIBLE_KEEP_ALIVE`; verify PR #12092 also adds the 3 `NEO_ORCHESTRATOR_PROVIDER_READY_*` rows (if missing, backfill)

### Downstream-deployment side (separate MR in the downstream repo)

- `.env.example` — add commented examples for all 5 new Neo env vars; add a section explaining the `OLLAMA_KEEP_ALIVE` ↔ `NEO_OLLAMA_KEEP_ALIVE` interaction
- `README.md` — operator-tuning section referencing the new env vars + the interaction note
- `tenant-tokens.env.example` — verify: no changes needed (the new env vars are provider-wide, not tenant-scoped)

## Acceptance Criteria

- [ ] AC1: `learn/agentos/cloud-deployment/Configuration.md` documents all 5 new env vars with their defaults + override guidance
- [ ] AC2: `learn/agentos/ConfigSubstrateEnvVarAudit.md` lists all 5 new env vars (verify PR #12092 additions present; backfill if missing)
- [ ] AC3: Downstream-deployment `.env.example` adds commented examples for all 5 new env vars with the OLLAMA_KEEP_ALIVE-vs-NEO_OLLAMA_KEEP_ALIVE interaction documented
- [ ] AC4: Downstream-deployment `README.md` operator-tuning section references the new env vars
- [ ] AC5: AC10 of #12089 (external operator-side compose validation) is now operationally addressable — operators have visibility into which env vars to set
- [ ] AC6: No production code changes (docs + env-example only)
- [ ] AC7: §15.6 diagnostic clean on any new prose anchors (doc updates allowed per snapshot-archaeology exception; production code untouched)

## Empirical Anchor

- PR #12092 env binding additions: `ai/config.template.mjs` orchestrator.providerReadiness env bindings block
- PR #12093 env binding additions: `ai/config.template.mjs` + `ai/mcp/server/memory-core/config.template.mjs` keep_alive env bindings
- Downstream-deployment current state: `OLLAMA_KEEP_ALIVE=5m` (native ollama server var) but no Neo-equivalent vars documented
- Neo cloud-deployment Configuration.md: grep returned zero hits for any of the 5 new env vars

## Related

- PR #12092 (orchestrator readiness gate)
- PR #12093 (keep_alive defaults)
- #12089 AC10 (external operator validation residual)
- `feedback_first_deployment_direct_client_repo_pattern.md` (work-in-both-repos discipline)
- Capability-framing discipline: Neo-side docs use generic capability framing, never name specific commercial partners

## Timeline

- 2026-05-27T13:38:56Z @neo-opus-ada assigned to @neo-opus-ada
- 2026-05-27T13:38:57Z @neo-opus-ada added the `documentation` label
- 2026-05-27T13:38:57Z @neo-opus-ada added the `ai` label
- 2026-05-27T13:38:57Z @neo-opus-ada added the `architecture` label
- 2026-05-27T13:41:03Z @neo-opus-ada changed title from **Cross-repo env-var documentation follow-up for PR #12092 + PR #12093 (cloud-deployment guides + klarso .env.example + README)** to **Cross-repo env-var documentation follow-up for PR #12092 + PR #12093 (cloud-deployment guides + downstream-deployment env-example + README)**
- 2026-05-28T06:47:19Z @neo-opus-ada cross-referenced by PR #12129
### @neo-opus-ada - 2026-05-28T06:49:55Z

**Input from [Claude Opus 4.7 1M] (@neo-opus-4-7):**

> ❋ ## Neo-side (AC1) shipped via PR #12129 + AC2 scope-correction
> 
> PR [#12129](https://github.com/neomjs/neo/pull/12129) adds the Model-provider + orchestrator-readiness env-var section to `Configuration.md` (AC1), documenting all 5 vars + the native-vs-Neo `keep_alive` interaction.
> 
> **AC2 correction (V-B-A):** the original AC2 planned to backfill the 3 `NEO_ORCHESTRATOR_PROVIDER_READY_*` vars into `ConfigSubstrateEnvVarAudit.md`. On verification, that audit explicitly scopes to `ai/mcp/server/**` env reads (its Scope section), and the PROVIDER_READY vars have **zero reads under `ai/mcp/server/**`** — they're orchestrator-daemon-scoped (`ai/config.template.mjs` `orchestrator.providerReadiness`). Backfilling them would violate the audit's stated scope. The 2 keep_alive vars are correctly already in the audit (read by the memory-core MCP server). **Resolution: no audit-doc change — it's already correct for its scope; the scope boundary is now documented inline in the new Configuration.md section.** AC2 satisfied-by-correction.
> 
> **Remaining (AC3/AC4):** downstream-deployment `.env.example` + `README.md` operator-tuning updates — separate downstream-repo work. Keeping #12094 open until that lands.
> 
> — @neo-opus-4-7

- 2026-05-28T07:04:41Z @neo-opus-ada cross-referenced by #12130
- 2026-05-28T07:37:19Z @tobiu closed this issue
- 2026-05-28T07:37:19Z @tobiu referenced in commit `8666408` - "docs(cloud-deployment): document provider keep_alive + orchestrator-readiness env vars (#12094) (#12129)

PRs #12092 + #12093 introduced 5 deployment env vars without
corresponding cloud-deployment documentation. Configuration.md had zero
hits for any of them, so operators reading the guide had no visibility
into the vars, their defaults, or the native-vs-Neo keep_alive
interaction.

Adds a "Model-provider runtime + orchestrator-readiness" section to
learn/agentos/cloud-deployment/Configuration.md covering:

- NEO_OLLAMA_KEEP_ALIVE + NEO_OPENAI_COMPATIBLE_KEEP_ALIVE (both default
  -1 / resident; per-request override semantics)
- The native OLLAMA_KEEP_ALIVE (server-default-for-requests-without-
  keep_alive) vs Neo's NEO_OLLAMA_KEEP_ALIVE (per-request override sent
  on every call) interaction — the key operator friction: shortening
  native keep_alive has no effect on Neo traffic unless NEO_OLLAMA_KEEP_ALIVE
  is also shortened.
- NEO_ORCHESTRATOR_PROVIDER_READY_ATTEMPTS/DELAY_MS/TIMEOUT_MS (defaults
  30/1000/3000; readiness-probe tuning for cold-start-slow hosts).

AC2 scope-correction: the 3 PROVIDER_READY vars were NOT backfilled into
ConfigSubstrateEnvVarAudit.md as the ticket originally planned. That
audit explicitly scopes to ai/mcp/server/** env reads; the PROVIDER_READY
vars have zero reads there (orchestrator-daemon-scoped in
ai/config.template.mjs / ai/daemons/orchestrator/*), so adding them would
violate the audit's stated scope. The 2 keep_alive vars correctly remain
in the audit (read by the memory-core MCP server at
ai/mcp/server/memory-core/config.template.mjs:459/469). The new section
documents this scope boundary inline.

Docs-only; no production code touched.

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"

