Mac mini 24 GB setup sheet

0Preflight

Ten minutes of checks that stop you discovering a problem two hours in.

1. Confirm you are on the machine you think you are2 min

   Run all four. hw.memsize must print 24; if it prints 16 or 32, the tuning numbers in phase 3 are wrong for this box and need rescaling.

   sw_vers
   sysctl -n hw.memsize | awk '{printf "RAM: %.0f GB\n", $1/1073741824}'
   system_profiler SPHardwareDataType | awk -F': ' '/Model Name|Chip|Total Number of Cores|Serial Number/ {print $1": "$2}'
   df -h / | awk 'NR==2 {print "Free disk: "$4" of "$2}'

   Gate

   Keep at least 60 GB free. Homebrew, Postgres, Node and the repo want ~8 GB; the rest is headroom for logs, Time Machine local snapshots, and — if you go that way — local model weights at 5–10 GB each. Under 60 GB, plan on a cloud boss model only.

2. Name the machine1 min

   All three names, or Bonjour and the shell prompt disagree with each other forever.

   sudo scutil --set ComputerName  hudson-mini
   sudo scutil --set HostName      hudson-mini
   sudo scutil --set LocalHostName hudson-mini
   # reachable afterwards at hudson-mini.local

3. Decide the account model5 min

   Use one dedicated macOS account for the whole stack — call it hudson — not your daily-driver login. Everything in this sheet installs into that account's home directory: ~/.hermes, ~/repos/project-hudson, the Homebrew services, the Claude Code credentials.

   It needs administrator rights during install (Homebrew, pmset, scutil). It is the account that will be auto-logged-in in step 1.2, so treat it as a service account: no personal iCloud, no browser sessions, no other secrets.

4. Turn on remote access before you unplug the display3 min

   System Settings → General → Sharing → enable Remote Login (SSH) and Screen Sharing. The GUI toggle is the reliable path; the CLI equivalent needs Full Disk Access granted to Terminal on current macOS:

   sudo systemsetup -setremotelogin on
   sudo systemsetup -getremotelogin

   Then prove it from your laptop before the mini goes headless:

   ssh hudson@hudson-mini.local

5. Give it a stable address5 min

   Ethernet if the port is anywhere near it — a Wi-Fi drop is the most common cause of a bot that "just stopped answering". Add a DHCP reservation on the router so the address survives reboots, and record it in the machine record above.

1Make macOS behave like a server

macOS defaults assume someone is sitting in front of it. Three settings and one honest trade-off fix that.

1. Never sleep, wake for the network, come back after a power cut2 min

   sudo pmset -a sleep 0 disksleep 0 displaysleep 15
   sudo pmset -a womp 1 autorestart 1
   pmset -g   # verify: sleep 0, disksleep 0, womp 1, autorestart 1

   Display sleep is fine to leave on — it does not suspend the daemon, and a headless mini has no display to speak of. autorestart 1 is the one that matters after a building power blip.

2. Settle FileVault vs. unattended boot — this is the decision that bites10 min

   Both halves of this stack start as LaunchAgents: hermes gateway install registers one, and brew services start registers one for Postgres. A LaunchAgent only runs inside a logged-in user session. With FileVault on and no auto-login, a reboot leaves the disk locked at the login window — and the bot is silent until a human types a password.

   Option	Boots back unattended?	What you accept
   FileVault off + automatic login recommended for a physically secure location	Yes	Disk is readable to anyone who walks off with the mini — and it holds a bot token, API keys, and a Claude session.
   FileVault on, no auto-login	No	Every reboot and power cut needs a person at a screen. Use sudo fdesetup authrestart for planned reboots — it unlocks once on next boot — but power loss still parks it.
   FileVault on + a UPS	Mostly	Removes the power-cut case, not the crash case. The pragmatic middle if the mini lives somewhere shared.

   fdesetup status
   # auto-login lives in System Settings → Users & Groups → Automatic login
   # (the menu is greyed out while FileVault is enabled)
   sudo fdesetup authrestart   # planned reboot that unlocks itself once

   Write the choice into the machine record. Every "the bot went quiet overnight" report traces back to this line.

3. Stop macOS from rebooting itself3 min

   System Settings → General → Software Update → Automatic Updates:

   • Keep on: "Install Security Responses and system files" — no reboot, real protection.
   • Turn off: "Install macOS updates" and "Install application updates from the App Store".

   An unattended OS upgrade reboots the machine, and — with FileVault on — leaves it at the login window. Do updates on your schedule, then re-run the reboot test in phase 6.

   softwareupdate --list   # see what's pending, on your terms

4. Point Time Machine at something5 min

   An external SSD or a NAS share. It is not a substitute for the repo-native bundle in step 6.4 — Time Machine gives you the machine back, pack-for-move.sh gives you the agent back — but on an always-on box that will accumulate state, you want both.

