🌌 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.

Install & availability

Available now. Install from the Companion Hub App Store. Note that the Hub app is only a status / reference page — see below.


Hub App Store	Search Tools Cache Mount → Install
Container image	`ghcr.io/companionintelligence/ci-tools-cache-mounts:latest` (public)
Container internal port	`80`
Architecture	`linux/amd64` and `linux/arm64` (multi-arch)
State / env	None — the container holds no state and takes no configuration

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, 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.

Installing the Hub app does not mount anything. The container is a static status / reference page describing the tooling. The actual mounting is done by running the install scripts on each client host. This page documents the real workflow.

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.conf on each client host, setting CACHE_SERVER to that NFS server.
Run the install script on each client (linux_install.sh or macos_install.sh). It configures the NFS mounts and auto-mount.
Re-point your tools at the mounted caches — mounting alone changes nothing.

Auto-mount details

Linux: an fstab entry with _netdev mounts the share on boot once the network is up (this is fstab, not a systemd automount unit).
macOS: a launchd job retries every ~5 minutes to (re)establish the mount; it needs passwordless sudo to run the mount.

Re-pointing tools (required)

Mounting a cache does nothing until each tool is told to use it:

Tool	What to set
Ollama	`OLLAMA_MODELS` → mounted models path
Hugging Face	`HF_HOME` → mounted HF cache path
npm	`npm config set cache <mounted path>`
Docker	BuildKit `type=local` cache sharing (in your build invocation)

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.

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, create cache-mounts.conf with CACHE_SERVER pointing at your NFS server.

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.