openworker/docs/headless.md

Running OpenWorker with nobody at the keyboard

OpenWorker has two headless modes. They answer different questions.

Command	What it does	Who drives it
openworker up (after openworker join)	Keeps this computer serving as a machine the desktop app controls, forever	The desktop app: tasks and chat arrive over its channel
openworker run	Runs one task to the end and exits, leaving a record behind	You at a terminal, a script, a CI job, an evaluation harness

This page is about openworker run and the two switches that decide what happens when the agent would normally stop and ask.

Two switches: approving and answering

Approving is a yes/no on a tool call the agent has already decided to make. It is answered by a person, by the reviewer model, or by the permission mode.

Answering is the agent asking for something it does not have: a question, a folder, a tool install. The answer is content, not permission. It is answered by a person, parked in the Inbox, or supplied by the engine. That is the attendance setting.

Mode (approving)

Mode	Routine tool calls	The safety checks (run a downloaded file, write outside the workspace, edit git hooks / CI / settings files, grant authority that outlives the session)
ask	asks	asks
auto-approve	the reviewer decides; anything it is unsure about asks	asks
bypass-approvals	runs	asks
dangerously-bypass-approvals	runs	runs, each one recorded as "cleared by mode"

bypass-approvals is for someone who wants no reviewer and few prompts but keeps the basic checks. dangerously-bypass-approvals grants every approval and switches the checks off. Use it only on a disposable machine or container. It is never offered in the desktop app; the server accepts it only when started with --allow-dangerous-mode, and openworker run prints a warning line when it is on.

Attendance (answering)

Attendance	Questions, folder requests, pinned tool installs	An approval card only a person could clear
attended	appear on screen	appears on screen
inbox	parked in the Inbox until someone returns	parked in the Inbox
auto	answered by the engine, by fixed rule, and recorded	refused, unless the mode clears it

In auto:

