# 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.9` binary using the platform-specific, checksum-
verified path in [getting started](./getting-started.md#install), then run
`phantom init` in the project.

### Step 2: wire up Codex (one command)

```bash
phantom setup --client codex
```

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

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

Install both `v0.7.9` release binaries before setup. Version `0.7.9` 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:

```bash
phantom setup --client codex --print
```

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

### Step 3: verify agent readiness

```bash
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

```bash
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](./claude-code.md#core-mcp-tools-claude-can-use), 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

```bash
# 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:

```bash
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](../examples/agent-first-five-minutes/README.md)
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

- Full setup guide: [getting-started.md](./getting-started.md)
- Troubleshooting: [troubleshooting.md](./troubleshooting.md)
- Sync to Vercel / Railway: [sync.md](./sync.md)
- Cloud login: [login.md](./login.md)
- Site: [https://phm.dev](https://phm.dev)