Workers

A worker is anything that pulls jobs from your queue and runs them. Three substrates:

• Silicon — AI-powered bots (Claude, Ollama, GPT, LM Studio, or your own custom code)
• Carbon — humans working through the dashboard
• Xenon — anything else that speaks the protocol

All three pull from the same queue, get routed by the same Director, and leave the same audit trail. ModelReins doesn’t care who — or what — is doing the work.

All workers are yours. ModelReins never provides hosted compute. Every worker runs on your hardware (or infrastructure you control), uses your API keys, and is scoped to your tenant. If you have zero workers, dispatch returns 503. This is by design — your infrastructure, your keys, your rules.

Silicon workers as first-class identities

A silicon worker is not an anonymous API-key holder. It’s a registered identity in your tenant with its own token, declared capabilities, a heartbeat, and an audit trail. When an action lands in your review queue or your audit log, it’s attributed back to a specific worker_id — not a generic “bot.”

This shape matters because:

• You can revoke one bot. A single worker token stops authenticating; every other worker keeps running. The row stays for audit.
• You can assign capabilities per bot. The email-triage bot gets email.triage; it can’t suddenly start posting to your social accounts.
• You can require human approval per capability. A worker might read on auto but reply on audit and publish on approve — all three are capabilities on the same worker, each with its own friction level.
• Your audit trail names names. The “bot posted that” question always has a specific answer.

Register a silicon worker

Two paths — both produce the same result.

From the dashboard: visit app.modelreins.com/workers, fill in a name, describe what the worker does, add one or more capabilities, and click Register. You get a one-time-view URL — open it, copy the raw token, put it in MODELREINS_TOKEN on the machine running the worker.

From the API:

curl -X POST https://app.modelreins.com/api/v1/workers/register \
  -H "Authorization: Bearer $MODELREINS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-triager",
    "description": "Triages incoming support email",
    "capabilities": [
      { "name": "email.triage", "risk_tier": "auto" },
      { "name": "email.reply",  "risk_tier": "audit" }
    ]
  }'

The response includes a view_url. Open it once — the raw token is delivered on that page and erased after the view. More on one-time view delivery →

Capabilities and risk tiers

Every capability has a name (you pick it — email.triage, inventory.check, report.generate) and a risk tier that decides how much friction a human needs to apply before the action runs.

Tier	Behavior
auto	Runs freely. Fire-and-forget.
audit	Runs, but every action is logged for later review.
approve	Pauses for a human to release it from the review queue.
session	Approved once per session, not per action.

A single worker can carry different tiers for different capabilities — read a feed on auto, reply on audit, publish on approve. The Director reads the tier at dispatch time and routes the friction accordingly.

The Python SDK

The fastest path to a running silicon worker is the official Python SDK, published on PyPI. stdlib-only — no external dependencies, zero supply-chain attack surface.

pip install modelreins-worker

Then ten lines of Python:

from modelreins_worker import Worker

def handle_job(job):
    prompt = job["prompt"]
    # ... do the work ...
    return "Triage complete: priority=high, category=billing"

Worker(name="my-triager").run(handler=handle_job)

Set MODELREINS_TOKEN in the environment and run the script. The worker heartbeats every 5 seconds, polls its inbox for jobs assigned to its name, and calls handle_job for each one. Exceptions auto-fail the job with the traceback as output. Full API surface at SDK: Python.

Worker lifecycle

Whether silicon or carbon, every worker follows the same rhythm:

1. Register — worker announces itself to your tenant with its name and capabilities.
2. Heartbeat — worker pings the presence endpoint on its poll interval so the dashboard knows it’s alive.
3. Claim — worker pulls a pending job assigned to its name.
4. Process — worker does the work (calls an LLM, runs a shell script, waits for a human, whatever it does).
5. Complete — worker reports the job done with a result, or failed with an error.

Managing workers

From the dashboard at app.modelreins.com/workers: list every worker in your tenant, see capabilities and last-seen timestamps, revoke ones you no longer need.

From the API:

Action	Endpoint
Register	POST /api/v1/workers/register
List	GET /api/v1/workers
Revoke (soft)	DELETE /api/v1/workers/:worker_id

Revoke is a soft delete — the row stays in your audit trail; the token stops authenticating. You always know who was doing what, even after a bot’s been retired.

Secrets: bring your own vault

Workers that need credentials (webhook URLs, third-party API tokens, SMTP passwords) declare them as vault:// references in their requires_secrets. ModelReins resolves those references against your vault (Vaultwarden, Bitwarden, HashiCorp Vault, Keeper) at dispatch time. The credential flows straight from your vault into the worker’s runtime.

ModelReins never holds your secrets. Configure the connector once at app.modelreins.com/settings/vault, and workers stop needing credentials pasted into env vars.

The companion path (legacy)

If you’re looking for the pre-silicon-worker path — the Companion app that installs a worker on your machine with one click, registered under your API key rather than its own — that still works and is still recommended for desktop AI inference setups (Ollama, LM Studio, local brain). See The Companion. The Companion and silicon workers coexist: the Companion runs your local brain; silicon workers run your task-specific bots.