2Base tooling

Xcode command line tools, Homebrew, the runtimes, and the Claude Code login.

1. Xcode command line tools5 min

   xcode-select --install   # GUI installer; skip if already present
   xcode-select -p          # expect /Library/Developer/CommandLineTools

2. Homebrew, on PATH for real5 min

   Apple silicon installs to /opt/homebrew, which is not on the default PATH. The shellenv line is what makes it stick for future sessions — including the ones launchd will start.

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
   eval "$(/opt/homebrew/bin/brew shellenv)"
   brew --version

3. The packages10 min

   brew install node python ripgrep ffmpeg git uv

   node runs the Claude Code CLI · uv runs the Postgres MCP server via uvx · ripgrep and ffmpeg are Hermes dependencies.

   Skip Docker on this box

   The native Postgres path in phase 3 is the default for the mini precisely so you do not pay for Docker Desktop's Linux VM — it reserves multiple gigabytes of your 24 up front and adds a second thing that must survive reboot. Install Docker only if you have another reason to.

4. Claude Code, logged in once5 min

   This login is what the 17 specialists run on, no matter which model you later give the Hermes boss layer.

   npm install -g @anthropic-ai/claude-code
   claude          # log in, then /exit
   claude doctor   # expect a clean install report

3The repo and the memory database

Cloning is the install. The only real work here is tuning Postgres for 24 GB — the Homebrew defaults are sized for a laptop that also runs a browser.

1. Clone the repo1 min

   mkdir -p ~/repos
   git clone https://github.com/lciamp/project-hudson.git ~/repos/project-hudson
   cd ~/repos/project-hudson

   The 17 subagents in .claude/agents/ and the 60 skills in .claude/skills/ register with Claude Code automatically — there is nothing else to install for the team itself.

2. Run the native Postgres setup10 min

   scripts/setup-native-postgres.sh

   It installs postgresql@18 + pgvector, starts the service, rewrites pg_hba.conf so TCP connections need scram-sha-256, creates the project_hudson role and database, applies db/init/01-schema.sql, and then proves the hardening by checking that a passwordless TCP connection is refused on both 127.0.0.1 and ::1. It is idempotent, and it refuses to run if anything else already holds port 5432.

3. Apply the 24 GB tuning10 min

   Homebrew ships shared_buffers = 128MB and maintenance_work_mem = 64MB — enough to make HNSW index builds crawl. Back up the config, append the block, restart.

   PG=/opt/homebrew/opt/postgresql@18/bin
   CONF=$("$PG/psql" -d postgres -tAc "SHOW config_file")
   echo "$CONF"
   cp "$CONF" "$CONF.bak-$(date +%F)"

   cat >> "$CONF" <<'EOF'
   
   # ── project-hudson · Mac mini, 24 GB unified memory ──────────
   shared_buffers = 2GB
   effective_cache_size = 6GB
   work_mem = 32MB
   maintenance_work_mem = 1GB
   max_connections = 40
   
   max_wal_size = 2GB
   min_wal_size = 512MB
   checkpoint_completion_target = 0.9
   
   random_page_cost = 1.1
   effective_io_concurrency = 200
   
   max_worker_processes = 8
   max_parallel_workers = 4
   max_parallel_workers_per_gather = 2
   max_parallel_maintenance_workers = 2
   
   jit = off
   hnsw.ef_search = 100
   log_min_duration_statement = 500ms
   EOF
   
   brew services restart postgresql@18

   "$PG/psql" -d project_hudson \
     -c "SHOW shared_buffers" -c "SHOW work_mem" \
     -c "SHOW maintenance_work_mem" -c "SHOW jit"

   Every number and the reasoning behind it is in the settings reference below. Short version: this box is not a database server — it is a database plus a gateway plus however many Node processes Claude Code spawns, so Postgres deliberately takes about 8% of RAM rather than the textbook 25%.

   If Postgres refuses to start

   Restore the backup and restart: cp "$CONF.bak-$(date +%F)" "$CONF" && brew services restart postgresql@18. Then re-add lines a few at a time. The log is at /opt/homebrew/var/log/postgresql@18.log.

4. Approve the MCP server3 min

   Run claude once inside the repo and approve the postgres server from .mcp.json. This also caches the workspace-trust prompt for the directory, which is what lets Hermes-spawned headless sessions run without stalling on a dialog nobody is there to answer.

   claude
   # approve the postgres MCP server when prompted, then:
   # /mcp   → postgres should read "connected"
   # /exit

5. Smoke-test the memory store2 min

   PGPASSWORD=project_hudson_dev /opt/homebrew/opt/postgresql@18/bin/psql \
     -h localhost -U project_hudson -d project_hudson \
     -c "SELECT extversion FROM pg_extension WHERE extname='vector'" \
     -c "SELECT count(*) FROM memories"

   A pgvector version and a row count (0 on a fresh install) means the whole path works: TCP, password auth, extension, schema.

