Joining as a worker

What running macbatch serve on your machine actually does, and what it does not.

The loop

Each cycle, the worker:

1. Posts a heartbeat with its hostname, configured jobs, models, and concurrency
2. Leases up to lease_limit shards
3. Runs them — in parallel if max_concurrent > 1
4. Writes each result to local disk before uploading
5. Bulk-posts every completion in a single complete_batch call

If no shards are available it sleeps poll_seconds (default 0.5s) and tries again.

Tuning

macbatch serve --lease-limit 4 --max-concurrent 4

Setting	Default	Effect
lease_limit	2	Shards pulled per round trip. Higher means fewer requests, but more work stranded if you quit.
max_concurrent	2	Shards processed in parallel threads. Bounded by what Ollama and your memory can sustain.
poll_seconds	0.5	Idle sleep between empty leases.

Raising max_concurrent past what Ollama can serve concurrently does not help — requests just queue inside Ollama instead of inside macbatch.

What a worker will run

Only an allowlist of job types: embed, ocr, classify, generate. Each maps to a fixed call against your local Ollama instance. There is no mechanism for a control plane to send code to a worker, and adding one would defeat the trust model.

Restrict a machine to specific work:

macbatch setup --jobs embed --control-url <url>

The worker sends its jobs list with every lease request and the control plane filters tasks accordingly.

Resource use

• Model weights live in Ollama's store, not macbatch's. macbatch sleep and macbatch clean never delete them; use ollama rm <model> for that.
• Shard results are written to ~/.macbatch/cache/tmp/shard_results/<worker_id>/ before upload, so a dropped connection does not throw away completed compute. sleep and clean clear this directory.
• Logs append to ~/.macbatch/logs/macbatch.jsonl as JSON lines.

Going offline

macbatch sleep

Stops the process, clears the temp cache, keeps model weights, and posts an offline heartbeat so the control plane stops counting you as alive. Any shard you held is reclaimed after its lease expires and is re-run elsewhere — quitting mid-job is safe and costs at most one attempt per in-flight shard.

Trust

Be aware of what you are joining:

• The control plane has no authentication in the current release. Any endpoint is open to anyone who has the URL.
• Your worker sends its hostname in every heartbeat.
• Task payloads arrive as plain JSON over HTTPS and are processed locally; nothing is uploaded anywhere except back to the control plane you configured.

Only point serve at a control plane run by someone you trust.