Your first local-first agent on a Mac mini in 90 minutes

This guide gets you from “blank Mac mini” to “a local agent that replies to a Telegram message and runs a tool” in about 90 minutes. Before you install anything, you have two decisions to make:

1. Which agent framework will own the loop (chat, tools, memory, scheduling)?
2. Which local model will the agent talk to?

The right answers depend on what you’re trying to do. Pick deliberately, then install.

Where the picks come from: the agent table below is sourced from each project’s official docs page (linked in the rightmost column, verified 2026-07-22). The model table below is sourced from the Ollama library page, verified 2026-07-22 — gemma4 last updated 3 weeks ago; qwen3.5 2 months ago; qwen3-coder 10 months ago; qwen2.5 1 year ago (superseded). The Claude Code + Ollama recipe is sourced from Ollama’s official Claude Code integration blog post, published 2026-01-16.

Pick your agent

Default pick for this guide: if you do nothing else, pick Hermes Agent — it has the Telegram gateway, the skills system, and the multi-provider plumbing that this walkthrough depends on. If you’re a Claude Max subscriber and want the IDE-coupled path, pick Claude Code and skip Steps 2-6 (it owns the chat loop, you don’t need Telegram). Steps 2-3 still apply if you want Claude Code talking to a local Ollama model.

Companion guide needed: “Pick a coding-agent CLI: Hermes Agent vs Claude Code vs Codex vs OpenCode.” A full Setup / How-to-Decide guide with the trade-off matrix and the per-agent tool surface. The 4-row table above is the seed.

Pick your model

The model you pick determines the hardware budget and the latency you’ll live with. All of these run on Ollama. See the Ollama library for the full catalog and “Updated X days ago” timestamps.

Default picks for this guide:

• Hermes path: gemma4:12b (12B, 7.6 GB on disk, fits a 16 GB Mac mini with headroom). If your mini is 24 GB+ and you’re doing real coding, swap to qwen3-coder:30b.
• Claude Code path: gpt-oss:20b (per Ollama’s own recommendation).

Companion guide needed: “Pick a local LLM on Ollama in 2026: gemma4 vs gpt-oss vs qwen3-coder vs qwen3.5 vs deepseek-r1.” Per-model benchmarks and the swap path when one regresses. The model table above is the seed.

What you need (hardware + accounts)

• Mac mini (M-series, 16 GB+ recommended). 24 GB+ for qwen3-coder:30b. 8 GB minimum (with gemma4:e2b) is possible but not recommended.
• macOS current.
• Terminal comfortable.
• A Telegram bot token (free, 5 minutes via @BotFather) — skip if you picked Claude Code and don’t want messaging.
• Your Telegram chat id (free, message @userinfobot).

That’s it. No cloud account, no paid API if your agent supports Ollama.

Step 1 — Install your agent (5–10 min)

The install command depends on what you picked in the agent table above.

A. Hermes Agent — recommended

Easiest path (macOS or Windows): download and run the Hermes Desktop installer. It bundles the CLI, the desktop app, all dependencies (Python, Node.js, ripgrep, ffmpeg), and the per-user install. The official installation docs lead with this path: “With the Hermes Desktop installer on macOS or Windows (recommended).”

CLI-only path (Linux, macOS, WSL2, Termux):

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The installer handles all dependencies (Python 3.11, Node.js v22, ripgrep, ffmpeg) and sets up the hermes binary at ~/.local/bin/hermes (per-user) or /usr/local/bin/hermes (root-mode). Per the docs, the only prerequisite on non-Windows is Git; the installer fetches everything else.

B. Claude Code — alternative

curl -fsSL https://claude.ai/install.sh | bash
# or: brew install --cask claude-code

After install, log in when prompted.

C. Codex CLI / OpenCode

See the Codex README and OpenCode docs for current install commands — both update faster than this guide.

Smoke-test before doing anything else

# Hermes
hermes --version
hermes chat "say hi"

# Claude Code
claude --version
claude   # then log in when prompted

If the smoke test fails, stop here and fix the install before moving on. Everything downstream assumes a working agent CLI.

Step 2 — Install Ollama (5 min)

🤖 Ask your agent (Hermes path): open a chat with Hermes and say:

install ollama via brew, start the daemon as a brew service, and confirm `ollama --version` returns a version ≥ 0.14.0

