Run unattended

Ready-made CI pipeline integration, such as GitHub Actions, is coming soon. Until then, use the headless setup on this page.

You can run the simulation commands in a session where nobody is there to answer, such as a CI job or a headless coding-agent run. You declare that the session is unattended, answer in advance the questions that need you, and every other question takes a safe default.

Declare that nobody is there

A headless session has no way to ask you anything. Declare it with either of these:

workspace:
  run_driver: headless

export PLURAI_SIM_NONINTERACTIVE=1

An explicit workspace.run_driver: interactive in plurai.config.yaml wins over the variable. With neither set, a headless run stops at the first question and waits for an answer that never comes. Then start your coding agent in its non-interactive mode, one stage per call:

Claude Code
Copilot CLI
Codex CLI

Claude Code asks before reading the plugin’s own files, and nobody can answer that in CI. Add the plugin’s folder as an extra working directory once. Print its path:

echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/plugins/cache/plurai-plugins/plurai-simulation"

Put it in ~/.claude/settings.json. The path has no version in it, so updates need no change:

{
  "permissions": {
    "additionalDirectories": ["<the path printed above>"]
  }
}

Then run:

PLURAI_SIM_NONINTERACTIVE=1 claude -p "/simulation-run"

Create ~/.plurai first, then start the stage with -p in autopilot, with the plugin’s folder and ~/.plurai allowed. /plurai-simulation:harness-setup prints this line with your folders filled in.

mkdir -p "$HOME/.plurai"
PLURAI_SIM_NONINTERACTIVE=1 copilot -p "/plurai-simulation:simulation-run" --autopilot --allow-all-tools \
  --add-dir "<the plugin's folder>" --add-dir "$HOME/.plurai"

/simulate can’t start under -p. Run its stages one at a time instead, one -p call each.

PLURAI_SIM_NONINTERACTIVE=1 codex exec '$simulation-run'

Tools that delete or cancel something keep Codex’s own approval, and codex exec cancels them.

On Codex CLI, codex exec runs no hook that is not trusted yet. Trust the plugin’s hooks in an interactive session first, and again after each plugin update. See Codex CLI.

A CI job can’t sign in with a browser. Create a key in the Plurai dashboard and export PLURAI_URL and PLURAI_TOKEN in the job’s environment. See Environment variables.

What happens to questions

Each question a command can ask is either a decision or something only you can supply.

A decision takes its declared default and the command continues.
Something only you can supply (a key, credentials, a target) is recorded as a finding that says what is missing, and the step it guards does not run.

The decisions you are most likely to meet:

Question	Unattended default
Approve the agent map from the scan	Approved, without running the read-only tool probes
Apply a fix to your harness files (`simulate.py` and helpers)	Declined, unless `approve_harness_edits: true`
Build a knowledge corpus before the suite	Proceed without a corpus
Record the run in your observability platform	Neither (no experiment, no traces)
Which fixes to accept after `/simulation-fixes`	None
Delete something on the backend	Declined
Send your content to the Plurai backend for grounding	Declined

Answer in advance what needs you

Supply these before an unattended run. Without them, the step that needs them does not run:

Anonymization posture. Declare anonymize: true or anonymize: false in plurai.config.yaml. There is no default: the plugin never picks one for you, and the run stops until you declare it. See Data and privacy.
Your agent’s model-provider key. Put it in the gitignored .env file in your agent’s folder. This is required on Copilot CLI, which strips provider keys from the shell.
Your observability key and project, if you record runs to LangSmith or Langfuse. Put the key in the same .env file, or declare observability off.
Where your agent is. Start the run from your agent’s folder. PLURAI_AGENT_PATH can narrow which agent is used, but it doesn’t replace starting there.
A blocker the suite raises, such as a fact only you know. Answer it in an interactive session, or declare the fact it asks for.

Approve harness edits in advance

While it builds the suite, the plugin sometimes finds a fix that belongs in your harness: simulate.py, its helpers, or a runner of your own that plurai.config.yaml declares as harness.entry_wrapper. These files are yours, so the plugin asks before it writes to them. When nobody can be asked, the edit is declined: the fix stays unapplied, and the plugin reports the file and the diff it would have applied. To approve these fixes in advance, add a top-level key to plurai.config.yaml:

plurai.config.yaml

approve_harness_edits: true

true approves harness edits when nobody can be asked. The plugin applies the diff and logs the question, the file path, the diff and the answer.
false, or leaving the key out, keeps them unapplied and reported.
It applies only when nobody can be asked. In an interactive session you are still asked.

The plugin never writes this key for you.

Long waits

Building the suite can take tens of minutes. In a headless session the plugin keeps the turn open and polls until each backend job finishes, because nothing wakes the session up later. A turn that dies on an API error is not retried for you: run the same command again and it resumes.

Next steps

Configuration

workspace.run_driver, anonymize and approve_harness_edits.

Save and switch environments

Commit an environment so CI runs the same suite.

Run the simulation

What a run does and where results appear.

Permissions

Running the plugin under auto permission mode.

Simulate your agent

Go further

Read your report

Declare that nobody is there

What happens to questions

Answer in advance what needs you

Approve harness edits in advance

Long waits

Next steps

Configuration

Save and switch environments

Run the simulation

Permissions

​Declare that nobody is there

​What happens to questions

​Answer in advance what needs you

​Approve harness edits in advance

​Long waits

​Next steps

Configuration

Save and switch environments

Run the simulation

Permissions

Declare that nobody is there

What happens to questions

Answer in advance what needs you

Approve harness edits in advance

Long waits

Next steps