> ## 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 Codex CLI > Install the Plurai Simulation plugin on OpenAI Codex CLI, set up hook trust and shell network access, sign in, and run your first flow. 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](#no-browser). ## Set up **1. Install the plugin** ```bash theme={null} 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. **2. Print your setup** In a Codex session, run: ```text theme={null} $harness-setup ``` It prints the exact settings for your install. **3. 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. **4. 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. > [tab] Every session > > Add this to `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`): > > ```toml theme={null} > [sandbox_workspace_write] > network_access = true > ``` > [tab] One session > > Pass it on the command line. This also works for `codex exec`: > > ```bash theme={null} > codex -c sandbox_workspace_write.network_access=true > ``` > [!WARNING] > > 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. **5. Restart Codex** Codex reads skills, hooks and the MCP server at session start. Restart it after you change the configuration or the environment. **6. Sign in** 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 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 /scripts/plurai_login.py --url https:// ``` 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](https://docs.plurai.ai/reference/environment-variables.md#connect-to-the-backend). ### 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: ```toml theme={null} 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: ```text theme={null} $simulate ``` To go one stage at a time, start with `$simulation-scan-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: ```text theme={null} flow-window: NOT READY (): ``` | 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](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 Codex, and no `config.toml` entry: ```bash theme={null} export PLURAI_URL=https:// ``` 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](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} 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](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.