Hermes has the shell tool and the Homebrew knowledge to do this itself. Use it.

Ollama is the local-LLM runtime; your agent will call it over HTTP at http://localhost:11434. Requires Ollama v0.14.0 or later if you’re using Claude Code’s Anthropic-compatibility path (released 2026-01-16).

brew install ollama
brew services start ollama

Verify:

ollama --version
brew services list | grep ollama    # shows "started"

Step 3 — Pull the model you picked (10–30 min)

🤖 Ask your agent (Hermes path):

pull the gemma4:12b model via ollama, then run `curl -s http://localhost:11434/api/generate -d '{"model":"gemma4:12b","prompt":"hi","stream":false}'` and show me the response

Hermes will run the ollama pull, then verify the model answers. If you picked a different model from the table, swap the name in the prompt.

This is the slow step — model weights download once.

# Hermes default pick
ollama pull gemma4:12b

# Claude Code default pick (per Ollama's recommendation)
ollama pull gpt-oss:20b

# Or your pick
# ollama pull qwen3-coder:30b
# ollama pull qwen3.5:9b
# ollama pull deepseek-r1:8b
# ollama pull gemma4:e2b         # 7.2 GB on disk; lowest-RAM fallback for an 8 GB mini

Verify with a live call:

curl -s http://localhost:11434/api/generate \
  -d '{"model":"gemma4:12b","prompt":"hi","stream":false}' | jq -r .response

You should see "hi" back. Free, local, no API bill. See the Ollama REST API docs for the full request shape.

⚠️ Pin the model version. ollama pull gemma4:12b tracks the :12b tag, which Ollama may silently update when a new quant ships. Pin to an exact digest if you need reproducibility: ollama pull gemma4:12b@sha256:<digest>. See ollama show gemma4:12b for the current digest.

Step 4 — Wire your agent to Ollama

🤖 Ask your agent (Hermes path): Hermes usually auto-detects a running Ollama daemon on localhost:11434. To confirm, say:

list your available model providers and confirm Ollama is reachable at http://localhost:11434

If Hermes shows Ollama in the list, skip the env-var steps below — you’re done.

This step is different per agent.

A. Hermes Agent (recommended)

Hermes has multi-provider support built in. Configure Ollama as a provider via the Nous Portal or by editing ~/.hermes/.env:

# Example ~/.hermes/.env additions
OLLAMA_BASE_URL=http://localhost:11434
HERMES_DEFAULT_MODEL=gemma4:12b

Then verify Hermes can route a call through Ollama:

hermes chat --model gemma4:12b "say hi"

You should see the same "hi" response — but now coming through the agent, not through curl.

B. Claude Code + Ollama

Two paths. Ollama now ships a first-party launch command for Claude Code (and other agents). It is the current recommended path; the manual env-var recipe below still works but is the older approach.

Path 1 (recommended): ollama launch claude. Ollama wires Claude Code against the running Ollama daemon for you, pre-installing the Claude Code binary if missing and selecting the model from the Ollama library:

# One-shot: install Claude Code (if needed) and run it against Ollama
ollama launch claude --model gemma4:12b

The ollama launch command also supports hermes, codex, codex-app, and opencode — see the Ollama applications docs (the per-model library pages now show ollama launch <agent> --model <name> snippets).

Path 2 (manual, power-user): Anthropic-compatible env vars. Set two environment variables, then run claude with the model flag:

export ANTHROPIC_AUTH_TOKEN=***
export ANTHROPIC_BASE_URL=http://localhost:11434

claude --model gpt-oss:20b

Notes from the Ollama blog (2026-01-16):

• ANTHROPIC_AUTH_TOKEN is required by Claude Code’s startup but is ignored by Ollama — set it to any non-empty string (ollama works).
• Ollama recommends gpt-oss:20b and qwen3-coder for Claude Code use cases when you go the manual route.
• Run a model with at least 32K tokens context length for Claude Code workflows.
• Ollama’s cloud models (glm-4.7:cloud, etc.) work too — claude --model glm-4.7:cloud.
• Supported features: messages, streaming, system prompts, tool calling, extended thinking, vision (image input).

