Skip to Content
DocumentationTools Cache Mount

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

Tools Cache Mount topology: shared network cache layers mounted on distributed client hosts to avoid redundant downloads and rebuilds.

Open-source repository

CI-Tools-Cache-Mounts is open source under the PolyForm Noncommercial 1.0.0 license:

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 StoreSearch Tools Cache Mount → Install
Container internal port80 (static status dashboard; holds no state)
Minimum Hub version0.2.27
Architecturelinux/amd64 and linux/arm64 (multi-arch)
Mount targetsDocker 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.

Supported cache targets and environment bindings

Once mounted, applications and build tools are directed to the shared mounts using standard environment variables and configuration files:

TargetLinux mount pathmacOS mount pathTool configuration
Ollama models/mnt/cache/ollama/Volumes/cache-ollamaSet OLLAMA_MODELS=/mnt/cache/ollama in systemd or shell env.
Hugging Face/mnt/cache/huggingface/Volumes/cache-huggingfaceSet 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-npmRun npm config set cache /mnt/cache/npm --global.
Bun cache/mnt/cache/bun/Volumes/cache-bunSet 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/fstab with _netdev (defers mounting until network interfaces are online) and soft,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 a launchd job that executes macos_mount.sh with 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_SERVER exports 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

  1. Stand up an NFS server (your responsibility) exporting /srv/cache/<name> for each cache you want to share (e.g. docker, ollama, npm, huggingface).
  2. Create cache-mounts.conf on each client host by copying cache-mounts.conf.example, and set CACHE_SERVER to that NFS server.
  3. Run the install script on each client (linux_install.sh or macos_install.sh). It configures the NFS mounts and auto-mount.
  4. 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:

Default cache layout

CacheServer exportLinux mountmacOS 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.

VariableDefaultPurpose
CACHE_SERVERnoneHostname or IP of the NFS server, reachable on your VPN or LAN. Required.
CACHE_NAMESdocker ollama npm huggingfaceCaches to mount, separated by spaces or commas
CACHE_EXPORT_BASE/srv/cacheExport root on the server
CACHE_EXPORT_<NAME>, CACHE_MOUNT_<NAME>derivedPer-cache overrides, for example CACHE_EXPORT_HUGGINGFACE and CACHE_MOUNT_HUGGINGFACE

Auto-mount details

Auto-mountLinuxmacOS
Install scriptlinux_install.shmacos_install.sh
MechanismAn fstab entry with _netdev (fstab, not a systemd automount unit)A launchd job that retries every ~5 minutes to (re)establish the mount
Mounts whenOn boot, once the network is upAt each retry, until the mount is established
NeedsThe NFS server reachable once networking is upPasswordless sudo to run the mount
NFS clientnfs-common on Ubuntu and Debian. The install script installs it with apt-get.Built in
How each install script keeps the share mounted after a reboot.

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:

ToolWhat to set
Ollamaexport OLLAMA_MODELS=/mnt/cache/ollama (Linux) or /Volumes/cache-ollama (macOS)
Hugging Faceexport HF_HOME=/mnt/cache/huggingface (Linux) or /Volumes/cache-huggingface (macOS)
npmnpm config set cache /mnt/cache/npm
DockerBuildKit 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.

Last updated on