Python SDK on Linux

Silicon-worker install playbook for Linux servers. Covers the friction points that trip up new users: PEP 668 “externally-managed environment” on modern distros, running the worker as a service, and permissions.

1. System Python vs a venv (you almost certainly want a venv)

Recent Ubuntu (23.04+), Debian 12+, Fedora 38+, and most distros now ship Python with PEP 668 enforced. Running pip install against the system Python fails with:

error: externally-managed-environment
× This environment is externally managed

That’s not a bug — the distro is telling you not to mix pip packages into the OS Python. Use a venv:

sudo apt-get update && sudo apt-get install -y python3-venv python3-pip
python3 -m venv ~/mr-worker
source ~/mr-worker/bin/activate
pip install modelreins-worker

From here on, python and pip inside that venv are isolated. You activate the venv to interact with the worker; outside of it, your system Python is untouched.

2. Quick smoke test

Confirm the SDK imports + can reach the server before you wrap it in a service:

export MODELREINS_TOKEN=<your-worker-token>   # from /workers on your dashboard
python -c "from modelreins_worker import Worker; \
  print(Worker(name='linux-smoke').heartbeat(details='smoke'))"

You should see {'success': True, ...}. If you get a WorkerError, the token is wrong or the server can’t be reached.

3. Write your worker

Save as ~/mr-worker/worker.py:

#!/usr/bin/env python3
from modelreins_worker import Worker

def handle_job(job):
    # job is a dict with id, prompt, assigned_to, status, etc.
    prompt = job["prompt"]
    # ... do the work ...
    return "Result goes here as a string"

Worker(name="linux-worker-01").run(handler=handle_job)

Test it runs:

MODELREINS_TOKEN=<token> python ~/mr-worker/worker.py

You’ll see heartbeat messages every 5 seconds. Ctrl-C to stop.

4. Run as a systemd service

So it survives reboots + auto-restarts on failure. Create /etc/systemd/system/modelreins-worker.service:

[Unit]
Description=ModelReins silicon worker
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=modelreins
Group=modelreins
WorkingDirectory=/home/modelreins
Environment="MODELREINS_TOKEN=<your-token>"
Environment="MODELREINS_URL=https://app.modelreins.com"
ExecStart=/home/modelreins/mr-worker/bin/python /home/modelreins/mr-worker/worker.py
Restart=on-failure
RestartSec=10

# Sandbox the process — read-only filesystem except the venv + workdir
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/modelreins/mr-worker /home/modelreins/work
PrivateTmp=true
PrivateDevices=true

[Install]
WantedBy=multi-user.target

Create the user + set up the venv under their home:

sudo useradd -m -s /bin/bash modelreins
sudo -u modelreins python3 -m venv /home/modelreins/mr-worker
sudo -u modelreins /home/modelreins/mr-worker/bin/pip install modelreins-worker
# copy worker.py to /home/modelreins/worker.py (adjust the ExecStart path if needed)
sudo systemctl daemon-reload
sudo systemctl enable --now modelreins-worker
sudo systemctl status modelreins-worker

Logs: sudo journalctl -u modelreins-worker -f

5. Common potholes

”externally-managed-environment” on pip install

Use a venv (see step 1). Do NOT use --break-system-packages — that’s a footgun that pollutes system Python.

Token not loaded when started by systemd

Environment="MODELREINS_TOKEN=..." in the unit file works, but don’t commit the unit file with the token in it to git. Better: store the token in /etc/modelreins/worker.env (mode 600, owned by modelreins:modelreins) and reference with EnvironmentFile=/etc/modelreins/worker.env.

Firewall blocks outbound

The worker needs outbound HTTPS (443) to app.modelreins.com. If you’re in a locked-down environment, confirm port 443 outbound is open.

Clock skew

If the server rejects with an auth error on an otherwise-correct token and the machine hasn’t synced NTP in a while, sudo timedatectl set-ntp true and retry. SMTPS-style timestamp-bounded tokens are less common here, but save yourself the debug hour.

Multiple workers on one box

Set a distinct name= per worker. Run each as its own systemd unit (modelreins-worker-01, modelreins-worker-02). They all share the venv; just parameterize the unit.

6. Distro quick-reference

Distro	venv package	Notes
Ubuntu 22.04+	python3-venv python3-pip	PEP 668 enforced in 23.04+.
Debian 12+	python3-venv python3-pip	PEP 668 enforced.
Fedora 38+	python3 python3-pip	venv module is built-in.
Rocky/Alma 9+	python3 python3-pip	venv is built-in. python3 is 3.9 — bump to newer if needed.
Alpine 3.18+	python3 py3-pip	Musl — should work fine for stdlib-only SDK.
WSL (any Linux)	same as host distro	Works the same.

7. Upgrade path

When a new version of the SDK ships:

source ~/mr-worker/bin/activate
pip install --upgrade modelreins-worker
sudo systemctl restart modelreins-worker

Changelog lives at modelreins.com/changelog — the SDK tracks its own SemVer, separate from the ModelReins server version. See Python SDK for the full API surface.