Pick one. If ollama launch claude works on your machine, use it. Fall back to the manual env-var recipe only if ollama launch is unavailable (older Ollama versions, restricted corporate proxies, custom base-URL paths).

C. Codex CLI / OpenCode

Both have Ollama support documented in their respective config files. Codex and OpenCode both use provider blocks — typically a JSON/YAML config that names Ollama as a base URL. See the Codex docs and OpenCode docs for the exact syntax.

Step 5 — Wire Telegram — Hermes Agent path only

Skip this step if you picked Claude Code.

🤖 Ask your agent (Hermes path):

set up the Telegram messaging gateway

Hermes will run hermes setup --portal itself if you ask it to. The portal flow handles the BotFather token + chat id wiring in one OAuth.

Manual path (if you’d rather do it yourself): the Hermes Messaging Gateway docs walk through the same flow with the BotFather token + chat id. Two commands cover it:

hermes gateway setup telegram    # paste your BotFather token + chat id when prompted
hermes gateway start            # runs the gateway as a managed process

Verify with /start from your Telegram chat. Hermes replies with the same “Local agent online” prompt.

# bot.py
import os, json, urllib.request
from telegram import Update
from telegram.ext import ApplicationBuilder, CommandHandler, MessageHandler, ContextTypes, filters

TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]

async def start(update: Update, ctx: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("Local agent online. Send me a task.")

async def reply(update: Update, ctx: ContextTypes.DEFAULT_TYPE):
    r = urllib.request.urlopen(urllib.request.Request(
        "http://localhost:11434/api/generate",
        data=json.dumps({"model":"gemma4:12b","prompt":update.message.text,"stream":False}).encode(),
        headers={"Content-Type": "application/json"},
    ), timeout=60)
    await update.message.reply_text(json.loads(r.read())["response"])

app = ApplicationBuilder().token(TOKEN).build()
app.add_handler(CommandHandler("start", start))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, reply))
app.run_polling()

Step 6 — Add a tool (10 min)

🤖 Ask your agent (Hermes path): the point of this step is to give Hermes the read_file tool so it can read files inside ~/local-agent/workspace/. Hermes can scaffold this tool itself if you say:

add a read_file tool that only reads files inside ~/local-agent/workspace/ and rejects any path that escapes it

Hermes will write the sandbox check shown below and register the tool. Verify by sending it a message that asks to read ~/local-agent/workspace/test.txt — it should succeed; asking for ~/Documents/private.md should be refused.

Tools are what make an agent useful. Start with one: “read a file from disk.”

