Codex

The Actera plugin connects Codex tool requests to your workspace: shell commands, file edits, MCP tools and other local tools. Hosted tools such as web search do not run hooks. Start with Monitoring to inspect the requests and define policies before enforcing them.

Install and connect

In Actera, open Agents → Add agent → Codex. Use the installation commands shown there. The current setup uses:

codex plugin marketplace add Actera-AI/actera-codex
codex plugin add actera@actera

Inside Codex, run:

$actera-connect

Follow the browser connection flow, verify that its code matches the one Codex displays, and approve the intended agent and workspace. With a setup code from the Overview, run $actera-connect <code> instead; it connects to the agent the code was made for. Codex may ask to run the connect command outside its sandbox, because it reaches Actera and writes to ~/.actera/codex.

Then open /hooks in Codex, trust the two Actera hooks, and start a new session. Codex does not run a plugin’s hooks until they are trusted, and asks again after each plugin update. $actera-status reports when no hook has run yet.

Use a tool in Codex. Actera confirms the first request and shows the agent. If setup was closed, find it under Not set up.

Configure its authority

New installations default to Monitoring. Review actual action names and arguments in Decisions, create policies from representative requests, and add tests for the boundaries that matter. Codex actions are named codex.tool.<tool> (for example codex.tool.Bash and codex.tool.apply_patch) and codex.mcp.<tool>. Reconnecting preserves the plugin’s settings.

Publish and assign the policies, then choose the agent’s When no policy matches setting. Saving this configuration does not itself change the plugin’s mode.

Run $actera-mode in Codex to choose:

• Mode: Monitoring records results without stopping tools. Enforcing applies Allow, Require approval, and Block.
• When Actera cannot evaluate: in Enforcing, block tool calls by default, or explicitly choose to allow them during an evaluation failure. Allowing them means those calls can run without an authority decision.

The change applies to the next tool call. Confirm that new requests appear as Enforcing in Actera and exercise an allowed and blocked tool call.

Handle approvals

Codex cannot ask a question from a hook, so in Enforcing mode a call that needs approval waits while Actera notifies eligible reviewers in Actera, Slack or email. Codex shows “Checking with Actera” meanwhile. An approval releases the call; a rejection denies it with the reviewer’s reason. After about nine minutes without a decision the call is denied with a link to review it, and an identical retry in the same session within an hour reuses the approval once. Check Needs approval for the request, its reason, and current status.

Approval does not independently prove that the tool ran or completed; review execution reports alongside the decision. Codex reports no success flag to its hooks, so the plugin reads each call’s status from the Codex session transcript and reports UNKNOWN when that record is missing.

Understand what is sent

The plugin sends tool names and inputs after sensitive-field redaction and secret scanning. Detection is best effort: ordinary commands, file paths, and other non-secret input can remain visible. Prompts and tool output are not sent.

Review the recorded input before broader rollout. Include only tools and environments whose data is appropriate for your workspace.

Manage access

The agent’s Connection panel shows connection status and key expiry. Disconnect stops that key immediately. Run $actera-connect to establish a new connection, or $actera-disconnect to remove this machine’s connection.

Policies cover requests that pass through the plugin. Codex lets a call run when a hook crashes or exceeds its timeout, and untrusted hooks do not run at all. For mandatory enforcement, deploy the same hooks as managed hooks in Codex’s requirements.toml, and verify coverage for the tools your team uses before relying on enforcement.