Phantom documentation

Configure API key security for Codex and keep supported agent workflows inside Phantom's authenticated local proxy boundary.

Phantom + Codex

Why this combination exists

OpenAI Codex runs in a sandboxed environment and executes tasks autonomously. It reads files in your repository — including .env — to understand the project. Real API keys in .env would be visible to the agent and present in its working context throughout the task.

After phantom init, managed dotenv secrets are replaced by phm_ tokens, so Codex can use value-blind metadata instead of real values. For supported HTTP API routes in a process launched by phantom exec, the authenticated local proxy matches an exact route and injects only its route-owned vault value into the fixed auth header; client headers and bodies never resolve tokens. Connection strings and unsupported protocols fail closed or require a separately approved workflow; unmanaged files remain outside this boundary.

The MCP integration registers Phantom's release-schema-verified catalog in Codex. The current release contract enforces 54 unique tools; runtime tools/list is canonical. The CLI includes agent readiness, proxy lifecycle, audit, import/export, cloud sync, team vaults, and safe MCP setup for Codex.

Install

Step 1: install Phantom

Install the reviewed v0.7.8 binary using the platform-specific, checksum- verified path in getting started, then run phantom init in the project.

Step 2: wire up Codex (one command)

phantom setup --client codex

This patches ~/.codex/config.toml with an [mcp_servers.phantom] entry:

[mcp_servers.phantom]
command = "phantom-mcp"
args = []

Install both v0.7.8 release binaries before setup. Version 0.7.8 records the running phantom executable with mcp serve when it can resolve that runtime, otherwise it looks for a local phantom-mcp. Setup has no network package-runner fallback and fails closed when neither local runtime is executable. Keep both verified binaries installed and inspect the generated entry.

To preview the snippet without modifying your config:

phantom setup --client codex --print

After running setup, restart Codex for the MCP server to activate.

Step 3: verify agent readiness

phantom agent doctor
phantom agent report --json

phantom agent doctor is the human-readable preflight for Codex. It checks that env files are phantomized, the vault is available, MCP is wired, package scripts and pre-commit protection are in good shape, and cloud/team/sync state is visible. The JSON report returns unsafe, protected, verified, team-ready, or compliance-ready for automation.

Step 4: run Codex tasks with the proxy active

phantom exec -- codex "add Stripe checkout to checkout.ts"

This starts the Phantom proxy, sets the implemented *_BASE_URL overrides, then hands off to Codex. Calls made by SDKs that honor those overrides use the proxy; arbitrary network clients and unsupported protocols do not.

For explicitly supervised repeated runs, start phantom start in a trusted terminal and keep it open. Copy the printed exports into a second terminal, launch Codex there, and press Ctrl-C in the original owning terminal to stop. Detached --daemon mode and current external process control fail closed; phantom stop authenticates legacy v0.7.3 state only to report manual migration guidance and never kills a process or deletes the record.

MCP tools Codex can use

Once phantom-secrets-mcp is registered, Codex can call the same runtime catalog as other MCP clients. See the core tool examples in the Claude Code guide, and use MCP tools/list for the canonical catalog.

Tools most relevant to Codex task execution:

  • phantom_status — check vault state before a task starts
  • phantom_list_secrets — let Codex know which secrets exist without exposing values
  • phantom_add_secret_interactive — return the terminal command to enter a secret out-of-band; useful when Codex identifies a missing key mid-task
  • phantom_check — scan .env or runtime environment for unprotected secrets
  • phantom_doctor — validate the full setup; Codex can call this as a pre-task health check

Codex cannot retrieve real secret values through MCP. phantom_list_secrets returns names only, and there is no tool that returns a plaintext credential.

Daily flow

# Run a Codex task with the proxy active
phantom exec -- codex "integrate the Resend email API"

# Codex discovers RESEND_API_KEY is missing — add it out-of-band
phantom add RESEND_API_KEY
# enter value at the terminal prompt

# Re-run the task; the proxy injects the key for any test calls
phantom exec -- codex "finish the Resend integration"

# After separately verified hosted commissioning and entitlement, request an
# encrypted cloud push. The public hosted service is not currently commissioned.
phantom cloud push

Codex writes code that references process.env.RESEND_API_KEY (or equivalent). Under phantom exec, that variable holds a fresh-session phm_... token. For a supported HTTP SDK route, the local proxy discards client control of the route auth header and injects its configured vault value when Codex makes a test call. The generated environment-variable lookup can remain unchanged, but the production runtime must be provisioned separately with the corresponding credential or an approved secret-manager integration. Phantom's local proxy does not deploy or authorize production credentials.

Troubleshooting

Codex does not list Phantom in its available tools

First confirm that the installed runtime responds, then preview only the Phantom entry that setup would generate:

phantom --version
phantom setup --client codex --print

The preview does not inspect your existing Codex configuration. In your local editor, locate only [mcp_servers.phantom] in ~/.codex/config.toml and compare its command and args with the preview. Do not paste or print the whole config: other server entries can contain credentials or private service configuration. If the Phantom entry is absent or stale, re-run phantom setup --client codex, which merges that entry, then restart Codex. A generated entry alone does not prove that the client connected; confirm Phantom's tools appear in Codex.

To test the installed CLI and both MCP launch paths independently of your project and client configuration, run the disposable runtime smoke example from a Phantom source checkout. It reports missing prerequisites as skipped and does not read a real vault or contact a provider.

Phantom proxy not active during Codex task execution

Codex tasks must be launched from a shell where phantom exec set the proxy environment or where you explicitly copied the exports printed by an active foreground phantom start. Launching Codex from a GUI shortcut or an unrelated terminal bypasses the proxy. Prefer phantom exec -- codex <task>.

Supported API call is not receiving route-owned authentication

The proxy only injects authentication for requests sent to URLs that match configured service mappings (OPENAI_BASE_URL, ANTHROPIC_BASE_URL, etc.). If your code uses a hardcoded URL rather than the *_BASE_URL environment variable, it bypasses the proxy. Check phantom status to see which service URLs are rewritten, and update your code to use the env var.

Reference