🌌 Tools Cache Mount
Share caches across your machines. Host-side shell tooling that NFS-mounts shared caches — Docker, Ollama, npm, Hugging Face — across the machines on your Tailscale, VPN, or LAN.
Open-source repository
CI-Tools-Cache-Mounts is open source under the PolyForm Noncommercial 1.0.0 license:
- Source code:
github.com/companionintelligence/CI-Tools-Cache-Mounts - Container registry:
ghcr.io/companionintelligence/ci-tools-cache-mounts:latest - Marketplace manifest: App ID
ci-tools-cache-mount
Install & availability
Available now. The host-side tooling scripts are open source in the repository, and a reference status dashboard is available in the Companion Hub App Store.
| Hub App Store | Search Tools Cache Mount → Install |
| Container internal port | 80 (static status dashboard; holds no state) |
| Minimum Hub version | 0.2.27 |
| Architecture | linux/amd64 and linux/arm64 (multi-arch) |
| Mount targets | Docker BuildKit, Ollama models, Hugging Face weights, npm/bun |
Tooling vs. container: Tools Cache Mount consists of two components: (1)
host-level shell scripts in
CI-Tools-Cache-Mounts
that mount NFS shares into your host operating system, and (2) a lightweight
Companion Hub container that serves a static status and reference page.
Installing the Hub app alone does not mount anything on your hosts.
Overview
Tools Cache Mount is host-side shell tooling, not a Hub service. Its install scripts run on each of your machines and NFS-mount shared cache directories — Docker BuildKit caches, Ollama models, npm, and Hugging Face — from a central NFS server reachable over your Tailscale, VPN, or LAN. Once mounted and pointed to, every machine reuses the same downloaded models and build caches instead of fetching its own copy.
Architecture and subsystems
Tools Cache Mount eliminates redundant downloads of multi-gigabyte machine learning models, container build layers, and package dependencies across personal fleets of developer workstations, Hub appliances, and remote compute nodes.
flowchart TD
subgraph SERVER["Central Cache Server (NFS)"]
EXP["NFS Daemon (NFSv4 / NFSv3)<br/>Base export: /srv/cache"]
D_CACHE[("/srv/cache/docker")]
O_CACHE[("/srv/cache/ollama")]
H_CACHE[("/srv/cache/huggingface")]
N_CACHE[("/srv/cache/npm")]
EXP --- D_CACHE & O_CACHE & H_CACHE & N_CACHE
end
subgraph NETWORK["Transport Mesh"]
TS["Tailscale / WireGuard VPN / Private LAN<br/>(Secure authenticated transport)"]
end
subgraph CLIENT_LINUX["Linux Client Host"]
FSTAB["/etc/fstab<br/>_netdev,soft,timeo=30"]
L_MNT["Mounts: /mnt/cache/*"]
L_TOOLS["Docker BuildKit · Ollama · npm"]
FSTAB --> L_MNT --> L_TOOLS
end
subgraph CLIENT_MAC["macOS Client Host"]
LAUNCHD["launchd Daemon<br/>com.ci.cache-mounts.plist"]
M_MNT["Mounts: /Volumes/cache-*"]
M_TOOLS["Docker Desktop · Ollama · HF"]
LAUNCHD --> M_MNT --> M_TOOLS
end
SERVER <--> NETWORK
NETWORK <--> CLIENT_LINUX
NETWORK <--> CLIENT_MACSupported cache targets and environment bindings
Once mounted, applications and build tools are directed to the shared mounts using standard environment variables and configuration files:
| Target | Linux mount path | macOS mount path | Tool configuration |
|---|---|---|---|
| Ollama models | /mnt/cache/ollama | /Volumes/cache-ollama | Set OLLAMA_MODELS=/mnt/cache/ollama in systemd or shell env. |
| Hugging Face | /mnt/cache/huggingface | /Volumes/cache-huggingface | Set HF_HOME=/mnt/cache/huggingface in shell env. |
| Docker BuildKit | /mnt/cache/docker | /Volumes/cache-docker | --cache-from type=local,src=/mnt/cache/docker--cache-to type=local,dest=/mnt/cache/docker,mode=max |
| npm package cache | /mnt/cache/npm | /Volumes/cache-npm | Run npm config set cache /mnt/cache/npm --global. |
| Bun cache | /mnt/cache/bun | /Volumes/cache-bun | Set BUN_INSTALL_CACHE_DIR=/mnt/cache/bun in shell env. |
Mount automation and resiliency
To prevent system hangs when traveling or disconnecting from the VPN:
- Linux (
scripts/linux_install.sh): Configures/etc/fstabwith_netdev(defers mounting until network interfaces are online) andsoft,timeo=30,retrans=2(fails I/O operations gracefully instead of hard-locking processes if the server becomes unreachable). - macOS (
scripts/macos_install.sh): Generates alaunchdjob that executesmacos_mount.shwith a 300-second polling watchdog and clean unmount handlers (macos_unmount.sh). - Network trust boundary: NFS traffic is unencrypted by default and relies on host-level authentication, so
CACHE_SERVERexports must be restricted to trusted Tailscale, WireGuard VPN, or isolated LAN subnets.
Current capabilities
What Tools Cache Mount provides today:
- Per-host install scripts (
linux_install.sh,macos_install.sh) that set up NFS mounts of shared caches - Sharing of Docker (BuildKit
type=local), Ollama models, npm, and Hugging Face caches - Auto-mount on boot via fstab
_netdev(Linux) or a launchd retry timer (macOS) - A status / reference page served by the Hub container
You must provide the NFS server. No server ships with this app. You need an NFS server on your network exporting /srv/cache/<name> directories; the client scripts mount from it.
How it actually works
- Stand up an NFS server (your responsibility) exporting
/srv/cache/<name>for each cache you want to share (e.g.docker,ollama,npm,huggingface). - Create
cache-mounts.confon each client host by copyingcache-mounts.conf.example, and setCACHE_SERVERto that NFS server. - Run the install script on each client (
linux_install.shormacos_install.sh). It configures the NFS mounts and auto-mount. - Re-point your tools at the mounted caches — mounting alone changes nothing.
The same four steps, as the data path from your NFS server to each tool on a client host:
flowchart TD
NFS["Your NFS server<br/>exports /srv/cache/docker, ollama, npm, huggingface"] -->|"NFS over Tailscale, VPN, or LAN"| MNT
subgraph HOST["Each client host"]
CONF["cache-mounts.conf<br/>CACHE_SERVER = your NFS server"] --> INST["linux_install.sh<br/>or macos_install.sh"]
INST --> MNT["NFS mounts + auto-mount<br/>fstab _netdev on Linux<br/>launchd retry on macOS"]
MNT -->|"re-point each tool"| TOOLS["OLLAMA_MODELS · HF_HOME<br/>npm config set cache · BuildKit type=local"]
endDefault cache layout
| Cache | Server export | Linux mount | macOS mount |
|---|---|---|---|
docker | /srv/cache/docker | /mnt/cache/docker | /Volumes/cache-docker |
ollama | /srv/cache/ollama | /mnt/cache/ollama | /Volumes/cache-ollama |
npm | /srv/cache/npm | /mnt/cache/npm | /Volumes/cache-npm |
huggingface | /srv/cache/huggingface | /mnt/cache/huggingface | /Volumes/cache-huggingface |
Configuration
The scripts read cache-mounts.conf from the repository root, whichever directory you run them from. Set CACHE_MOUNTS_CONFIG=/path/to/conf to use a different file.
| Variable | Default | Purpose |
|---|---|---|
CACHE_SERVER | none | Hostname or IP of the NFS server, reachable on your VPN or LAN. Required. |
CACHE_NAMES | docker ollama npm huggingface | Caches to mount, separated by spaces or commas |
CACHE_EXPORT_BASE | /srv/cache | Export root on the server |
CACHE_EXPORT_<NAME>, CACHE_MOUNT_<NAME> | derived | Per-cache overrides, for example CACHE_EXPORT_HUGGINGFACE and CACHE_MOUNT_HUGGINGFACE |
Auto-mount details
| Auto-mount | Linux | macOS |
|---|---|---|
| Install script | linux_install.sh | macos_install.sh |
| Mechanism | An fstab entry with _netdev (fstab, not a systemd automount unit) | A launchd job that retries every ~5 minutes to (re)establish the mount |
| Mounts when | On boot, once the network is up | At each retry, until the mount is established |
| Needs | The NFS server reachable once networking is up | Passwordless sudo to run the mount |
| NFS client | nfs-common on Ubuntu and Debian. The install script installs it with apt-get. | Built in |
On Linux, linux_install.sh backs up /etc/fstab to /etc/fstab.cache-mounts.bak.<timestamp>, adds the entries, and mounts now. Rerun it after you change the configuration, because it writes the resolved server and export paths into /etc/fstab. To mount or unmount by hand, use linux_mount.sh, linux_unmount.sh, macos_mount.sh, or macos_unmount.sh.
Re-pointing tools (required)
Mounting a cache does nothing until each tool is told to use it:
| Tool | What to set |
|---|---|
| Ollama | export OLLAMA_MODELS=/mnt/cache/ollama (Linux) or /Volumes/cache-ollama (macOS) |
| Hugging Face | export HF_HOME=/mnt/cache/huggingface (Linux) or /Volumes/cache-huggingface (macOS) |
| npm | npm config set cache /mnt/cache/npm |
| Docker | BuildKit type=local cache sharing: docker buildx build --cache-to type=local,dest=/mnt/cache/docker/buildkit --cache-from type=local,src=/mnt/cache/docker/buildkit … |
Docker caching here is BuildKit type=local cache sharing, not Docker
image-layer caching. You opt in per build with BuildKit cache flags pointing
at the shared local cache directory. For real image-layer caching, the
repository’s Docker cache notes describe running a registry pull-through proxy
on the cache server as an optional upgrade.
Use cases
- Download a model once and share it across every machine on your Tailnet
- Share a BuildKit local cache so CI/build hosts don’t rebuild identical layers
- Keep npm and Hugging Face caches consistent across a small fleet
Setup
Provide an NFS server
Stand up an NFS server on your Tailscale/VPN/LAN exporting /srv/cache/<name> for each cache you want to share. (No server ships with this app.)
Create cache-mounts.conf
On each client host, copy cache-mounts.conf.example to cache-mounts.conf and set CACHE_SERVER to your NFS server. Set CACHE_NAMES if you don’t want all four caches.
Run the install script
Run linux_install.sh (Linux) or macos_install.sh (macOS) on each client. This sets up the NFS mounts and auto-mount (fstab _netdev on Linux; a launchd retry on macOS that needs passwordless sudo).
Re-point your tools
Set OLLAMA_MODELS, HF_HOME, npm config set cache …, and use BuildKit type=local cache sharing for Docker so the tools actually use the mounted caches.
Troubleshooting
Installed the Hub app but nothing is shared The Hub container is only a status/reference page. Run the install scripts on each host to actually mount the caches.
Tools still download their own copies
Mounting isn’t enough — re-point each tool (OLLAMA_MODELS, HF_HOME, npm cache, BuildKit type=local).
Mount doesn’t come back after reboot (macOS) The launchd retry needs passwordless sudo to run the mount. Verify the sudoers entry, then wait for the next ~5-minute retry.
Mount missing on Linux boot
Confirm the fstab entry includes _netdev and the NFS server is reachable once networking is up.