GuidesRunning & maintaining

opencode run: OpenCode headless, on cron or a systemd timer

Run OpenCode unattended: opencode run flags, JSON output, permissions that never ask, --standalone vs the background service, timers, and what fails.

November 18, 2026The Everpod team
The short answer

opencode run "your prompt" is OpenCode’s headless mode: it sends one message, prints the reply and exits, 0 on success and 1 on failure. For a timer or cron job on a server, as of OpenCode 2.3.2 (November 2026): call it by its full path, ~/.opencode/bin/opencode; add --standalone so the run gets a private server that sees the job’s own environment instead of borrowing the shared background service; pass the provider key in that environment; add --format json for output a script can parse and --archived to keep the run out of your session list; and put a timeout around it, because a run waits, with no limit, for any background job it started. It never stops to ask: a permission request is rejected automatically and the run carries on, still exiting 0, unless you pass --auto.

One-shot runs

The CLI docs describe opencode run as “designed for scripts, CI jobs, and other workflows that need model output directly in the terminal.” The flags that matter for a job, from the command’s definition at the v2.3.2 tag:

opencode run "summarise yesterday's commits"
opencode run -m anthropic/claude-sonnet-5-5 "..."  # provider/model#variant
opencode run --agent plan "..."      # a named agent
opencode run -f notes.md "..."       # attach a file
opencode run --title "nightly" "..."
opencode run -c "..."                # continue the last session
opencode run -s <session-id> "..."   # continue that session
opencode run -w "..."                # new session in a new git worktree
opencode run --archived "..."        # created archived
Copied

Piped input is read too: with no message, standard input is the message, and with both, the piped text is added after the message on a new line. So git log --since=yesterday | opencode run "summarise these commits" works. With neither, the run stops with You must provide a message. There is no directory flag in version 2; the run works in the folder it starts in, so a job changes into the project folder first.

--archived keeps scripted runs from filling the session list; the 2.2.6 release notes add that archived sessions are skipped by --continue, so a job that archives its runs and then continues “the last session” gets your last interactive one instead. Continue by ID when a job needs its own thread.

Output a script can read

In the default format the reply goes to standard output as plain text when stdout is not a terminal, and warnings and errors (prefixed Error: ) go to standard error. --format json writes one JSON object per line to standard output instead, each with type, timestamp and sessionID. The types are step_start, step_finish (with cost and tokens), text, reasoning, tool_use, retry, error and background_wait. The reply is in the text events:

opencode run --format json "..." > run.jsonl
jq -r 'select(.type=="text") | .part.text' run.jsonl
jq -r 'select(.type=="error") | .error.message' run.jsonl
jq -r '.sessionID' run.jsonl | head -1
Copied

The session ID is printed nowhere in the default format, so JSON is also the way to learn which session a run made, for -s later or for opening it in the terminal interface.

Permissions: it never asks, and that can hide a failure

A run cannot wait for anyone. When the agent hits a permission set to ask, the run rejects it, prints ! permission requested: <action> (<resource>); auto-rejecting on standard error, and tells the model “This non-interactive run cannot ask the user for permission, so the request was rejected. Continue without this action.” The run then carries on, and nothing in that path changes the exit status. A job whose key step was refused can finish with 0 and a reply explaining what it could not do. A question from the agent is cancelled the same way, with the model told to “make reasonable assumptions and state them.”

How often that happens depends on your rules. Per the permissions docs, every agent starts from a base policy that allows everything except reading *.env and *.env.* files, which ask. So on a default setup the agent can run shell commands and edit files without a prompt, and only rules you add, or a match on nothing (“If no rule matches, OpenCode uses ask”), produce rejections. Two ways to set it up for a job:

