ai-model-usb

Portable macOS helper script for carrying Ollama and Hugging Face model caches on a USB drive.

The script is intended to live at the USB root:

cd /Volumes/<USB_NAME>
./ai-model-usb status

It detects the USB root from its own location, so no install step is required on a new Mac.

Layout

Preferred USB layout:

ai-models/
  ollama/
    models/
  huggingface/
    hub/
ai-model-usb

Existing legacy paths are also supported when the preferred paths do not exist:

ollama-settings/models
huggingface-models/hub

Commands

Show detected paths and cache sizes:

./ai-model-usb status

List models without requiring the Ollama server:

./ai-model-usb list usb
./ai-model-usb list local
./ai-model-usb list all

Use models directly from the USB on the current Mac:

./ai-model-usb use-usb on --yes

Stop using the USB on the current Mac:

./ai-model-usb use-usb off --yes

Copy selected local models to the USB:

./ai-model-usb copy-from-local --ollama qwen3.5:4b --yes
./ai-model-usb copy-from-local --hf mlx-community/Qwen3.5-4B-MLX-4bit --yes

Copy selected USB models to the current Mac:

./ai-model-usb copy-to-local --ollama qwen3.5:4b --yes
./ai-model-usb copy-to-local --hf mlx-community/Qwen3.5-4B-MLX-4bit --yes

If no selector is provided, copy commands default to --all.

Copy commands only copy model files. They do not update .zshrc or switch the active Hugging Face cache path.

What It Changes

use-usb on:

• Links ~/.ollama/models to the detected USB Ollama model path.
• Adds a managed block to ~/.zshrc setting HF_HUB_CACHE to the detected USB Hugging Face Hub path.
• Backs up conflicting local paths before replacing them.

use-usb off:

• Removes the USB symlink at ~/.ollama/models when it points to this USB.
• Creates a real local ~/.ollama/models directory.
• Removes only the managed ai-model-usb block from ~/.zshrc.

Hugging Face tokens and auth files are never copied to the USB. Only Hub cache repositories under hub/models--... are copied.

Model-Level Copy

Hugging Face models are copied by repo cache directory:

mlx-community/Qwen3.5-4B-MLX-4bit
hub/models--mlx-community--Qwen3.5-4B-MLX-4bit

Ollama models are copied by manifest plus referenced blobs:

qwen3.5:4b
models/manifests/registry.ollama.ai/library/qwen3.5/4b
models/blobs/sha256-...

The script reads the Ollama manifest with jq and copies the referenced .config.digest and .layers[].digest blobs.

Requirements

• macOS
• zsh
• rsync
• jq for selected Ollama model copies

Development

Run syntax and behavior checks:

zsh -n ai-model-usb
zsh tests/test_ai_model_usb.zsh