TOOLS = {
    "read_file": {
        "description": "Read a text file from disk and return its contents.",
        "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
}

def run_tool(name, args):
    if name == "read_file":
        with open(args["path"]) as f:
            return f.read()[:8000]
    raise ValueError(f"unknown tool: {name}")

Ollama’s /api/chat supports tool calling with the same JSON-Schema shape shown above; see the Ollama REST API docs for the exact request body. The agent decides when to call the tool; you execute it; you put the result back in the next prompt.

Security note: the read_file tool above reads any path the agent asks for. Before you deploy to anyone but yourself, restrict it to a WORKSPACE_ROOT directory and reject any path that escapes it via .. or symlinks:

import os
WORKSPACE_ROOT = os.path.expanduser("~/local-agent/workspace")
def run_tool(name, args):
    if name == "read_file":
        target = os.path.realpath(os.path.join(WORKSPACE_ROOT, args["path"]))
        if not target.startswith(WORKSPACE_ROOT + os.sep):
            raise ValueError(f"path escapes workspace: {args['path']}")
        with open(target) as f:
            return f.read()[:8000]
    raise ValueError(f"unknown tool: {name}")

Step 7 — Add memory (10 min)

🤖 Ask your agent (Hermes path): Hermes has a built-in memory system. To turn it on and seed it with the basics, say:

enable the memory system, then write a MEMORY.md and USER.md under ~/.hermes/ with the facts and preferences we'd want you to remember between sessions

Hermes will create the files and start using them. Skip the rest of this step.

Two files in ~/.local-agent/:

MEMORY.md        # project facts
USER.md          # operator prefs

Read them once at the start of every message and inject them into the system prompt. That is your entire project memory tier. No vector DB needed. If you picked Hermes Agent, the built-in memory system already handles this — see the Memory System docs.

Step 8 — Add a cron job (10 min)

🤖 Ask your agent (Hermes path): if your agent supports scheduled jobs, ask it to register one. For Hermes:

create a daily 6:30am cron job that calls the gemma4:12b model with a morning-brief prompt and posts the result to my Telegram chat

Hermes has cron-management commands and will register the plist + start the job. Skip the rest of this step.

The point of running an agent on a Mac mini is that it can wake up without you. Use launchd, not cron (cron on macOS is deprecated). Apple’s launchd scheduled jobs guide and the launchd.info reference define the plist format and StartCalendarInterval key.

<!-- ~/Library/LaunchAgents/com.localagent.daily.plist -->
<?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.localagent.daily</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/python3</string>
    <string>/Users/you/local-agent/daily.py</string>
  </array>
  <key>StartCalendarInterval</key>
  <dict>
    <key>Hour</key><integer>6</integer>
    <key>Minute</key><integer>30</integer>
  </dict>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.localagent.daily.plist

daily.py runs at 6:30 AM, calls the local model with a prompt, posts the result to Telegram.

Per-platform service mechanism — this section applies the ABS rule that “platform-dependent” is not a useful answer:

Step 9 — Cost ledger (10 min)

🤖 Ask your agent (Hermes path): Hermes already logs every model call. To get a per-day breakdown, say:

show me the cost summary for the last 7 days by model, broken down by run

For local Ollama models the cost is electricity, not dollars — about 5W per Mac mini running an inference. Hermes will compute the watt-minutes for you.

Even though local tokens are free, log every call. Time is the real cost.

import time, json, pathlib
LEDGER = pathlib.Path("~/.local-agent/runs.jsonl").expanduser()

def log(**kw):
    kw["ts"] = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
    with LEDGER.open("a") as f:
        f.write(json.dumps(kw) + "\n")

At the end of each call: log(model="gemma4:12b", tokens_in=N, tokens_out=M, latency_ms=T). Once a week, run awk -F'"latency_ms":' '{s+=$2} END{print s/1000 "s"}' ~/.local-agent/runs.jsonl and know exactly how much time the agent spent thinking.

What you will have at the end

• An agent picked from the table above, with its CLI on PATH and a smoke-tested chat turn.
• A local LLM picked from the model table, running at http://localhost:11434 via Ollama.
• A tool wired (read_file), with workspace-escape protection.
• Project memory in two files (or your agent’s built-in memory system).
• One daily launchd job (Apple’s docs).
• A JSONL run log.

Cost to run: $0 in API, ~5W of electricity.

How to know it is working

• hermes --version (or claude --version) prints a version.
• hermes chat "say hi" returns a text reply.
• curl http://localhost:11434/api/generate -d '{"model":"gemma4:12b","prompt":"hi","stream":false}' returns text.
• Telegram /start returns “Local agent online.” (Hermes path only.)
• launchctl list | grep localagent shows the daily plist loaded.
• wc -l ~/.local-agent/runs.jsonl grows after every agent run.

When to stop here and when to graduate

Stop here if:

• Your daily run fits in <1 GB of context.
• Latency under 5 s is fine.
• You are not running a vision model yet.

Graduate if:

• You want a vision model (try gemma4:12b or llava in Ollama).
• You want a bigger reasoning model (32B+ on a 48 GB mini).
• You need always-on public endpoints (move to VPS + Docker).

Common failures and fixes

Updates and breaking changes

Re-run the smoke test after any of these:

• macOS major version upgrade — which python3 may change.
• Ollama major version upgrade (currently 0.32.x; Anthropic-compat added in 0.14.0) — /api/generate and /api/chat request shapes have changed in the past; re-read the REST API docs.
• python-telegram-bot major version upgrade — handler signatures changed between v13 and v20.
• The agent framework you picked ships a major release — re-read its install docs.

Where to get unstuck

• Hermes Agent: the installation guide, Messaging Gateway, Memory System, and Nous Portal.
• Claude Code: the Claude Code docs and installation troubleshooting.
• Claude Code + Ollama: Ollama’s Claude Code integration blog (2026-01-16) and the Claude Code Anthropic compatibility docs.
• Codex CLI: the repo README and issues.
• OpenCode: the docs site.
• Ollama: the REST API docs and library; for model-specific quirks, search the Ollama GitHub issues.
• Apple launchd: the archived developer docs and launchd.info.
• python-telegram-bot: the official docs and GitHub issues.

Companion guides this guide relies on (not yet written)

A reviewer called out the gaps this guide can’t fully close in 9 steps. These companion guides are needed:

1. Pick a coding-agent CLI: Hermes Agent vs Claude Code vs Codex vs OpenCode. A full Setup / How-to-Decide guide with the trade-off matrix, the provider-vs-subscription question, and the per-agent tool surface. The 4-row table at the top of this guide is the seed for that one.
2. Pick a local LLM on Ollama in 2026: gemma4 vs gpt-oss vs qwen3-coder vs qwen3.5 vs deepseek-r1. A Concepts/Comparison guide with per-model benchmarks, the swap path when one regresses, and the VRAM/RAM budget per size. The model table here is the seed.

Sources

• Ollama library — used for: the current model catalog, tag conventions, update recency. Verified 2026-07-22.
• Ollama — macOS download — used for: official install path. Verified 2026-07-22.
• Ollama — REST API docs — used for: /api/generate and /api/chat endpoints and tool-calling request shapes. Verified 2026-07-22.
• Ollama — Claude Code integration blog — used for: the first-party Claude Code + Ollama recipe (ANTHROPIC_AUTH_TOKEN=*** + ANTHROPIC_BASE_URL=http://localhost:11434 + claude --model gpt-oss:20b). Published 2026-01-16; v2 of this guide missed this and was wrong about Claude Code + Ollama. Verified 2026-07-22.
• Ollama — Claude Code Anthropic compatibility — used for: the env-var names, the recommended model list, and the supported features (messages, streaming, tools, extended thinking, vision). Verified 2026-07-22.
• Ollama GitHub issues — used for: per-model failure modes, known regressions, and the v0.32.x model-loading regression class. Verified 2026-07-22.
• Hermes Agent — Installation — used for: the desktop installer (recommended on macOS/Windows), the curl-piped CLI installer, and the per-platform support matrix. Verified 2026-07-22.
• Hermes Agent — homepage (desktop installer) — used for: the desktop installer download link. Verified 2026-07-22 (link was transient 502 at fetch time; the install docs page references it as the canonical path).
• Hermes Agent — Messaging Gateway — used for: the Telegram wiring path. Verified 2026-07-22.
• Hermes Agent — Memory System — used for: the built-in memory system (replaces the manual MEMORY.md step for Hermes users). Verified 2026-07-22.
• Claude Code — Overview — used for: the install command and the multi-surface architecture. Verified 2026-07-22.
• Codex CLI — GitHub — used for: install path, language stats, activity. Verified 2026-07-22.
• OpenCode — docs — used for: install script and surfaces. Verified 2026-07-22 via web search.
• Apple — launchd scheduled jobs — used for: plist format, StartCalendarInterval, launchctl lifecycle. Verified 2026-07-22.
• launchd.info — used for: independent, well-maintained plist key reference. Verified 2026-07-22.
• python-telegram-bot — official docs — used for: ApplicationBuilder, handler registration, polling. Verified 2026-07-22.

Last verified: 2026-07-22. Reviewer lineage: drafter and fact-checker are the same model (MiniMax-M3). The model-selection table was checked against the current Ollama library on 2026-07-22; the agent-selection table was checked against each project’s official docs on the same date; the Claude Code + Ollama recipe was checked against Ollama’s official blog post and integration docs on the same date. v4 — 2026-07-22. Subagent reviewer caught a blocking correctness bug in v3: gemma4:9b and gemma4:4b tags do not exist in Ollama. v4 swaps the default to gemma4:12b, updates the RAM column to actual on-disk sizes, updates the low-RAM fallback to gemma4:e2b, and adds Ollama’s new first-party ollama launch claude --model <name> path. The manual ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL recipe is preserved as the power-user fallback.

v5 — 2026-07-22. (1) Tables: table-layout: fixed so % column widths work; agent-name 14%, Best for 32%. (2) Steps 2-9 lead with an “Ask your agent” callout — for each step, the running Hermes Agent does the work; manual commands below as the do-it-yourself path. (3) Step 5: hermes setup --portal is primary; python-telegram-bot snippet demoted to a footnote.