Whichever you choose, check standard error for auto-rejecting after a run rather than trusting the exit status. And do not lock the agent down by denying read outright if the job uses one of OpenCode’s free models: that makes every run fail with “OpenCode’s free tier can only be used from within OpenCode” (reported in #55653). Deny narrow patterns instead.

Which server a run uses, and why it matters on a timer

OpenCode 2 runs its sessions and tools in a server process, and opencode run picks one of three. The source’s own comment: “A one-off run uses the background service when it is already up, but never leaves a new one running.”

So the same job behaves differently depending on whether someone opened OpenCode on the machine since it last booted. --standalone removes that: every run gets a fresh private server with the job’s environment, which is what OpenCode’s own CI example does (“use standalone mode so the private server receives it”). The cost is a cold start each time, MCP servers included. To make standalone the default for every command in the account, opencode service set disabled true; how the shared service behaves otherwise is in OpenCode’s background service.

Credentials for a job

In version 2, keys and sign-ins saved with opencode auth login or /connect are not in auth.json. The providers page: “Saved API keys and OAuth tokens live in the server’s SQLite database,” usually ~/.local/share/opencode/opencode.db. Version 2 imports a version 1 ~/.local/share/opencode/auth.json once, during its database migration, and “New and updated credentials are stored in SQLite rather than written back to that file.” Editing either file by hand is not supported.

For a scheduled run the docs’ pattern is a provider variable such as ANTHROPIC_API_KEY in the run’s environment with --standalone; OpenCode “reads a supported variable from the server process without saving it.” Keep the key in a file only your account can read (chmod 600) and have the script read it, rather than writing it into a unit file or crontab. With no key and no account at all, a run falls back to OpenCode’s free models, which have a daily allowance of their own: OpenCode’s free usage limit covers what a run sees when it is spent.

A run that never ends

Since 2.2.6, opencode run “now waits for the background shell commands, subagents, and image jobs that its prompt started,” printing waiting for N background job(s) (a background_wait event in JSON). There is no time limit, and the release notes name the case: a dev server or file watcher the agent started keeps the run open until something cancels it. Since 2.3.1, a shell command that outlives its own timeout also moves to the background instead of being killed, so a long build or test run is waited for too.

The bound has to come from outside. The same release made SIGTERM the clean way to stop a run: it “cancels the session and its background jobs and exits with code 143.” Both timeout and systemd send SIGTERM by default, so either works.

On a systemd timer

A script, a service and a timer. The script, ~/bin/opencode-nightly.sh, made executable:

#!/bin/bash
set -uo pipefail
export PATH="$HOME/.opencode/bin:/usr/local/bin:/usr/bin:/bin"
export ANTHROPIC_API_KEY="$(cat "$HOME/.config/keys/anthropic")"
cd "$HOME/project"
out="$HOME/runs/$(date -u +%F)"

opencode run --standalone --archived --format json \
  -m anthropic/claude-sonnet-5-5 --title "nightly $(date -u +%F)" \
  "$(cat prompts/nightly.md)" > "$out.jsonl" 2> "$out.err"
status=$?

grep -q 'auto-rejecting' "$out.err" && echo "permission refused" >&2
exit $status
Copied

The PATH line matters twice: the installer adds ~/.opencode/bin to ~/.bashrc, which neither systemd nor cron reads (installing OpenCode on Linux), and the agent’s own shell commands inherit this PATH, so the tools the job needs belong on it too. The service, ~/.config/systemd/user/opencode-nightly.service:

[Unit]
Description=Nightly OpenCode run

[Service]
Type=oneshot
ExecStart=%h/bin/opencode-nightly.sh
TimeoutStartSec=45min
Copied

And opencode-nightly.timer beside it:

[Unit]
Description=Nightly OpenCode run, 02:30 UTC

[Timer]
OnCalendar=*-*-* 02:30 UTC
Persistent=true

[Install]
WantedBy=timers.target
Copied
systemctl --user daemon-reload
systemctl --user enable --now opencode-nightly.timer
systemctl --user start opencode-nightly.service   # one run now, to test
loginctl enable-linger                            # keep it with you logged out
Copied

TimeoutStartSec is the bound: a oneshot service has none by default, and at 45 minutes systemd sends SIGTERM, the run cancels its jobs and exits 143, and the service is marked failed. Without lingering, your account’s systemd stops shortly after you log out and takes the timer with it; lingering for a user service explains it.

From cron, the same script works, with a timeout in the line since cron has none: 30 2 * * * timeout 45m /home/you/bin/opencode-nightly.sh. cron runs the line with the machine’s own time zone and a minimal PATH, which the script already sets, and needs no lingering. A run killed by timeout shows as exit 124 to cron.

What fails with nobody watching

None of these covers the run that never started: a timer not enabled, lingering off, the machine down. A message from every run, success or not, makes silence the signal; notifications from an agent on a server covers routes that work from a cloud machine, and Claude Code and Codex on a schedule covers the same job for those agents, with OnFailure= and heartbeat checks.

OpenCode 2.3.1 also added an experimental automations feature, behind a flag, which runs a prompt “on a time, an interval, a cron or a pushed MCP event”. It lives inside OpenCode rather than the system’s scheduler and was experimental as of November 2026.

On OpenCode 1

Version 1’s run has no shared service. Its equivalent of --server is --attach http://localhost:4096, “attach to a running opencode server”, started with opencode serve, with --password or OPENCODE_SERVER_PASSWORD for its basic auth, and --dir sets the working folder. Its --auto and the auto-reject behave as above. Version 1 no longer gets OpenCode’s free models, so a job on a free model needs version 2; moving from OpenCode 1 to 2 covers the upgrade.

Run OpenCode on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.