> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plurai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run unattended

> Run the simulation where nobody can answer questions, such as CI or a headless coding-agent session.

> [!NOTE]
>
> 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:

```yaml plurai.config.yaml theme={null}
workspace:
  run_driver: headless
```

```bash Environment variable theme={null}
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:

> [tab] Claude Code
>
> 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:
>
> ```bash theme={null}
> 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:
>
> ```json theme={null}
> {
>   "permissions": {
>     "additionalDirectories": ["<the path printed above>"]
>   }
> }
> ```
>
> Then run:
>
> ```bash theme={null}
> PLURAI_SIM_NONINTERACTIVE=1 claude -p "/simulation-run"
> ```

> [tab] Copilot CLI
>
> 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.
>
> ```bash theme={null}
> 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.

> [tab] Codex CLI
>
> ```bash theme={null}
> PLURAI_SIM_NONINTERACTIVE=1 codex exec '$simulation-run'
> ```
>
> Tools that delete or cancel something keep Codex's own approval, and `codex exec` cancels them.

> [!NOTE]
>
> 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](https://docs.plurai.ai/integrations/codex-cli.md).

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](https://docs.plurai.ai/reference/environment-variables.md).

## 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](https://docs.plurai.ai/security/data-and-privacy.md).
* **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`:

```yaml plurai.config.yaml theme={null}
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

> [card] [Configuration](https://docs.plurai.ai/reference/config.md)
>
> `workspace.run_driver`, `anonymize` and `approve_harness_edits`.

> [card] [Save and switch environments](https://docs.plurai.ai/guides/environments.md)
>
> Commit an environment so CI runs the same suite.

> [card] [Run the simulation](https://docs.plurai.ai/guides/run-the-simulation.md)
>
> What a run does and where results appear.

> [card] [Permissions](https://docs.plurai.ai/reference/permissions.md)
>
> Running the plugin under auto permission mode.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.