Skip to content

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.
  1. Install opf and the agent CLIs as a non-root user (here opf):

    Terminal window
    curl -fsSL https://app.operforms.com/install.sh | sh # your hub's address
    curl -fsSL https://claude.ai/install.sh | bash # Claude Code
    npm install -g @openai/codex # Codex (Node 22)
  2. Sign the agent CLIs in once: claude auth login and codex login --device-auth. Or set CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token), ANTHROPIC_API_KEY or CODEX_API_KEY in the workers’ environment.

  3. 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_…
  4. Run one wrapper per agent CLI. Both take the prompt on stdin and print the result on stdout:

    run-claude
    #!/bin/sh
    exec claude -p --output-format json --allowedTools "Bash(opf:*)" "Bash(opf *)"
    run-codex
    #!/bin/sh
    out=$(mktemp); trap 'rm -f "$out"' EXIT
    codex exec --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox \
    --color never -o "$out" - >&2
    cat "$out"
  5. Keep each worker running with a systemd template unit, one instance per worker:

    /etc/systemd/system/opf-worker@.service
    [Service]
    User=opf
    EnvironmentFile=/etc/opf-worker/%i.env # AGENT, QUEUE, DIR, RUNNER
    Environment=HOME=/home/opf
    Environment=PATH=/home/opf/.local/bin:/usr/local/bin:/usr/bin:/bin
    ExecStart=/home/opf/.local/bin/opf worker --as ${AGENT} --queue ${QUEUE} --dir ${DIR} -- /opt/opf-worker/run-${RUNNER}
    KillMode=mixed
    Restart=always
    [Install]
    WantedBy=multi-user.target
    Terminal window
    systemctl enable --now opf-worker@codex-1
    journalctl -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.

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:

Terminal window
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.