6 · Pull-worker

A remote agent registers a queue; requests to that queue name route to it.

What it is

Instead of routsi hosting an agent's credentials, a worker process running anywhere (behind NAT, on a laptop, no inbound port needed) registers a named queue via POST /v1/workers/register, then long-polls GET /v1/workers/{name}/jobs?wait= for questions and answers with POST /v1/workers/{name}/jobs/{id}. The queue name becomes a normal routable model.

Why

Use this when the agent that should answer can't or shouldn't run on the proxy's machine — it needs credentials, tools, or a login session that only exist on a specific developer machine or CI runner. The worker is outbound-only, so nothing needs to be exposed to reach it, and it shows up in the catalog (/v1/models, /v1/workers, the dashboard) like any other model.

Configure

models.yaml (optional — a worker can also register at runtime)

workers:
  auth: {}          # reserved — no worker auth in v1
  # freshness: 30s  # worker considered "present" if it polled within this
  # max_wait: 5m    # cap on how long a request blocks for a worker

models:
  - name: my-agent
    type: queue

on the worker machine

routsi worker run --proxy https://your-proxy:8080 --queue my-agent \
  --agent 'codex exec -'

from any client

curl localhost:8080/v1/chat/completions \
  -d '{"model":"my-agent","messages":[{"role":"user","content":"hi"}]}'
# → routed to the registered worker; 503 fast if none is polling

Full config reference: Pull-workers.

How to adapt

To add another worker queue, declare a type: queue model entry (or skip the config entirely — a worker registering with a new queue name adds it dynamically) and run routsi worker run --queue <name> --agent '<your command>' pointed at your own agent — any command that reads the question on stdin and writes an answer to stdout works. Constraints to know: one worker per queue, delivery is at-most-once, requests are non-streaming, and there's no worker auth yet (v1 reserves the workers.auth key for later). routsi install --skills packages this as an agent skill for Claude Code / Codex if you want an agent to register itself.

Next: Streaming with heartbeat →