6. Restore from another machine15 min

   Only if this mini is replacing an existing setup. Unzip the bundle from scripts/pack-for-move.sh and follow its RESTORE.md: drop the repo in place, restore the Claude auto-memory folder, fix the absolute paths inside .claude/settings.local.json, then load the rows.

   /opt/homebrew/opt/postgresql@18/bin/psql \
     'postgresql://project_hudson:project_hudson_dev@localhost:5432/project_hudson' \
     < memories-dump.sql

4Hermes, the always-on boss

The Telegram-facing daemon. Everything up to here works without it — claude in the repo is already the boss. This is what puts it on your phone.

1. Install Hermes and pin the version10 min

   The installer is curl-pipe-bash. Download it, read it, then run it — on a machine that is about to hold your bot token and API keys, that is not paranoia.

   curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o /tmp/hermes-install.sh
   less /tmp/hermes-install.sh   # read before running
   bash /tmp/hermes-install.sh
   source ~/.zshrc
   hermes --version              # record this — pin it, don't auto-update

   Config lands in ~/.hermes/config.yaml, secrets in ~/.hermes/.env.

2. Pick the boss model — with the 24 GB rule in mind10 min

   hermes model   # interactive picker
   # Claude Max subscription (no per-token billing; Pro is not eligible):
   hermes auth add anthropic --type oauth

   Only the boss layer runs on this model — the 17 specialists always run on Claude via the claude login from phase 2. Qwen, OpenAI, DeepSeek, OpenRouter and Bedrock all work here.

   On 24 GB, prefer a hosted boss model

   A local model is the one thing that can genuinely starve this box. If you want one anyway, the sizing table gives the ceiling: roughly 14 B at Q4, and not while a heavy Claude Code session is running.

3. Create the Telegram bot10 min
   1. Message @BotFather → /newbot → copy the token.
   2. Message @userinfobot → copy your numeric user ID.
   3. Write both into ~/.hermes/.env, then lock the file down.

   cat >> ~/.hermes/.env <<'EOF'
   TELEGRAM_BOT_TOKEN=<token from BotFather>
   TELEGRAM_ALLOWED_USERS=<your numeric user ID>
   EOF
   chmod 600 ~/.hermes/.env

   Never run allow-all

   Always set TELEGRAM_ALLOWED_USERS, and never GATEWAY_ALLOW_ALL_USERS=true — a documented fail-open left gateways accepting DMs from any Telegram account. Admit anyone else with Hermes pairing codes, which expire after an hour. The full Telegram walkthrough is in the Telegram setup guide.

4. Start the gateway and register it with launchd5 min

   hermes gateway setup     # wizard
   hermes gateway start
   hermes gateway status    # logs: ~/.hermes/logs/gateway.log
   hermes gateway install   # LaunchAgent — starts at login

   launchd quirks worth knowing now

   • Never use a bare restart — there is a race. Use hermes gateway stop && sleep 5 && hermes gateway start.
   • Exit-78 config errors can wedge launchd.
   • On macOS 26+ it can silently fall back to a detached process with no auto-start and no crash restart. Check hermes gateway status after every reboot.
   • One bot token per gateway — Telegram rejects concurrent polling, so stop the laptop's instance if you have one.
5. Make Hermes a thin relay2 min

   Send this as your first message to the bot, so it lands in Hermes's own memory. Substitute the real account name.

   For any project-hudson work, use the claude-code skill with workdir
   /Users/hudson/repos/project-hudson, print mode, and resume sessions rather
   than starting new ones for follow-ups. Don't answer project-hudson questions
   from your own tools.

   Without this you get two competing orchestrators, and the gates that live in CLAUDE.md — security review after auth or infra changes, chaos validation for failover claims, the approval boundaries — get quietly skipped.

5Permissions and hardening

This machine is an internet-reachable agent with shell access. Ten minutes here is cheap.

1. Pre-authorize tools in the repo5 min

   A headless session cannot answer a permission prompt — it just stops. Commit the allow rules so every Hermes-spawned session inherits them.

   {
     "permissions": {
       "allow": [
         "Read",
         "Edit",
         "Bash(git status:*)",
         "Bash(git diff:*)",
         "Bash(git log:*)"
       ]
     }
   }

   Scope Bash to exact subcommands

   Never write Bash(git *). git runs arbitrary programs through -c core.pager=…, -c core.sshCommand=… and aliases, so a "git-only" wildcard is full shell access to anyone who can prompt-inject the bot.

2. Guardrails on every dispatch2 min

   Always --max-turns and --max-budget-usd. Never --dangerously-skip-permissions or bypassPermissions on this box — the approval boundaries in AGENTS.md (no live terraform apply, no destructive SQL, no paging real humans) only bind while enforcement is on.

