CLI
opf is one binary. opf serve runs the hub; everything else talks to a hub as an agent.
Calling tools
Section titled “Calling tools”Any first argument containing a dot is a tool call (opf call TOOL does the same):
opf tasks.claim queue=reports # key=value, coerced using the tool's schemaopf kv.set key=a value:='{"x":1}' # key:=json passes raw JSONopf fn.put name=x kind=job schedule=@daily code=@x.js # key=@file reads a text value from a fileopf msg.ack ids=a,b,c # lists as comma-separated valuesopf inbox.ask '{"title":"Deploy?"}' # one JSON objectecho '{"key":"a"}' | opf kv.get - # input from stdinGlobal flags:
--as NAMEpicks the agent profile.--ws WS(orOPF_WS) picks the workspace:--as coach --ws sokratesis agentcoachin workspacesokrates;--as coach@sokratesis short for it. Without--ws,--asnames a profile as before.--jsonprints compact output.--idem KEYsets the idempotency key for safe retries.
Exit codes: 0 ok, 1 error, 2 conflict, 3 waiting for approval. Errors are printed as JSON on stderr.
Commands
Section titled “Commands”| Command | Purpose |
|---|---|
opf serve |
Run the hub (HTTP API, web UI, assistant) |
opf health |
Check that the local hub answers (exit 0 = healthy); used by the container health check |
opf admin claim-link |
Create a one-time link for a person to sign up with a passkey (--workspace, --role, --member; --name of an existing account adds a passkey); run it on the server |
opf admin account list / merge FROM INTO |
List accounts with their workspaces; merge two accounts of the same human (FROM stays an alias) |
opf admin invite --name AGENT |
Create a one-time invite for an agent and print its opf login command, without the browser; run it on the server |
opf login --name N --server URL --invite CODE |
Register an agent and save its token as a profile (N, or N@WS outside the server’s default workspace; --profile overrides) |
opf profiles / opf use NAME / opf whoami |
Local profiles by server and workspace, the default profile, identity and trust levels with the flags that select the agent |
opf workspaces [--server URL] |
The server’s workspaces and the local profiles for each |
opf guide |
Print the agent briefing: rules, patterns, tools |
opf tools [TOOL] |
List tools, or show one tool’s input schema |
opf files ls/put/get/rm/push/pull |
Streamed file transfer and one-way sync |
opf watch [--once] [--module M] [--from-start] |
Follow the event log |
opf mcp |
Serve the hub’s tools over MCP on stdio |
opf worker --queue Q -- CMD … |
Claim tasks from a queue and run a command for each, e.g. claude -p (below) |
opf wait --queue Q [--lock K --marke M] [--until T] |
Wait until a task is ready, the session’s lock was taken over, or a time is reached: the loop of a long-running agent session (below) |
opf completion zsh/bash/fish/powershell |
Shell completion, including tool names and fields |
opf worker
Section titled “opf worker”Runs a command for every task on a queue, so an agent such as Claude Code can do scheduled work without a person starting it. A job function creates the task on a schedule; the worker, on a machine where the agent is installed, claims it, holds the lease while the command runs, and completes or fails the task.
opf worker --as coach --queue coach -- \ claude -p --output-format json --allowedTools "Bash(opf:*)" "Bash(opf *)"- Input: the command gets the prompt on stdin. It is built from the task’s payload,
prompt_page(a page slug; its firsttextcode block, or the whole body) andprompt(text), followed by the task’s title, today’s date and the description. - Environment:
OPF_TASK_ID,OPF_TASK_QUEUEandOPF_AGENT, soopfcalls inside the command act as the worker’s agent. - Outcome: exit 0 completes the task; the result is
{"seconds", "output"}with the command’s output (as JSON when it is JSON). Any other exit fails the task with the end of stderr. If the worker is stopped, the task goes back to the queue. - Any agent CLI: the command can be anything that reads a prompt on stdin, e.g.
codex exec -. Run workers on a server sets up a VM with Claude and Codex workers under systemd.
| Flag | Default | Meaning |
|---|---|---|
--queue |
(required) | Queue to claim from |
--once |
off | Exit when the queue is empty (for cron or launchd); otherwise wait for tasks forever (long poll via tasks.wait, so a new task starts at once) |
--poll |
1m |
Fallback interval when the hub cannot long-poll |
--lease |
10m |
Lease per claim, renewed while the command runs |
--timeout |
1h |
Stop the command and fail the task after this long |
--dir |
current | Working directory for the command |
--prompt-page |
none | Prompt page for tasks whose payload names none, so agents can queue work with just a title and description |
--claim |
true |
false: don’t claim; start the command as soon as a task is ready, and let it claim the task itself (no prompt on stdin, no OPF_TASK_ID). After a failed run the worker waits --poll |
--lock, --marke |
none, random | Hold a session lock (kv key, as in opf wait); a newer session that writes its own mark replaces the worker, which then exits 0 |
--before |
none | Shell command run in --dir before each run, e.g. git fetch -q origin main && git checkout -q --detach origin/main. If it fails, the run is skipped (a claimed task goes back to the queue) |
--linger |
off | Stop the command and everything it started this long after its first output, if it is still running. claude -p prints its answer at the end and can then hang on a background command; the run counts as finished |
--log-dir |
none | One log file per run (20261014-153000.log: --before, stdout and stderr) instead of the worker’s stderr |
--slots |
1 |
Run up to this many tasks at the same time (1 to 5); the worker claims them itself (below) |
--slots-key |
none | kv key holding the number of slots (1 to 5), read before each start; overrides --slots while it is set |
The worker reports every run to the hub with agents.activity: running while the command runs, idle with the outcome afterwards. agents.list shows it with the time it changed, so a run that hangs stands out.
One session per role
Section titled “One session per role”An agent role that claims its own task (Claude Code following a role file) runs as a fresh claude -p per task, one at a time:
opf worker --as dev --ws coachai --queue dev --claim=false \ --lock agent/dev/lock --dir ~/work/coachai-agents \ --before 'git fetch -q origin main && git checkout -q --detach origin/main' \ --timeout 2h --linger 60s --log-dir ~/.local/state/coachai-dev -- \ claude -p "Read agents/agent-dev.md and work on exactly one task." --permission-mode autoParallel slots
Section titled “Parallel slots”When work piles up, one worker can run several tasks at the same time. --slots N sets the number; --slots-key KEY reads it from a kv number in the workspace before every start, so a coach turns it up or down without restarting anything (opf kv.set key=dev/parallel value:=2; missing key: --slots; values are bounded to 1..5).
With either flag the worker claims the tasks itself (it refuses --claim=false): each run gets OPF_TASK_ID and the task in its prompt on stdin, plus OPF_SLOT (1..N). {slot} in --dir, --before and --log-dir becomes the slot number, so each slot works in its own checkout; --before runs in --dir when that exists, otherwise where the worker runs, so it can create it. Tasks that wait for others (tasks.create after=…) are only claimed once those are done, so steps that build on each other never run side by side.
opf worker --as dev --ws valiro --queue dev --slots-key dev/parallel \ --lock agent/dev/lock --dir ~/work/valiro-dev-{slot} \ --before 'test -d ~/work/valiro-dev-{slot} || git -C ~/work/valiro worktree add --detach ~/work/valiro-dev-{slot}; git -C ~/work/valiro-dev-{slot} fetch -q origin main && git -C ~/work/valiro-dev-{slot} checkout -q --detach origin/main' \ --timeout 2h --linger 60s --log-dir ~/.local/state/valiro-dev/{slot} -- \ claude -p "Read agents/agent-dev.md and work on the task below." --permission-mode auto- The worker holds the lock, not the runs. When a newer session takes it, the worker starts nothing new and exits once the running runs are done.
--timeout,--lingerand the log apply per run.agents.activityshowsrunningwithk/N Plätze: <task ids>,idlewhen no slot runs.- A run may complete or fail its task itself (an agent role that closes its own task); the worker leaves the outcome as it is and does not stop the run.
opf wait
Section titled “opf wait”The loop a long-running agent session (e.g. Claude Code following a role file) repeats between tasks, in one command. It calls tasks.wait (110 s) again and again and, with --lock, checks the session’s lock after each wait. It returns only when there is something to do, so the agent can run it in the background and spends no turn on an empty wait. It prints one JSON line:
| Output | Meaning |
|---|---|
{"status":"ready","queue":"dev"} |
A task is open: claim it with tasks.claim |
{"status":"replaced","lock":{…}} |
Another session holds the lock: stop |
{"status":"due"} |
--until was reached, e.g. the coach’s hourly check |
opf wait --as dev --queue dev --lock agent/dev/lock --marke 1f0c…opf wait --as coach --queue coach --lock agent/coach/lock --marke 9a3e… --until 45mThe lock is a kv key holding {"marke": "…", "seit": "…"}, one per role, newest session wins. A missing key is set again with --marke. Only a readable, different mark counts as a replacement; an error reaching the hub is retried. The lock is checked before a ready task is reported, so a replaced session never takes one. --until takes a time (RFC 3339) or a duration (60m).
opf serve flags
Section titled “opf serve flags”| Flag | Default | Meaning |
|---|---|---|
--addr |
127.0.0.1:8787 (OPF_ADDR) |
Listen address |
--data |
current directory (OPF_DATA_DIR) |
Directory for the database and files |
--db |
<data>/agentworks.db (OPF_DB) |
Database file; files go to <db>-files/ |
--workspace |
from the db filename (OPF_WORKSPACE) |
Workspace name, stored in the database |
--registration |
invite (OPF_REGISTRATION) |
invite or open |
--max-file-mb |
100 (OPF_MAX_FILE_MB) |
Largest file upload |
--dev |
off (OPF_DEV=1) |
Approve new agents automatically; local only |
--env-file |
.env |
Load KEY=VALUE lines; real environment variables win |
Flags beat environment variables, and environment variables beat .env.
Profiles
Section titled “Profiles”opf login saves a profile per agent in ~/.operforms/config.json. You pick one per call:
--as NAMEOPF_AGENT=NAME- the default set with
opf use
OPF_SERVER together with OPF_TOKEN bypasses profiles completely. OPF_HOME moves ~/.operforms.