OLLAMA_HOST Resolution Strategy — ALAI Fleet (MC #8476)

OLLAMA_HOST Resolution Strategy — ALAI Fleet

Owner: Skillforge |/ Lexicon
MC: #8476
Verified: 2026-07-28 |from live files and BookStack API
MC:Canonical references read:

#8476

Source of truth: 
• ~/system/tools/ollama-host.sh
(implemented 2026-04-20, CodeCraft) +
• ~/system/architecture/distributed-ai-factory-plan.md §4 (OLLAMA_HOST Abstraction)
• ~/.zshrc for shell integration verification

---

Purpose

ALAI tools and agents need a portable way to reach Ollama from different factory hosts. The wrapper ~/system/tools/ollama-host.sh resolves the best reachable Ollama endpoint once, exports it as OLLAMA_HOST, and lets Node/JS callers consume it via process.env.OLLAMA_HOST instead of hardcoding localhost:11434.

The architecture-plan intent is: ANVIL local → Tailscale ANVIL 100.103.49.98 → FORGE 10.0.0.2 → graceful warning/fallback. The live script adds two operational safeguards: explicit override support and a five-minute cache.

---

1.Resolution WhyStrategy ThisImplemented Existsby ollama-host.sh

ALAIActual agentlive scriptsorder callin Ollama~/system/tools/ollama-host.sh:

for

local
1. inference

   Explicit (classifiers,environment embeddings,override
   sessionIf summarization).OLLAMA_HOST Differentis machinesalready reachset, Ollamathe differently:script honors it and does not probe.

2. Fresh cache short-circuit
   If /tmp/ollama-host.cache exists and is younger than 300 seconds:

   • cached URL other than NONE → export it as OLLAMA_HOST
   • cached value NONE → warn and leave OLLAMA_HOST unset

3. ANVIL hostname match
   (MacIf Studio,the hostname contains makinja-sin-mac-studio / hostnameor makinja.local), —the Ollamascript runsassumes locallyit is running on ANVIL and sets:

   OLLAMA_HOST=http://localhost:11434
   .

4. Remote/clientLocal hostsprobe
   (e.g.Probe ab-mac)http://localhost:11434/api/version —with musta reachone-second timeout. If it responds, set:

   OLLAMA_HOST=http://localhost:11434
   

5. Tailscale ANVIL probe
   Probe ANVIL over Tailscale at 100.103.49.98:11434, or fall back to FORGE (10.0.0.2:11434, LAN-only) if ANVIL is unreachable.

6. Neither reachable — script must degrade gracefully (warn, do not hang, do not crash agents that havewith a Claudetwo-second API fallback).

ollama-host.sh centralizes this so scripts don't hardcode an endpoint. Instead they read $OLLAMA_HOST (or, in JS, process.env.OLLAMA_HOST), which the wrapper resolves and exports once per shell session.

---

2. Resolution Order (as implemented in ollama-host.sh)

The live script's actual order is cache-first, then hostname, then a network probe ladder — this is slightly more defensive than the original architecture-plan pseudocode (§4 of distributed-ai-factory-plan.md), which omits the cache and the local-probe step. Documenting the real script here:timeout:

1. Explicit override   — if $OLLAMA_HOST is already set in the environment, use it
                          as-is. No probing. (Lets a human or CI job pin an endpoint.)
2. Cache check          — if /tmp/ollama-host.cache exists and is < 5 min old:
                            - cached value present and != "NONE"  → export it, done
                            - cached value == "NONE"              → warn, leave unset, done
3. Hostname match       — if `hostname` contains "makinja-sin-mac-studio" or
                          "makinja.local" (i.e. we ARE ANVIL) → localhost:11434
4. Local probe          — curl localhost:11434/api/version, 1s timeout
                          (catches "Ollama running locally for some other reason")
5. Tailscale ANVIL      — curl http://100.103.49.98:11434/api/version,version
2s

timeout

If 6.it responds, set:

OLLAMA_HOST=http://100.103.49.98:11434

7. FORGE LAN probe
   Probe FORGE (on LAN only)with —a curlone-second timeout:

   http://10.0.0.2:11434/api/version,version
   1s

   timeout

   If (fast-failsit onresponds, non-LANset:

   hosts,

   OLLAMA_HOST=http://10.0.0.2:11434
   e.g.

   remote/cloud
machines)
8. 7.

   Graceful degrade
   —If none of the endpoints responds, write "NONE"NONE to the cache, print onea WARNINGwarning to stderr, and leave $OLLAMA_HOST unset. AgentsThe withwarning anames the failed endpoints and states that Ollama-dependent agents will fail gracefully while Claude API fallback continue; Ollama-only agents failcontinue explicitlynormally.

   downstream
rather than hanging on an unreachable host.

Every successful resolution (steps 3–6) writes its result to the cache file before exporting, so the next shell in the same 5-minute window skips the probe ladder entirely (step 2 short-circuits).

---

3.Cache Cache: /tmp/ollama-host.cacheBehavior

• Path:Cache file: /tmp/ollama-host.cache
• TTL: 300 seconds / five minutes (flat_OLLAMA_CACHE_TTL=300)
text
• Value file,format: singleone line:line eithercontaining a resolved URL likesuch as http://100.103.49.98:11434, or the literal string NONE).
• TTL:Why it exists: 300avoids secondsrepeated (5curl minutes),timeouts enforcedon byevery comparingshell stator mtimesubprocess againststart
date
• Platform +%s.detail: Thecache scriptage triesuses macOS stat -f %m first,first and falls back to GNU stat -c %Y
—

safe

Successful onendpoint bothresolution ANVILwrites (macOS)the andURL anyto Linuxthe cache. A failed resolution writes NONE, so the host thatdoes sourcesnot repeat the same file.

Purpose: avoids re-running the curlfull probe ladder (up to ~4s of sequential timeouts in the worst case: local 1s + Tailscale 2s + FORGE 1s) on every new shell/subprocess.

Failure caching: a NONE result is cached too — so a host with no reachable Ollama doesn't re-probe every session, it just re-warns from cache until the TTL expires or the cache is manually flushed.

---

ollama_flush_cache()

The wrapper exports this function:

ollama_flush_cache() {
  rm -f "$_OLLAMA_CACHE_FILE"
  echo "[ollama-host] Cache cleared. Run 'source ~/system/tools/ollama-host.sh' to re-resolve."
}

DeletesUse /tmp/ollama-host.cache and prints a reminder to re-source. Call this manually after:

• Tailscale reconnects (e.g.it after sleep/wakeTailscale reconnects, after Ollama starts/restarts, after ANVIL/FORGE network state changes, or VPN flap) and ANVIL becomes reachable again
• Ollama is (re)started on ANVIL or FORGE
• You changed $OLLAMA_HOST by hand and want the wrapper to re-probe instead of trustingafter a stale cachedNONE failure

Itresult is exported as a shell function (export -f ollama_flush_cache) so it's callable from any subshell in the sourcing session, not just interactively.suspected.

ThereThe isscript also exports ollama_available(), a one-line guard scripts can call before an Ollama-only code path::

ollama_available() {
  [[ -n "${OLLAMA_HOST:-}" ]] && [[ "${OLLAMA_HOST}" != "NONE" ]]
}

Use this before an Ollama-only path when a script needs an explicit availability guard.

---

4.How ConsumptionRefactored inJS/Node Files Consume the Result

Refactored Node/JS Agentcode Scripts

Scripts that were refactored off hardcoded endpoints readreads the resolvedenvironment value viaexported by the wrapper:

const host = process.env.OLLAMA_HOST || 'http://localhost:11434';

or equivalent variants. The important rule is: do not hardcode a fleet endpoint inside each agent/tool; read process.env.OLLAMA_HOST (theand shell wrapper exports it, so any JS process spawned from a shell that sourcedlet ollama-host.sh inheritsresolve it).

Verified counts (2026-07-28, grep -rl over ~/system, .js/.sh/.ts/.mjs):routing.

Pattern	Count
Files reading process.env.OLLAMA_HOST	149
Files still hardcoding localhost:11434 or 127.0.0.1:11434	(scan in progress — see File-count note below)

⚠️ Correction tofor MC #8476

The task description:description thesays task text (written 2026-04-20, the day ollama-host.sh was implemented) states "“52 refactored files now read process.env.OLLAMA_HOST".” ACurrent live grepverification todayon counts2026-07-28 149found:

Scope	Verified count	Evidence file
Source-like files matchingunder that~/system pattern(*.js, —*.mjs, *.ts, *.sh) matched with rg --no-ignore	38	/tmp/verify-8476/process-env-ollama-host-files-rg-no-ignore.txt
All matched files under ~/system including backups/docs/evidence/context bundles	50	/tmp/verify-8476/process-env-ollama-host-all-files-rg-no-ignore.txt

The historical “52” figure is therefore documented as task context, but was not reproduced by the current filesystem scan. Do not 52.treat This52 runbook reportsas the verifiedcurrent live count ratherunless thanseparate thedated originalimplementation estimate; the 52 figure appears to be a stale same-day estimate that predates further refactor work, not a target to reconcile against. No historical record (evidence/reports) of a "52 files" sign-off was found via discover.js search, so the original number cannot be reconstructed or verified — only the current state.

Not every hardcoded referenceevidence is necessarilyfound.

a

---

bug:

Shell someIntegration are(~/.zshrc)

inside

The source line expected by ollama-host.sh itself (the probe URLs), health-probe/monitoring scripts that intentionally target a specific host, or docs/comments. A hardcode count is a signal for follow-up, not an automatic defect list — each hit needs eyeballing before "refactor" is filed as a task.

---

5. Shell Integration

Expected integration (per ollama-host.sh header comment):is:

[ -f ~/system/tools/ollama-host.sh ] && source ~/system/tools/ollama-host.sh

addedCurrent toverification ~/.zshrc.

on

⚠️this Verified gap (2026-07-28):machine: ~/.zshrc onwas thisread machineand (ANVIL) currently hascontains no reference to ollama-host.sh, OLLAMA_HOST, or "ollama" at all (grep -in ollama ~/.zshrc returns nothing; file last modified 2026-05-18). The wrapper is NOT currently auto-sourced on interactive shell start. It must be invoked explicitly (source ~/system/tools/ollama-host.sh) or sourced by whatever launches an agent process today.

This is a real gap, not a documentation omission — filed as a follow-up rather than silently assumed fixed. See §6.

---

6. Follow-ups Identified While Writingline. This Runbook

runbook

• zshrc source line missing — addrecords the one-linerequired sourceline; guardadding from §5it to ~/.zshrc sois everya interactivefollow-up shelloperational resolveschange, not performed by this documentation task.

  ---

  Operational Checklist

  When a host cannot reach Ollama:

  1. Check the currently resolved value:

     echo "$OLLAMA_HOSTOLLAMA_HOST"
     

     automatically
  instead
  2. Clear ofstale relyingcache onand eachre-resolve: agent-launch path to

     ollama_flush_cache
     source it~/system/tools/ollama-host.sh
     independently.

  3. "52Probe files"the figureexpected staleendpoints —manually: treat

     curl as-sf historical/unverifiable;--max-time 1491 http://localhost:11434/api/version
     curl -sf --max-time 2 http://100.103.49.98:11434/api/version
     curl -sf --max-time 1 http://10.0.0.2:11434/api/version
     

  4. If ANVIL should be reachable over Tailscale but is thenot, currentcheck verifiedTailscale countACL/binding ofwork from distributed-ai-factory-plan.md §4.

  ---

  Evidence Captured for This Runbook

  Verification artifacts for MC #8476 were saved under /tmp/verify-8476/, including:

  • BookStack shelf/book/page API metadata
  • exported BookStack markdown
  • process.env.OLLAMA_HOST consumers.match Re-baseline if this runbook is used as a compliance reference.lists
  • HardcodeQA/GOTCHA audit — a full-tree count of remaining localhost:11434/127.0.0.1:11434 references (excluding ollama-host.sh's own probe code) would tell CodeCraft how much refactor work is actually left; not completed here due to ~/system's size (23G) making a full recursive grep slow — a scoped follow-up task should target it.
  • Tailscale ACL — per architecture plan §4, ANVIL's Ollama port was not reachable from other Tailscale peers as of the plan's writing. This runbook does not re-verify that ACL state; treat §4's Tailscale ACL recommendation as still open unless confirmed otherwise.artifacts