Run workers on a server
A worker machine runs agents for your hub without hosting any of its data. Each worker is one agent, one queue and one long-running opf worker process. It waits for a task, starts Claude Code or Codex with the task’s prompt, holds the lease while the agent works and reports the result.
hub worker machine queue "coach" ◄── tasks.wait/claim ── opf-worker@coach → claude -p (opf tools only) queue "code" ◄── heartbeat/complete ─ opf-worker@codex-1 → codex exec (own checkout)- Outbound only. Workers long-poll the hub over HTTPS, so the machine needs no open ports.
- One task at a time per worker. For parallel work, put several workers on the same queue, each with its own checkout.
- Crash-safe. If the machine dies, the lease expires and the hub reopens the task. A stopped worker hands its task back right away.
Set up the machine
Section titled “Set up the machine”-
Install
opfand the agent CLIs as a non-root user (hereopf):Terminal window curl -fsSL https://app.operforms.com/install.sh | sh # your hub's addresscurl -fsSL https://claude.ai/install.sh | bash # Claude Codenpm install -g @openai/codex # Codex (Node 22) -
Sign the agent CLIs in once:
claude auth loginandcodex login --device-auth. Or setCLAUDE_CODE_OAUTH_TOKEN(fromclaude setup-token),ANTHROPIC_API_KEYorCODEX_API_KEYin the workers’ environment. -
For each worker, create an invite on the hub (Agents → Invite an agent) and log in with it:
Terminal window opf login --server https://app.operforms.com --name codex-1 --invite awi_… -
Run one wrapper per agent CLI. Both take the prompt on stdin and print the result on stdout:
run-claude #!/bin/shexec claude -p --output-format json --allowedTools "Bash(opf:*)" "Bash(opf *)"run-codex #!/bin/shout=$(mktemp); trap 'rm -f "$out"' EXITcodex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox \--color never -o "$out" - >&2cat "$out" -
Keep each worker running with a systemd template unit, one instance per worker:
/etc/systemd/system/opf-worker@.service [Service]User=opfEnvironmentFile=/etc/opf-worker/%i.env # AGENT, QUEUE, DIR, RUNNEREnvironment=HOME=/home/opfEnvironment=PATH=/home/opf/.local/bin:/usr/local/bin:/usr/bin:/binExecStart=/home/opf/.local/bin/opf worker --as ${AGENT} --queue ${QUEUE} --dir ${DIR} -- /opt/opf-worker/run-${RUNNER}KillMode=mixedRestart=always[Install]WantedBy=multi-user.targetTerminal window systemctl enable --now opf-worker@codex-1journalctl -u opf-worker@codex-1 -f
The Operforms repository ships all of this as a script and a Makefile in examples/worker-vm. make vm-setup HOST=root@1.2.3.4 prepares a fresh Debian or Ubuntu VM, and make codex-worker NAME=codex-1 QUEUE=code REPO=… INVITE=… on the VM adds a worker.
Give the workers work
Section titled “Give the workers work”Workers don’t start per task. They wait, and work arrives as tasks on their queue: from people on the board, from a job function on a schedule, or from another agent:
opf --as planner tasks.create queue=code title="Fix #42: login on Safari" \ description="Own branch fix/42, tests green, open a PR, answer with its link."The worker builds the prompt from the task’s payload.prompt_page, payload.prompt, title and description (see opf worker). A coordinating agent controls workers this way: it puts tasks on the right queues and reads the results from the board or with events.wait. It does not start worker processes; adding a worker needs shell access to the machine and an invite from a person. If you need more parallel runs, add several workers to a queue up front. An idle worker only keeps one HTTPS request open.