INTEGRATE

OpenAI Codex

Use Phase from OpenAI Codex in two ways.

Connections: Codex uses services such as AWS and PostgreSQL through your Agent Workflow's Connections, approved in the Phase Console. It only ever sees decoy credentials; the Phase AI proxy swaps in the live ones. See Phase AI.
Application secrets: Codex can list, create, rotate and delete secrets in your Phase apps without reading their values.

Prerequisites

The Phase CLI, installed and up to date.
OpenAI Codex installed.
The Codex CLI on your PATH, even if you use Codex Desktop. phase ai enable uses it to install the plugin.
For Connections: an Agent and a Workflow in the Phase Console.

Setup

1. Log in

For Connections, log in with an Agent token for the Agent's Workflow, created in the Phase Console:

phase auth --mode token

For application secrets, log in as yourself with phase auth: Agent tokens can't access application secrets. To use Connections with your own login, set the Workflow in the next step with --workflow <workflowId>.

2. Enable Phase for Codex

Run this yourself, in your own terminal. Codex isn't allowed to run it.

phase ai enable --harness codex

It installs:

The phase-cli-ai-relay and phase-cli-app-secrets skills in ~/.agents/skills/.
The phase-ai-bootstrap plugin, from a Phase-owned local marketplace in ~/.phase/ai/codex-marketplace/ that phase ai enable registers with the Codex CLI. It starts the proxy when Codex first calls Phase.

It also creates the Phase AI CA and offers to trust it for your user (see The proxy CA), and asks whether Codex may read secret values.

3. Restart Codex

Open the Codex CLI, run /hooks, and trust every hook from phase-ai-bootstrap@phase-cli-local. Then fully quit and restart Codex (the CLI or Codex Desktop), start a new task, and repeat your original prompt.

Using Connections

Ordinary commands keep your usual credentials. When you ask Codex to use Phase, it runs the command with phase ai exec, adding --connection <connectionId> when a service has several Connections:

phase ai exec -- aws s3 ls

The plugin starts the Phase AI proxy the first time Codex calls Phase, and phase ai exec reuses it.

In Codex's default sandbox, each Phase call needs Codex's network approval. To skip it, set network_access = true under [sandbox_workspace_write] in ~/.codex/config.toml.

You: what can Phase manage here?
You: use Phase to list the S3 buckets in our dev AWS account
You: use Phase to count yesterday's orders in the analytics database

When the Workflow has no Connection for what you asked, Codex creates a request and shows you a link to it in the Phase Console. Create or choose the credential there and approve the request; Codex waits and then carries on. See Requests and approvals.

Managing application secrets

The phase-cli-app-secrets skill lets Codex work with your Phase apps and environments without seeing sensitive values: Invoke a skill explicitly with $phase-cli-ai-relay or $phase-cli-app-secrets, or let Codex pick it from the task.

List apps, environments and secret keys.
Create or rotate secrets with random values (--random), so the value never appears in the conversation.
Create and update non-sensitive config values.
Delete secrets, after confirming the app, environment and path.

You: list the secret keys in staging for the backend app
You: create STRIPE_WEBHOOK_SECRET as a sealed secret with a random value
You: rotate API_TOKEN in development
You: set LOG_LEVEL to debug in development

Codex doesn't read secret values (phase secrets get, phase secrets list --show, phase secrets export), import .env files, or run phase run or phase shell. Run those yourself in a terminal. When a sensitive value has to be entered by hand, Codex asks you to enter it in the Phase Console or your terminal rather than in the chat.

Secret visibility

Type	Visible to Codex	Description
`config`	Always	Non-sensitive configuration, such as ports, hosts and flags
`secret`	Your choice in `phase ai enable` (`--mask` or `--no-mask`)	Standard encrypted secrets
`sealed`	Never	Write-only secrets, such as API keys, tokens and passwords

Sealed secret values are never shown to AI agents, whatever you choose. Codex creates and rotates them with --random, so the value never appears in the conversation.

Security guardrails

Guardrail	Enforcement
Live provider credentials	Stay in the Phase AI proxy; Codex only sees decoys
Calls that mint new credentials (for example `sts:GetSessionToken`)	Blocked by the proxy
`phase ai enable` / `phase ai disable`	Blocked; run them yourself
`printenv`, `env`, `export`, `set`, `declare`, `compgen` inside `phase run`	Blocked by the CLI
`phase shell`	Blocked for AI agents
Sealed secret values in output	Always redacted
Secret values in `phase secrets` output	Redacted according to your visibility choice

Managing the integration

# Check setup, the proxy and the Workflow's Connections
phase ai status

# Refresh the skills and plugin after a CLI upgrade
phase ai enable --harness codex

# Remove the integration
phase ai disable

# Print the Phase AI skill
phase ai skill

Troubleshooting

Codex doesn't know about Phase

Check that the skills are installed:

ls ~/.agents/skills/phase-cli-ai-relay/SKILL.md ~/.agents/skills/phase-cli-app-secrets/SKILL.md

If they're missing, run phase ai enable --harness codex and restart Codex.

Phase-managed commands fail

Run phase ai status and check the Proxy and Connections lines. A Connection must be ready. When Codex reports a Phase error, it quotes the X-Phase-Event-Id from the response, which you can look up in the Phase Console.

Authentication errors

Check who you're logged in as:

phase users whoami