Skip to content

NAS Infrastructure & Operational Model

Status: Authoritative Specification
Last Consolidated: 2026-09-09
Supersedes: nas-repository-convergence-model.md (Proposed), nas-mirror-standard.md (Ruling)

This document governs NAS operational placement, repository mirroring, and execution/storage constraints. For Beads/Dolt backup and restore-rehearsal requirements, see the Backup / Restore Contract. For model identity, serving, and gateway topology, see Inference Topology.

1. Governance Invariant (Canonical Mirroring)

GitLab at gitlab.com/blueflyio is the canonical source of truth for repository structure and subgroup taxonomy.

The NAS (/Volumes/AgentPlatform/Applications/) must mirror GitLab's subgroup taxonomy exactly:

/Volumes/AgentPlatform/Applications/
├── amcs/
│   └── site_template_amcs/
├── agent-platform/
│   ├── drupal/
│   │   ├── ai_agents_marketplace/
│   │   └── ai_agents_ossa/
│   ├── infra/
│   │   └── agent-docker/
│   ├── services/
│   │   ├── agent-protocol/
│   │   └── agent-tracer/
│   └── tools/
│       └── technical-docs/
├── agentictools/
│   ├── agentic-marketplace/
│   ├── agents/
│   └── skills/
└── blu/
    ├── blu-cli/
    ├── blucity/
    ├── blucity-packs/
    ├── blutown/
    └── blucity-docs/

Do not modify GitLab subgroup taxonomy to match a flat directory dump. Fix the NAS structure to mirror GitLab.

2. Technical Operational Constraints

  1. SMB Performance & Locks: SMB file protocol locks over network storage cause git operations (such as git status, git branch, or git fetch) to experience severe delays or timeouts.
  2. Worktree & Execution Invariant: Developers and AI agents MUST NOT construct normal execution worktrees directly over /Volumes/AgentPlatform/Applications.
  3. Execution Locations:
  4. Workstation execution worktrees belong in the governed local worktree area.
  5. Production/server execution worktrees belong on the governed runtime host.
  6. Clean Checkout Rule: Canonical NAS checkouts must remain clean mirrors, not feature-work destinations.
  7. Source / runtime separation: GitLab owns source; NAS may hold durable storage and mirrors; runtime authority remains with the owning runtime platform for each service.

3. Model Storage and Serving Role

The NAS is the durable store of record and the always-on host for Bluefly shared local model inference.

MODEL_STORAGE_SOR=/volume1/AgentPlatform/LLM
OLLAMA_PERSISTENT_STORE=/volume1/AgentPlatform/LLM/ollama/data
OLLAMA_SERVICE=blueflynas.tailcf98b3.ts.net:11434

This means:

  • model weights do not belong on Oracle;
  • the Mac may cache or test models but is not the shared serving authority;
  • shared inference must continue when the Mac is asleep or shut down;
  • phone, iPad, and other computers must be able to consume the same NAS-backed inference over the private network;
  • /volume1/docker/services/ollama-models may contain Docker-managed artifacts but is not the AgentPlatform LLM registry/store authority;
  • implementation wiring belongs in agent-docker / IaC and must project the Inference Topology.

A NAS disk copy without NAS-hosted serving is incomplete. The intended pattern is:

NAS stores model
NAS runs model server
Mac / phone / iPad / other computers consume
Oracle remains model-weight-free

Not:

NAS stores model
Mac runs shared model server against NAS storage

4. Current Convergence Notes

As of 2026-09-09, NAS Ollama was reachable and serving small models, while the primary Qwen coder was still being served by Mac-local Ollama. That is runtime drift from the binding topology, not a new architectural choice.

The canonical implementation task is therefore to converge agent-docker / NAS compose and client routing to the existing model-storage and serving contract, not to create a new gateway, new documentation owner, or Oracle model host.

5. Target Convergence Topology (Automation Spec)

Automated synchronization between GitLab, runtime hosts, and the NAS should use:

  • GitLab as source authority;
  • governed runtime deployment mechanisms for live services;
  • NAS background mirroring for durable repository replicas rather than interactive SMB git work;
  • NAS-backed model storage and serving for shared local inference;
  • Tailscale-governed private access for clients and gateways.