> ## 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.

# Install on Copilot CLI

> Install the Plurai Simulation plugin on GitHub Copilot CLI, sign in through your browser, and run your first flow.

This page takes you from nothing to a running simulation flow on GitHub Copilot CLI. The flows are the same as
on Claude Code, but you type the plugin's name in front of each command: `/plurai-simulation:simulate` runs
everything end to end, and `/plurai-simulation:simulation-scan-agent`,
`/plurai-simulation:simulation-generate-suite`, `/plurai-simulation:simulation-run` and
`/plurai-simulation:simulation-fixes` run one stage each.

The first Plurai command signs you in through your browser and installs the SDK for you.

## Requirements

* macOS, Linux or Windows (PowerShell, with Git for Windows; Python agents only), with `python3` on the `PATH`.
  Every hook runs as `python3 …`.
* GitHub Copilot CLI. Verified on 1.0.91 through 1.0.93; a newer version is unverified until this page lists
  it. Copilot updates itself unless you set `COPILOT_AUTO_UPDATE=false`.
* Python 3.12 or newer for your agent's environment. The plugin installs the `plurai` SDK there.
* A browser, to sign in or sign up. On a machine without one, see [No browser](#no-browser).

## Set up

**1. Install the plugin**

```bash theme={null}
copilot plugin marketplace add plurai-ai/plurai-plugins
copilot plugin install plurai-simulation@plurai-plugins
```

The skills, hooks and backend MCP server load with the install. There is nothing to approve.

**2. Check that every skill loaded**

```bash theme={null}
copilot skill list
```

The output has no "failed to load" section when every skill loaded.

**3. Start Copilot with the plugin's folder allowed**

The plugin installs outside your project, so Copilot asks for path access on each plugin script and
reference file it touches. A full `/plurai-simulation:simulate` run asked 22 times in testing, and an
unanswered prompt stalls the run. `--allow-all-tools` does not cover paths. Allow the folder up front:

```bash theme={null}
copilot --add-dir <the plugin's folder>
```

`/plurai-simulation:harness-setup` prints the plugin's folder. `--add-dir` also loads that folder's
`.github/skills` and `.github/agents` as trusted configuration.

**4. Check the install**

In a Copilot session, run:

```text theme={null}
/plurai-simulation:harness-setup
```

It says whether you are signed in, and signs you in when you are not.

**5. Sign in**

There is nothing more to run: the first Plurai command signs you in. It opens your browser, where you sign
in or sign up, pick your organization and approve. The SDK creates its own key and saves it; the key is
never shown, typed or copied. When the SDK is missing, the command asks once and installs it first.

The plugin's backend tools pick up the new login in the same session. If Copilot does not refresh them, the
command says `Restart Copilot to connect Plurai, then run <command> again.`

### No browser

On a machine without a browser, create a key in the Plurai dashboard and save it once, in a terminal of your own:

```bash theme={null}
python3 <plugin root>/scripts/plurai_login.py --url https://<your-backend>
```

It asks for the key with echo off. Run it in your own terminal, never through the model. You can also export
`PLURAI_URL` and `PLURAI_TOKEN` together in the environment that launches Copilot. See
[Environment variables](https://docs.plurai.ai/reference/environment-variables.md#connect-to-the-backend).

## Run a flow

Start Copilot in your agent's project and type the command with the plugin's name. `simulate` runs every stage:

```text theme={null}
/plurai-simulation:simulate <path-to-your-agent>
```

To go one stage at a time, start with `/plurai-simulation:simulation-scan-agent <path-to-your-agent>`.

* **Use the qualified form.** A bare `/simulation-scan-agent <path-to-your-agent>` is an unknown command on
  Copilot. A bare command with no arguments goes through Copilot's picker, which runs the first match on Enter;
  that can be a different flow.
* **At the keyboard, use the default interactive mode, not autopilot.** The flows ask you questions at their gates
  (grounding, topology approval, run readiness, fix selection), and autopilot answers them with a canned reply.
  Unattended runs are the exception: they use autopilot, as shown in [Headless runs](#headless-runs).
* **Choose a Claude model.** Copilot routes to a GPT model by default and the skills are tuned on Claude. Pass
  `--model <model>`.
* **Keep gated steps in the main agent.** A Copilot subagent has its own session, and the plugin's guards do not
  follow it there.
* **Set `COPILOT_ALLOW_ALL=true` only in a directory you trust.** That exact value auto-approves every tool and
  trusts the working directory, which loads its skills, plugins, MCP servers and hooks.

A missing login is not a problem: the flow signs you in and carries on. Every flow checks the rest of the
install first and stops with one line per problem:

```text theme={null}
flow-window: NOT READY (<check>): <what to fix>
```

| Check | What it means on Copilot |
| - | - |
| `hooks` | The plugin's hooks did not run. Check that the plugin is installed, then restart the session. |
| `backend tools` | The `plurai` tools are missing. `python3` is not on the `PATH` that launched Copilot, the plugin is not enabled, or the server is not connected (`copilot mcp list`). If a `bridge_status` tool is listed, call it: it says what to change. |
| `one backend` | The backend the MCP tools call is not the one the shell uses. The line names the fix. |
| `window` | The flow's guard window is not armed. The line names the fix. |

## Headless runs

`copilot -p` cannot ask you anything. Declare that nobody is there with `PLURAI_SIM_NONINTERACTIVE=1`, or
`workspace.run_driver: headless` in `plurai.config.yaml`. Each gate then takes its default, or records a finding
and stops when only you can supply the answer.

* **Start each stage with `-p` in autopilot.** Create `~/.plurai` first, and allow the plugin's folder and
  `~/.plurai`. `/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"
  ```

* **Run `/simulate`'s stages one by one.** `/simulate` can't start under `-p`, so run each stage in its own `-p` call.

* **Declare gates with no default before you start.** The anonymization posture has no default, so set
  `anonymize: true` or `false` in `plurai.config.yaml` first.

* **Put the agent's provider key in the agent's own `.env`.** Copilot removes provider variables such as
  `OPENAI_API_KEY` from the model's shell. The runner reads the gitignored `.env` next to the agent module.

* **Sign in once in an interactive session first.** A headless run with no login stops with "Plurai is not
  logged in. Sign in once in an interactive session, then run this again." In CI, export `PLURAI_URL` and
  `PLURAI_TOKEN` instead.

* **Allow every folder the run reads** with `--add-dir`, the plugin's folder included.

See [Run in CI](https://docs.plurai.ai/guides/ci.md).

## Use a non-default backend

A test or self-hosted backend needs its URL exported in the environment that launches Copilot:

```bash theme={null}
export PLURAI_URL=https://<your-backend>
```

With no key exported, the browser login signs in to that backend. The URL must be `https`, or `http` to a
loopback address. A saved login belongs to one backend; the plugin does not hand its key to another. A backend
outside `*.plurai.ai` and loopback needs `PLURAI_URL` and `PLURAI_TOKEN` exported together.

> [!WARNING]
>
> If you run the plugin from a local checkout, do not add a `.mcp.json` at its root. Copilot loads a root
> `.mcp.json` and it hides the MCP servers of every manifest, so the backend tools disappear.

## What differs from Claude Code

* Commands carry the plugin's name: `/plurai-simulation:<command>`. The hand-off names the next command the
  same way.
* There is no autopilot for gated flows.
* Copilot picks a GPT model unless you pass `--model`.
* Subagents run outside the plugin's session-keyed guards.
* There is no dropped-turn rescue. A turn that dies on an API error is not re-driven; re-invoke the same
  command and it resumes.
* The [report](https://docs.plurai.ai/report/overview.md) is a local file, not a link. Each hand-off names its path; open it in a
  browser. It refreshes in place while a Run plays.

## Update

```bash theme={null}
copilot plugin update plurai-simulation
```

Restart the session afterwards.

## Privacy

The plugin sends no client-side telemetry. See [Data and privacy](https://docs.plurai.ai/security/data-and-privacy.md).

## Next steps

> [card] [Scan your agent](https://docs.plurai.ai/guides/scan-your-agent.md)
>
> The first stage, in detail.

> [card] [Troubleshooting](https://docs.plurai.ai/troubleshooting.md)
>
> Fixes for common setup problems.


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