• a question gets: "No one is available. Choose the least destructive option that still satisfies the task as written."
• a folder request is declined with guidance: work inside the workspace (or, in the dangerous mode, use the shell for paths outside it), and stop and say what is missing if the task cannot continue without the user;
• a pinned catalog tool (any tool in coworker/toolchain.py's catalog) is installed by the verified installer, same version and checksum as the desktop card would use;
• an approval card that would have needed a person is refused, never parked. Nothing hangs.

The desktop app offers auto as the third position of the Unattended toggle ("Answer for me while I'm away"); there it can only combine with modes that keep the checks, so the worst case is a refused card.

openworker run

cd ~/src/project
openworker run --prompt "Fix the failing test in tests/test_parser.py"

The task comes from --prompt, from --prompt-file, or from standard input when it is piped in. The coworker's answer is printed on standard output; progress, prompts and the closing summary line go to standard error.

What a run reads from this computer

A run uses this computer's OpenWorker settings: the default model, the stored provider keys, the connectors you have connected, the sandbox and its allowed sites. It reads them and changes none of them. The one thing it may write is a renewed sign-in, as the app does when a sign-in expires.

A connector's actions go through the approval mode like any other tool call.

Each run is its own process. Two runs started from two terminals do not share anything but those settings, and each is saved as its own session.

The app and any number of runs can work at the same time. When a sign-in needs renewing, one of them renews it and the others use the result.

Approvals and questions

These are separate, and each has its own switch.

Approvals follow --approval-mode (the table above). The default is ask.

	An approval card
At a terminal	asked in the terminal: yes once, yes for this session, or no
No terminal (a pipe, a CI job)	refused and recorded; nothing hangs

With no terminal, mode ask refuses every approval, and the run says so when it starts. For a run with nobody present, use --approval-mode auto-approve (the reviewer decides) or --approval-mode bypass-approvals.

Questions follow --auto-answer.

	A question from the coworker
At a terminal	asked in the terminal
At a terminal with --auto-answer	answered by the fixed rule above, and recorded
No terminal	answered by the fixed rule, and recorded

--auto-answer does not touch approvals: at a terminal they are still asked.

Two other requests go with the questions. A request for another folder, to read or to write, is asked at a terminal: yes, yes but read only, no, or a different folder; with --auto-answer or no terminal it is declined by rule. A pinned tool install is asked at a terminal and installed by rule otherwise.

Options

Flag	Meaning
--prompt TEXT / --prompt-file PATH	the task. With neither flag, the task is read from standard input when it is piped in (cat task.md | openworker run); --prompt-file - does the same
--workspace DIR	the folder the agent works in; the current folder when left out
--add-dir DIR	an extra folder the agent may read and write, beside the workspace (repeatable), for a harness whose output contract lives outside the workspace — e.g. --add-dir /output. The file tools only write inside the session's folders, in every mode; the shell is not scoped, so without this a delivery would depend on which tool the model happened to pick. Recorded under args.extra_dirs in summary.json.
--coworker ID	the coworker that does the task, by its id: cowork (default) or code. An unknown id stops the run with exit code 2
--model ID	provider:model or provider/model (first slash splits). Default: this computer's setting
--approval-mode	ask (default), auto-approve, bypass-approvals, dangerously-bypass-approvals
--auto-answer	nobody will answer questions; see above
--allow-site HOST[:PORT]	a site this run's commands and web tools may reach, beside this computer's allowed sites (repeatable). For this run only; the computer's list is not changed. Exact host names, no wildcards
--allow-sites-file FILE	the same, from a file: one HOST[:PORT] per line, # starts a comment
--out DIR	where the record goes. Default: sessions/<workspace path>/<session id>/ in OpenWorker's state folder, the workspace path written with dashes
--isolated	read nothing from this computer; see below
--reasoning-effort	low … max, sent to the provider; unset = provider default, recorded
--max-output-tokens, --max-iterations, --timeout-seconds	ceilings; --timeout-seconds 0 when an outer runner enforces its own
--no-web-tools	never offer web_search / web_fetch; for sealed evaluation runs and air-gapped work (a firewall only refuses the call, this removes the tool, and summary.json records web_tools: false)
--tool-result-max-bytes	bound each tool result (default 10,000; 0 = off); full text spilled under out/tool-output/
--provider-order	OpenRouter only: pin the upstream host, no fallback
--trajectory-atif PATH	also write the trajectory here

Isolated runs, for benchmarks

openworker run --isolated --prompt-file task.md --workspace /work \
    --model anthropic/claude-sonnet-5 --approval-mode bypass-approvals --out ./run-record

--isolated reads nothing from the computer: no settings, no stored keys, no sandbox. The model key comes from the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, TOGETHER_API_KEY, OPENROUTER_API_KEY, …), and OpenWorker's state and scratch folders are placed under --out. Two runs of the same task on two computers then start from the same place. It needs --out and --model, and a harness should pass --approval-mode too, so the record states it.

Exit code

Code	Meaning
0	the task finished
1	the run crashed before it could write a record
2	the command line could not be run as given
3	the run stopped early (time limit, model error, iteration limit, cut-off reply); the record is written
130	stopped with Ctrl-C or a stop signal (what timeout, a CI job or docker stop sends); the record is written

The record

File	Contents
trajectory.json	the run in ATIF-v1.7, with per-call token counts, the serving host, and an estimated cost from coworker/headless/prices.yaml (a cross-check; a consumer should price the counts itself)
summary.json	outcome, iterations, tool calls, tokens, cost, the arguments, the context window and compaction trigger used, the hosts that served the run
answers.json	every answer the engine gave on the absent user's behalf: refused cards, cleared checks, answered questions, declined folder requests, installs
events.jsonl	every engine event, in order, written as it happens
messages.json	the final conversation in OpenWorker's own shape
model_calls.jsonl	one line per model call: stop reason, usage, ceiling, effort, host
provider_errors.log	full cause chains of failed model calls, credentials redacted
audit.db	OpenWorker's audit log for the session

The trajectory and the exit code are the stable contract.

A transient provider failure or an empty reply does not end the run: the runner waits and re-enters the conversation with a nudge. The waits grow: 2 s, 5 s, 10 s, 30 s, 60 s, 120 s, 240 s, 300 s, 300 s. The first ones are short because the usual failure is one dropped connection, which the next request gets past. Permanent errors (bad key, unknown model, context overflow) are not retried.

Each retry prints a line with the error and its cause, for example provider error (APIConnectionError: Connection error. Cause: the proxy answered 403 Forbidden); retry 1/9 in 2s. A stop signal or Ctrl-C ends the run at once, also during the wait between retries, and the record is still written.