macos-ai-daemon-toolkit

Practical scripts and templates for running AI workloads as always-on macOS daemons.

Companion to My OpenClaw chronicles — What running local AI on a Mac Mini actually taught me: the 7 infrastructure walls I hit running a local AI shadow-testing system 24/7 on a Mac Mini M4, and the specific fixes for each one.

MIT licensed. Use freely, adapt as needed.

---

What's in here

File	Fixes	What it does
plists/caffeinate.plist	Gotcha #1	Prevents macOS from sleeping when idle — keeps the network alive
scripts/inject-env.sh	Gotcha #2	Bakes env vars directly into a LaunchAgent plist (setenv doesn't work)
scripts/install-github-release.sh	Gotcha #3	Downloads the latest release binary from any GitHub repo into ~/.local/bin
scripts/check-daemon-script.sh	Gotcha #6	Validates a Python script before deploying as a LaunchAgent
templates/daemon_template.py	Gotcha #6	Python daemon starter with correct startup logging
templates/embedding_store_template.py	Gotcha #7	Embedding store with fallback backend tagging for evaluation pipelines

---

Quick start

1. Stop your Mac from sleeping (Gotcha #1)

cp plists/caffeinate.plist ~/Library/LaunchAgents/com.local.caffeinate.plist
launchctl load ~/Library/LaunchAgents/com.local.caffeinate.plist

Verify it's working:

pmset -g assertions | grep caffeinate
# Should show: "THE CAFFEINATE TOOL IS PREVENTING SLEEP."

2. Bake a secret into a LaunchAgent plist (Gotcha #2)

chmod +x scripts/inject-env.sh
scripts/inject-env.sh ~/Library/LaunchAgents/my.service.plist API_TOKEN "sk-abc123"

3. Install a CLI tool without Homebrew admin rights (Gotcha #3)

chmod +x scripts/install-github-release.sh
scripts/install-github-release.sh jqlang/jq "jq-macos-arm64" ~/.local/bin

4. Validate a daemon script before deploying (Gotcha #6)

chmod +x scripts/check-daemon-script.sh
scripts/check-daemon-script.sh my_daemon.py

5. Start a new daemon from the template (Gotcha #6)

cp templates/daemon_template.py my_daemon.py
# Edit my_daemon.py, add your logic in run()
scripts/check-daemon-script.sh my_daemon.py  # validate first

---

The gotchas this covers

These are documented in detail in the blog post. Short version:

1. macOS sleeps by default — caffeinate.plist prevents it permanently
2. launchctl setenv doesn't affect LaunchAgents — inject-env.sh bakes vars into the plist directly
3. Non-admin accounts can't use Homebrew — install-github-release.sh bypasses it for most CLI tools
4. Node.js binary path changes silently revoke TCC permissions — no script fix, just don't do it; covered in README only
5. Python 3.14 breaks Pydantic V1 — check your deps before committing to a Python version
6. Syntax errors in daemon scripts fail silently — check-daemon-script.sh and daemon_template.py catch this before it costs you hours
7. Free-tier embedding APIs corrupt evaluation data without tagging — embedding_store_template.py shows the tagging pattern

---

Requirements

• macOS (Apple Silicon or Intel)
• bash (built-in)
• curl (built-in)
• jq for install-github-release.sh — install it first using the script itself:

  curl -L https://github.com/jqlang/jq/releases/latest/download/jq-macos-arm64 \
    -o ~/.local/bin/jq && chmod +x ~/.local/bin/jq

• Python 3.x for the Python templates

---

License

MIT — see LICENSE.