Use openscience run for a single terminal task. An external scheduler or CI system can invoke it repeatedly; this command does not create a recurring schedule by itself.
Run a bounded task
openscience run --deny-prompts --format json "Summarize the project README" > run.jsonl
This emits newline-delimited JSON. A rejected permission request can stop the run with exit code 3.
For work you have already reviewed and authorized, --auto-approve approves the run's permission requests, answers any question the agent asks with its recommended option, and continues past a denied tool call instead of ending the run. Delegation stays on: worker sessions stream into the same output. It is mutually exclusive with --deny-prompts.
openscience run --auto-approve --format json "Run the existing data validation script and report failures" > run.jsonl
Four flags shape a headless run:
| Flag | Effect |
|---|---|
--delegation off|light|standard|high | How freely the lead dispatches workers; the default is the saved preference. |
--worker-model provider/model | The model workers run on when their agent has none configured. |
--autonomy interactive|balanced|autonomous | How the lead treats decision points; --auto-approve defaults to autonomous. |
--deadline <seconds> | A wall-clock budget. The agent sees the Time budget in its environment, gets a reminder at 50% and at 85% that states the time used, and is asked to continue when time remains and named outputs are missing. |
openscience run --format json --auto-approve --workspace project \
--delegation standard --deadline 600 -- "Fit the model; write results/fit.csv and results/report.md"
Use a clearly scoped project and request. The command's ability to run still depends on installed tools, account access, and applicable policy.
Read events
Each event has type, timestamp in milliseconds, and sessionID. Events from a worker session carry that session's id and a parentID naming the session that dispatched it; root events have no parentID.
| Event | Main content |
|---|---|
user | Input parts and an optional command. |
step_start / step_finish | A model step; finished steps include usage. |
text | A completed text part. |
reasoning | A completed readable reasoning part, when available. |
tool_use | A completed or failed tool call; inspect part.state.status. A task result carries the worker's answer in a <task_result> envelope. |
permission | The permission request and reply. |
question | A question the run answered on the agent's behalf, with the answers. |
error | An error name and data. |
done | Final status, exitCode, the root session's tokens and cost, and children: one entry per worker session with its agent, model, tokens and cost. |
Example completion event:
{
"type": "done",
"timestamp": 1788600000000,
"sessionID": "ses_example",
"status": "completed",
"exitCode": 0,
"tokens": {
"input": 120,
"output": 40,
"reasoning": 0,
"cache": { "read": 0, "write": 0 }
},
"cost": 0
}
The numbers are illustrative. Usage summaries are not payment receipts.
Handle failures
Check both the process exit code and the final event. A process can fail before a session starts, so do not wait indefinitely for done after an early usage error, termination, or crash.
| Exit code | Interpretation |
|---|---|
| 0 | Completed turn. |
| 1 | Session error. |
| 2 | Invalid usage or missing configuration. |
| 3 | Rejected permission or question. |
Use the failed tool's status and saved output to decide what to retry. Avoid automatically replaying a paid request after an uncertain failure.
Configure a CI environment
Supply provider credentials through the CI system's secret settings. Install the OpenScience version you intend to use, prepare the required data and software, and set the working directory explicitly.
Useful environment settings include:
| Variable | Purpose |
|---|---|
OPENSCIENCE_DATA_DIR | Use a dedicated directory for this installation's saved data. |
OPENSCIENCE_CONFIG_DIR | Point to a dedicated configuration directory. |
OPENSCIENCE_DISABLE_AUTOUPDATE=1 | Keep the chosen version during a job. |
OPENSCIENCE_DISABLE_PROJECT_CONFIG=1 | Ignore configuration supplied by the task repository. |
Do not assume a fresh runner can run every scientific tool. Validate the environment and a small task before adding it to a pipeline.
Collect run.jsonl and the files the task produced. Review what they contain before exposing them as public CI artifacts.
Schedule outside OpenScience
Use your existing scheduler to launch the same tested command. Decide how overlapping runs, timeouts, credentials, and result retention should work.
See Sessions for continuing a particular session and SDK for programmatic integration.