Skip to main content

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
Canonical references read:

  • ~/system/tools/ollama-host.sh
  • ~/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.

Resolution Strategy Implemented by ollama-host.sh

Actual live order in ~/system/tools/ollama-host.sh:

  1. Explicit environment override
    If OLLAMA_HOST is already set, the 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
    If the hostname contains makinja-sin-mac-studio or makinja.local, the script assumes it is running on ANVIL and sets:

    OLLAMA_HOST=http://localhost:11434

  4. Local probe
    Probe http://localhost:11434/api/version with a one-second timeout. If it responds, set:

    OLLAMA_HOST=http://localhost:11434

  5. Tailscale ANVIL probe
    Probe ANVIL over Tailscale with a two-second timeout:

    http://100.103.49.98:11434/api/version

    If it responds, set:

    OLLAMA_HOST=http://100.103.49.98:11434

  6. FORGE LAN probe
    Probe FORGE on LAN with a one-second timeout:

    http://10.0.0.2:11434/api/version

    If it responds, set:

    OLLAMA_HOST=http://10.0.0.2:11434

  7. Graceful degrade
    If none of the endpoints responds, write NONE to the cache, print a warning to stderr, and leave OLLAMA_HOST unset. The warning names the failed endpoints and states that Ollama-dependent agents will fail gracefully while Claude API agents continue normally.

Cache Behavior

  • Cache file: /tmp/ollama-host.cache
  • TTL: 300 seconds / five minutes (_OLLAMA_CACHE_TTL=300)
  • Value format: one line containing a resolved URL such as http://100.103.49.98:11434, or the literal NONE
  • Why it exists: avoids repeated curl timeouts on every shell or subprocess start
  • Platform detail: cache age uses macOS stat -f %m first and falls back to GNU stat -c %Y

Successful endpoint resolution writes the URL to the cache. A failed resolution writes NONE, so the host does not repeat the full probe ladder 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."
}

Use it after Tailscale reconnects, after Ollama starts/restarts, after ANVIL/FORGE network state changes, or after a stale NONE result is suspected.

The script also exports ollama_available():

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

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

How Refactored JS/Node Files Consume the Result

Refactored Node/JS code reads the environment value exported 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 and let ollama-host.sh resolve routing.

File-count note for MC #8476

The task description says “52 refactored files now read process.env.OLLAMA_HOST.” Current live verification on 2026-07-28 found:

Scope Verified count Evidence file
Source-like files under ~/system (*.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 treat 52 as the current live count unless separate dated implementation evidence is found.

Shell Integration (~/.zshrc)

The source line expected by ollama-host.sh is:

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

Current verification on this machine: ~/.zshrc was read and contains no ollama-host.sh, OLLAMA_HOST, or ollama source line. This runbook records the required line; adding it to ~/.zshrc is a follow-up operational change, not performed by this documentation task.

Operational Checklist

When a host cannot reach Ollama:

  1. Check the currently resolved value: 
    echo "$OLLAMA_HOST"
  2. Clear stale cache and re-resolve: 
    ollama_flush_cache
source ~/system/tools/ollama-host.sh
  3. Probe the expected endpoints manually: 
    curl -sf --max-time 1 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 not, check Tailscale ACL/binding work 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 match lists
  • QA/GOTCHA artifacts
Back to top