Install on Codex CLI

This page takes you from nothing to a running simulation flow on Codex CLI. The flows are the same as on Claude Code, but you start them with a dollar sign: $simulate runs everything end to end, and $simulation-scan-agent, $simulation-generate-suite, $simulation-run and $simulation-fixes run one stage each. Codex needs two things the plugin cannot set for you: one keypress of hook trust, and shell network access. The first Plurai command then signs you in through your browser and installs the SDK for you.

Requirements

macOS or Linux, with python3 on the PATH. Every hook runs as python3 ….
Codex CLI. Verified on 0.160.0; a newer version is unverified until this page lists it.
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.

Set up

Install the plugin

codex plugin marketplace add plurai-ai/plurai-plugins
codex plugin add plurai-simulation@plurai-plugins

The skills load with the install. Hooks and the backend tools need the next steps.

Print your setup

In a Codex session, run:

$harness-setup

It prints the exact settings for your install.

Trust the plugin's hooks

The plugin’s guards are hooks, and Codex runs a plugin hook only after you trust it. On the first start after you install or update the plugin, Codex shows Hooks need review. Choose Trust all and continue. The hooks run in that same session.If you chose Continue without trusting, open /hooks in a running session and press t to trust them all.

Open the shell's network

The Codex sandbox blocks the shell’s network by default, loopback included. The plugin’s scripts and the simulation runner reach the backend from the shell, so run Codex with the workspace-write sandbox and open its network.

Every session
One session

Add this to ~/.codex/config.toml (or $CODEX_HOME/config.toml):

[sandbox_workspace_write]
network_access = true

Pass it on the command line. This also works for codex exec:

codex -c sandbox_workspace_write.network_access=true

This gives every shell command in the workspace-write sandbox network access to any host. Writes stay limited to the workspace and temp folders, but a command that a prompt injection steers could send workspace data anywhere. The config-file form applies to every Codex project.

Restart Codex

Codex reads skills, hooks and the MCP server at session start. Restart it after you change the configuration or the environment.

There is nothing 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 Codex does not refresh them, the command says Restart Codex 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:

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: a key typed to a model lands in its transcript. You can also export PLURAI_URL and PLURAI_TOKEN together in the environment that launches Codex. See Environment variables.

Limit network access to named hosts (experimental)

A Codex permission profile can open the network only to the hosts you name. It relies on Codex’s network_proxy feature, which Codex marks experimental. A profile replaces network_access, so do not combine the two. Add an entry for the backend, the agent under test’s model host, any package index, and 127.0.0.1 if you use a local service:

default_permissions = "plurai"

[features]
network_proxy = true

[permissions.plurai]
extends = ":workspace"

[permissions.plurai.network]
enabled = true
domains = { "api.example.com" = "allow", "127.0.0.1" = "allow" }

Run a flow

Start Codex in your agent’s project and invoke the command with a dollar sign. $simulate runs every stage:

$simulate <path-to-your-agent>

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

Start with $simulate or $simulation-scan-agent. Building-block skills such as $simulation-setup also run when you type them on Codex, but they are steps of the scan.
Answer gates as a new message. Codex has no blocking question tool in Default mode. At a gate the model asks one question with its options and ends the turn. Reply with one of the listed options.
Use Default mode, not Plan mode. Plan mode forbids the file edits the flows make.
Choose a Claude model if Codex offers one. The skills are tuned on Claude; Codex support was measured on OpenAI models only.

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:

flow-window: NOT READY (<check>): <what to fix>

Check	What it means on Codex
`hooks`	The plugin’s hooks did not run. Trust them in the startup dialog or in `/hooks`. Trust that a project or managed config layer supplies is not visible; trust must be in your user `config.toml`.
`backend tools`	The `plurai` tools are missing. `python3` is not on the `PATH` that launched Codex, or the server is off. If a `bridge_status` tool is listed, call it: it says what to change (a URL without its key, or a URL that is not `https`).
`network`	The shell has no network (`CODEX_SANDBOX_NETWORK_DISABLED` is set). Open it as above.
`one backend`	The backend the MCP tools call is not the one the shell uses, for example a user-level server entry that dials another URL.
`window`	The flow’s guard window is not armed. The line names the fix.

Headless runs

codex exec 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. codex exec also skips hooks that are not trusted yet, so start Codex once and trust them first. Tools that delete or cancel something keep Codex’s own approval, and codex exec cancels them. See Run in CI.

Use a non-default backend

A test or self-hosted backend needs its URL exported in the environment that launches Codex, and no config.toml entry:

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. If your config.toml sets [shell_environment_policy] inherit = "core", the shell sees neither variable. Put them under [shell_environment_policy.set] too, and keep the export where Codex launches: the MCP bridge reads them from there. This writes the key into config.toml in plain text, so use it only with a development key.

Who can read the key

The plugin’s own shell steps need your key, so on Codex it reaches the model’s shell in either form:

The saved login keeps other users out (mode 0600), not commands that run as you.
An exported PLURAI_TOKEN reaches the model’s shell by default. Setting [shell_environment_policy] ignore_default_excludes = false makes Codex drop variables whose names contain KEY, SECRET or TOKEN from that shell. The MCP tools still work, but the plugin’s shell steps that call the backend (uploads, polling, the runner) then stop, because they cannot find the key.

The key is as safe as the commands you approve. Run plurai logout and sign in again when a session went wrong.

What differs from Claude Code

Commands start with $, and the hand-off names the next command the same way.
Hooks need your trust once per install or hook change.
The shell needs network access.
A gate ends the turn; you answer in your next message.
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 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

codex plugin marketplace upgrade

Restart the session afterwards and open /hooks. Newer Codex versions ask you to approve the plugin’s hooks again after every plugin update. Until you do, flows stop with “plugin files changed”.

Privacy

The plugin sends no client-side telemetry. See Data and privacy.

Next steps

Scan your agent

The first stage, in detail.

Troubleshooting

Fixes for common setup problems.

Overview

Coding agents

Agent frameworks

Trace sources

Requirements

Set up

No browser

Limit network access to named hosts (experimental)

Run a flow

Headless runs

Use a non-default backend

Who can read the key

What differs from Claude Code

Update

Privacy

Next steps

Scan your agent

Troubleshooting

​Requirements

​Set up

​No browser

​Limit network access to named hosts (experimental)

​Run a flow

​Headless runs

​Use a non-default backend

​Who can read the key

​What differs from Claude Code

​Update

​Privacy

​Next steps

Scan your agent

Troubleshooting

Requirements

Set up

No browser

Limit network access to named hosts (experimental)

Run a flow

Headless runs

Use a non-default backend

Who can read the key

What differs from Claude Code

Update

Privacy

Next steps