Install

macOS only. macbatch shells out to Homebrew and Ollama, and assumes Apple Silicon for anything performance-related.

Requirements

Requirement	Why
macOS	The npm package declares "os": ["darwin"]
Python ≥ 3.11	The CLI is a Python package; the npm wrapper builds a venv around it
Node ≥ 18	Only for the npm install path
Homebrew	macbatch setup uses it to install Ollama
~2 GB free disk	Checked during setup, before pulling a model

As a worker (recommended)

npm i -g macbatch

The postinstall step finds a Python ≥ 3.11, creates a private virtualenv inside the package, and pip-installs the vendored Python source into it. The macbatch binary on your PATH is a small Node shim pointing at that venv.

To force a specific interpreter:

MACBATCH_PYTHON=/opt/homebrew/bin/python3.12 npm i -g macbatch

Then bootstrap the machine:

macbatch setup --control-url https://your-control-plane

setup installs Ollama if missing, starts the service, pulls nomic-embed-text, runs an embedding smoke test, writes ~/.macbatch/config.toml, and pings the control plane. It is designed so a non-technical friend never has to read a second page of instructions.

TIP

If the control plane is not up yet, setup warns but still succeeds. You can run macbatch serve --control-url <url> later without redoing setup.

From source (development)

git clone https://github.com/kmr-rohit/macbatch
cd macbatch
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

A source checkout behaves differently in one respect: benchmark artifacts and sample corpora are written into the repo (benchmarks/, data/) instead of ~/.macbatch/. That detection is deliberate — an npm-installed CLI must never write into site-packages.

Optional: cloudflared

Needed only if you want to expose a control plane running on your own machine to workers on other networks.

brew install cloudflared

Verify

macbatch version
macbatch doctor

doctor checks Ollama, Homebrew, cloudflared, your config file, control-plane reachability, and the Ollama API. Anything marked FAIL will break serve.

Uninstall

npm uninstall -g macbatch
rm -rf ~/.macbatch          # config, logs, local caches, control-plane DB
ollama rm nomic-embed-text  # model weights are not macbatch's to delete