3. Confirm the database is loopback-only2 min

   lsof -nP -iTCP:5432 -sTCP:LISTEN

   Expect 127.0.0.1:5432 and [::1]:5432 — never *:5432. The project_hudson:project_hudson_dev credential is local-development-only and stays acceptable exactly as long as that holds. If this database ever needs to be reachable off-box, the credential comes from Vault or AWS Secrets Manager instead, never from a file in the repo.

4. Secrets and surface5 min
   • chmod 600 ~/.hermes/.env — and keep the bot token out of the repo. If it leaks, revoke it in BotFather immediately.
   • Turn the macOS firewall on (System Settings → Network → Firewall) and allow only Remote Login and Screen Sharing.
   • Do not add the bot to public groups. Every message it can read is prompt-injection surface for an agent that can run shell commands.
   • Ignore third-party "auth bypass" add-ons — that whole category is a credential-theft vector. Official Max OAuth covers it.

6Prove it, then walk away

An always-on box is only as good as its last reboot test. Do these four before you trust it unattended.

1. The reboot test10 min

   sudo shutdown -r now
   
   # wait ~90s, then from the laptop:
   ssh hudson@hudson-mini.local 'hermes gateway status; brew services list | grep postgres'

   Expect the gateway running and postgresql@18 started. If both are down, you are looking at the phase 1.2 trade-off: LaunchAgents need a logged-in session, and without auto-login there isn't one.

2. End-to-end from the phone5 min
   1. Ask the bot: "in the project-hudson repo, list your agents" → expect the 17 specialists.
   2. Send a routed task: "find 5 product ideas in the dev-tools niche" → it should dispatch into Claude Code and come back through product-researcher and the market-niche-scan skill.

   If the answer looks like Hermes improvising rather than the team, the thin-relay instruction from step 4.5 did not stick — send it again.

3. Watch memory under real load5 min

   While that routed task is actually running, on the mini:

   memory_pressure | head -5
   sysctl vm.swapusage
   top -l 1 -o mem -n 12 -stats pid,command,mem

   Healthy on 24 GB: memory pressure "normal", swap used in the low hundreds of MB or less. Sustained swap in the gigabytes means something is oversized — usually a local model, occasionally shared_buffers if you raised it past 2 GB. Compare against the budget.

4. Take the first bundle3 min

   scripts/pack-for-move.sh ~/Desktop

   Repo + Claude auto-memory + a dump of the memories table + a generated RESTORE.md, in one zip. Copy it off the machine. This is the artifact that makes the mini replaceable.

5. Nightly database dump10 min

   Optional, and worth it once the memory store has real rows in it. Write the plist, then load it — nothing installs itself.

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
     "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
     <key>Label</key><string>com.hudson.pgdump</string>
     <key>ProgramArguments</key>
     <array>
       <string>/bin/sh</string>
       <string>-c</string>
       <string>PGPASSWORD=project_hudson_dev /opt/homebrew/opt/postgresql@18/bin/pg_dump -h localhost -U project_hudson --clean --if-exists project_hudson > "$HOME/backups/memories-$(date +%F).sql" && find "$HOME/backups" -name 'memories-*.sql' -mtime +14 -delete</string>
     </array>
     <key>StartCalendarInterval</key>
     <dict><key>Hour</key><integer>3</integer><key>Minute</key><integer>30</integer></dict>
     <key>StandardErrorPath</key><string>/tmp/hudson-pgdump.err</string>
   </dict>
   </plist>

   mkdir -p ~/backups
   launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.hudson.pgdump.plist
   launchctl kickstart -k gui/$(id -u)/com.hudson.pgdump   # run it once, now
   ls -lh ~/backups

   Same LaunchAgent caveat as everything else here: it runs at login, keeps 14 days, and writes errors to /tmp/hudson-pgdump.err.

24 GB memory budget

What the box actually spends, so you can tell "busy" from "oversubscribed" at a glance. Peaks are what you see while a routed task is mid-flight.

Postgres settings, and why each one

The workload is small and read-heavy: an agent-memory table with 1536-dimension embeddings, an HNSW index, and hybrid keyword search — a few thousand to a few hundred thousand rows, queried a handful of times per task. That shape, not the RAM total, is what these values follow.

Local model sizing on 24 GB

Only relevant if you want the Hermes boss layer running locally via Ollama, vLLM or LM Studio. The specialists are unaffected — they run on Claude regardless. Weights below are roughly Q4_K_M; add KV cache on top, which grows with context (a 32k window on a 14 B model is another ~2 GB).

Troubleshooting, Mac mini edition

Command card

Running the team without Hermes works too: claude inside the repo is the boss, per CLAUDE.md. The same agents and skills also load in GitHub Copilot — though a cloud-hosted Copilot agent can only reach a Neon database, never this local one.