Configuration

File

~/.macbatch/config.toml

WARNING

Despite the extension, the contents are JSON. The name is historical. Unknown keys are ignored on load, so a config written by an older version keeps working after an upgrade.

Written by macbatch setup, and updated whenever serve or control start is given overriding flags.

Fields

Field	Default	Meaning
control_url	http://127.0.0.1:8000	Control plane this machine talks to
worker_id	<hostname>-<6 hex>	Identity used in every request
token	""	Unused. Reserved for authentication that does not exist yet.
jobs	["embed"]	Job types this worker will accept
models	["nomic-embed-text"]	Advertised in heartbeats. Does not pull anything.
ollama_url	http://127.0.0.1:11434	Local runtime endpoint
max_concurrent	2	Shards processed in parallel threads
lease_limit	2	Shards leased per round trip
poll_seconds	0.5	Sleep between empty lease attempts
control_host	127.0.0.1	Bind address when this machine hosts the control plane
control_port	8000	Bind port
public_url	""	Tunnel URL, set while a tunnel is live and cleared when it exits

control_url versus public_url

Both exist, and the resolution order is deliberate:

effective_control_url() = control_url or public_url or http://127.0.0.1:8000

control_url always wins. public_url exists to be shared with other people, not to be used by this machine.

The reason is operational: a worker on the same Mac as the control plane should reach it over localhost. Preferring the tunnel URL meant a dead tunnel broke a worker that had a perfectly good local server one process away.

Paths

Path	Holds
~/.macbatch/config.toml	This file
~/.macbatch/state/serve.pid	Pid of the running worker, used by sleep
~/.macbatch/cache/tmp/	Temp files, cleared by sleep and clean
~/.macbatch/cache/tmp/shard_results/<worker_id>/	Shard results written before upload
~/.macbatch/logs/macbatch.jsonl	JSON-lines log
~/.macbatch/control-plane/batch.db	SQLite queue, when this machine is the control plane
~/.macbatch/control-plane/artifacts/	Artifact store

Source checkout versus installed

Benchmark output and sample corpora move depending on how macbatch was installed:

Installed via	benchmarks/ and data/ land in
pip install -e . in a clone	The repository
npm or a regular pip install	~/.macbatch/

Detection looks for a pyproject.toml declaring name = "macbatch" beside the package, and explicitly refuses to treat a site-packages location as a checkout. An installed CLI must never write benchmark artifacts into its own install directory.

Environment variables

Variable	Used by	Meaning
MACBATCH_PYTHON	npm postinstall	Interpreter to build the private venv with

The Python CLI itself reads no environment variables — all state is the config file plus command-line flags.

Constants that are not configurable

Constant	Value	Where
Lease duration	600s	LEASE_SECONDS in macbatch.control.db
Heartbeat staleness	60s	HEARTBEAT_STALE_SECONDS in the same module
Max attempts before failing	3	Hard-coded in the completion handler

Changing any of these means editing the source.