Phantom Secrets: A Local Proxy and MCP Server That Keep Real Secrets Hidden from AI Coding Agents

Who It's For

If you've wired an AI coding agent into your day-to-day development and your project's .env holds real secrets, then logs, error echoes, and context snippets can all become paths for secrets to leak. Phantom fits people who need a hard boundary between “the app still gets the real values” and “the agent never sees the secret values” — as well as teams that want to distribute and rotate secrets centrally without pushing them down into every individual's toolchain.

Its shape is “local proxy + MCP server”: project secrets are replaced with scoped phm_ placeholders, the app fetches the real values through an authenticated local proxy, and the agent side only touches value-blind MCP tools used for inventory, diagnostics, and controlled requests. The premise is that you're willing to keep a proxy process running on your own machine and to bring the .env rewrite under your own version control process — that step isn't something you can casually skip.

Three Minutes to Your First Attempt

The recommended official path is Homebrew. The macOS install the repository gives is a three-step chain: tap first, then trust, then install; what you get are two executables, phantom and phantom-mcp, matching the v0.7.9 version the repository tags.

brew tap ashlrai/phantom
brew trust --formula ashlrai/phantom/phantom
brew install ashlrai/phantom/phantom

Prerequisites: Homebrew must already be installed on macOS. If you skip Homebrew and build from source instead, the repository pins the compiler toolchain version, so your build environment needs the matching Rust toolchain.

Next come two configuration steps, in order. First change into the project directory and run phantom init; note that this is a write operation — it rewrites that project's .env, swapping the real key values for phm_ placeholders. The checkpoint is to confirm before running that .env is backed up or committed, and to check in the command output that the number of replacements matches what you expected. The second step writes the configuration per client:

phantom init
phantom setup --client claude

After that, use the read-only step for a low-risk check: phantom list shows your secret inventory without displaying any values. The observable success signal is that the terminal lists entry names with no real secret characters after any of them; then have the agent read the repository once more and it gets things starting with phm_ instead of the real values.

For the complete command and parameter reference, see the official repository https://github.com/ashlrai/phantom-secrets

Use Cases

Case one: give the agent a channel where it can see the inventory but not the values. The MCP tools on the agent side are value-blind and cover three uses: inventory, diagnostics, and controlled requests; the repository positions these tools as capability, status, and repository-state checks that trigger no provider-side actions. So you can safely let the agent answer “which secrets does this project configure, is the current path working, and which files in the repository reference placeholders” — the agent neither echoes secret values back nor casually changes cloud resources while checking.

Case two: let business code keep running against the real values while keeping those values out of the agent's line of sight. The substitution happens at initialization time: the real key values in .env become scoped phm_ placeholders, the app reads environment variables as usual, and the requests it sends are taken over by the local proxy, which retrieves the real values after authentication. The controlled-request entry point on the proxy side shares the same “no values” constraint as the inventory and diagnostics entry points, so the app runs fine while the agent still cannot get the secrets themselves. Note that the repository material only says the proxy is an “authenticated” local proxy and does not spell out the specific form of authentication; for that layer, go by the repository's description.

Boundaries of Use

First, phantom init rewrites .env — it's a genuine write operation. Back up or commit before you run it, and don't paste the before/after diff straight into a public channel.

Second, the value-blind nature of the agent-side tools only guarantees “can't see values,” not “can do anything.” The repository positions them as capability, status, and repository-state checks, and they don't issue provider actions on your behalf; the actual cloud calls happen on the request path the app sends through the local proxy, so when debugging you need to tell those two segments apart.

Third, it is not a zero-risk tool: it has to read the local .env and the client configuration files, and the local proxy sends requests to third-party providers, so secrets still flow between your machine and that provider. Whether you accept that path depends on whether your organization allows it to exist on the agent side.

Fourth, the installation methods and command descriptions in the repository change with each version, so check back against the official repository before upgrading.