Skip to content
ModelReins ModelReins Docs

Add a Worker

A worker is anything that can pick up a job from the ModelReins queue and complete it. ModelReins supports multiple worker types — pick the one that matches what you have.

Option 1: Screensaver companion (easiest)

Section titled “Option 1: Screensaver companion (easiest)”

Best for: your laptop, your daily driver, anyone who hates configuration.

See Install the Screensaver.

Option 2: Companion installer on a server or spare machine

Section titled “Option 2: Companion installer on a server or spare machine”

Best for: a Proxmox container, a Raspberry Pi, an old machine in the closet — anything you want to turn into a dedicated worker.

  1. Download the Companion installer:

  2. Run the installer and follow the prompts. It walks you through:

    • ModelReins URL (default: https://app.modelreins.com)
    • API token (from your dashboard → Settings → API Keys)
    • Worker name (defaults to hostname)
    • Provider (claude, openai, ollama, 1minai, lmstudio)
    • Tags (code, review, draft, etc.)

  3. The Companion registers itself, starts picking up jobs, and appears in your fleet within seconds.

On Linux, the Companion installs a systemd unit so it survives reboots. On Windows it runs as a startup app.

Option 3: MCP channel — turn an existing Claude Code session into a worker

Section titled “Option 3: MCP channel — turn an existing Claude Code session into a worker”

Best for: you’re already running Claude Code in another project and want to donate its idle cycles to the fleet.

Terminal window
# Install the channel
npm install -g @mediagato/modelreins-channel@latest


# In any Claude Code session, run the bootstrap tool
modelreins_recruit

The MCP tool generates a CLI command + VSCode config tailored to your session. Paste it back, restart the session, and you’re a worker.

This is how you get dual-Claude topology — you can have one Claude Code instance writing this very tour while another instance off-screen takes jobs from the saddle. They share nothing, they don’t compete for context, they just both pull from the same queue.

Provider-specific worker setup

Section titled “Provider-specific worker setup”

The worker SDK ships with adapters for:

ProviderAuthNotes
claudeCLAUDE_CODE_OAUTH_TOKEN (subscription) or ANTHROPIC_API_KEYshells out to the claude CLI
openaiOPENAI_API_KEYuses the OpenAI Python SDK
ollamanonelocal at 127.0.0.1:11434
1minaiONEMINAI_API_KEYheader is API-KEY, not Bearer
lmstudiononelocal at 127.0.0.1:1234

Each adapter knows its provider’s quirks (rate-limit headers, streaming format, error classification) so the router can make smart decisions.

How the router picks workers

Section titled “How the router picks workers”

When you dispatch a job, the router scores every eligible worker on:

  • Tag overlap (50%) — does the worker’s tags match the job’s tags?
  • Track record (30%) — 30-day success rate with a Bayesian prior for new workers
  • Load (20%) — how many jobs is this worker already running?
  • Penalties — recently failing workers, rate-limited workers, sub-workers that need to load

The highest-scored worker wins. To debug a routing decision, use /dispatch/explain:

Terminal window
curl -H "Authorization: Bearer mr-..." \
  "https://app.modelreins.com/dispatch/explain?job_tags=code,review&urgency=normal"

You get the score breakdown for every candidate so you can see exactly why the router picked what it picked.

Tagging workers correctly

Section titled “Tagging workers correctly”

Tags are how the router knows what a worker is good at. Set them in the worker config:

Terminal window
# Worker SDK
MODELREINS_WORKER_TAGS=code,architecture,complex,review


# Or via the API
curl -X PUT https://app.modelreins.com/presence \
  -H "Authorization: Bearer mr-..." \
  -d '{"instance":"my-worker","tags":"code,draft,economy"}'

Common tags by use case:

  • General coding: code, draft
  • Code review: code, review
  • Architecture: architecture, complex, review
  • Cheap/quick tasks: triage, draft, economy
  • Local/private: local, code
  • Specialty: math, reasoning, logic

Tags are normalized server-side (lowercased, trimmed, deduped) so don’t worry about case or whitespace.

Verifying the worker is actually working

Section titled “Verifying the worker is actually working”

In the saddle, your new worker should appear in the Fleet section within 30 seconds. Hit dispatch with effort: trivial to send the smallest possible test job. If it lands on your new worker and comes back, you’re done.

If the worker shows up but doesn’t get jobs, check /dispatch/explain to see its score — usually it’s a tag mismatch.