🌌 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

The Hub app is available, but it is only a status page. Install it from the Companion Hub App Store. The tooling that does the work isn’t publicly available yet — see the status note below.

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.

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

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:

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"]
    end

Default cache layout

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.

Auto-mount details

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:

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

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.

Links

• Static Container Builder
• Local Bench