How to Install SAM3 in LightCraft

Written as of LightCraft version 0.14.0. Due to rapid development, instructions may not apply when you read this.

Official SAM3 Hugging Face | LightCraft GitHub

LightCraft for macOS doesn’t ship with SAM3 model necessary for automatic object mask selection, and facebook/sam3 is gated — unauthenticated requests to its files return 401 until Meta approves your licence request. But if you’re like me who got their request rejected, here are a couple options to get it.

Option A — use the installer with an ungated mirror (easiest)

From the LightCraft repo root:

./tools/install-sam3.sh --repo jetjodh/sam3

It installs into the correct folder, resumes if interrupted, and SHA-256-checks the 3.4 GB of weights, deleting the file if it doesn’t match.

Option B — no repo? Grab the 3 files by hand

Thankfully for us, several unofficial mirrors exist right on Hugging Face itself. Download an unofficial mirror from Hugging Face.

DEST="$HOME/Library/Application Support/LightCraft/models/sam3"
BASE="https://huggingface.co/jetjodh/sam3/resolve/main"
mkdir -p "$DEST"
for f in model.safetensors vocab.json merges.txt; do
  curl -fL --retry 3 -C - -o "$DEST/$f" "$BASE/$f"
done

Verify

cd "$HOME/Library/Application Support/LightCraft/models/sam3"
shasum -a 256 model.safetensors vocab.json merges.txt

Then quit and relaunch LightCraft — it reads model status at startup, so a running instance won’t pick the files up.

Notes

• The weights hash is the official checkpoint pin; if it matches, the bytes are Meta’s regardless of who hosted them. merges.txt above is also byte-identical to OpenAI’s CLIP merges.txt, and vocab.json matches every other working mirror (7 of 7 checked).
• Avoid Justin331/sam3 — same weights, but its merges.txt is a different tokenizer (573,514 bytes) and text prompts tokenize wrongly.
• The SAM License still applies to your use of the weights; an ungated copy grants no extra rights.
• If you ever do get HF access: HF_TOKEN=hf_... ./tools/install-sam3.sh (hf auth login may be broken if Homebrew’s python@3.14 was removed — use the env var).
• Optional, for future in-app downloads: put https://huggingface.co/jetjodh/sam3/resolve/main in models/sam3-mirrors.txt in LightCraft’s settings folder.
• Linux/Windows: replace the DEST path with ${XDG_CONFIG_HOME:-$HOME/.config}/lightcraft/models/sam3 or %APPDATA%\LightCraft\models\sam3, and use sha256sum instead of shasum -a 256.