trackmcp
Back to directory
ashlrai

phantom-secrets

View on GitHub

Stop AI coding agents from leaking your API keys. Local proxy + MCP that swaps real secrets for phm_ tokens — works with Claude Code, Cursor, Windsurf, and Codex.

16 stars RustOthers Updated Sep 3, 2026
ai-safetyapi-keysclaude-codeclideveloper-toolsenv-filesmcprustsecrets-managementsecurityaicursorencryptionmcp-serverproxyapi-securitycodexphantomtoken-proxywindsurf

Documentation


> **▶ Historical v0.4 demo — current behavior differs**  · 

> **🛡 Security model**  · 

> **📋 Threat model**  · 

> **💬 Discussions**

> [!IMPORTANT]

> Release-state snapshot (verified 2026-09-03): `v0.7.5` is the reviewed

> immutable GitHub release at source commit

> `d2969e73995cc139e6253e0c8a70f1d683f88e20`. Its 19-asset release set,

> checksums, archive-specific SPDX SBOMs, GitHub provenance and SBOM

> attestations, and all six native release rows were verified in workflow

> 33709338577.

> Homebrew publishes the same reviewed `v0.7.5`; npm `latest` remains `0.6.0`, and the npm

> `0.7.4` wrappers remain quarantined under `release-candidate` after failed

> npm-channel acceptance. The GitHub receipt alone does not prove the separately

> verified Homebrew formula, an npm or crates.io package, MCP Registry entry, hosted-service

> commissioning, provider activation, signing/notarization, certification, or

> customer acceptance. See

> release readiness and

> platform support.

Start here

Choose the smallest path that answers your next question. The first path uses

no credential, makes no network request, and does not install or configure

Phantom.

GoalStartWhat it establishes
See the delegation boundary with no secret or setupRun `node examples/first-five-minutes/run.mjs`, then read the first-five-minutes walkthroughA deterministic, read-only example contract; not vault, proxy, provider, or deployment acceptance.
Protect a real local projectFollow Quick Start with the reviewed `v0.7.5` GitHub releaseLocal initialization and diagnostics on your machine.
Connect an AI coding clientComplete the first MCP taskValue-blind capability, status, and repository checks; no provider action.
Define a bounded task for an agentUse the safe delegation quickstartA reviewable task contract with explicit authority and acceptance boundaries.
Evaluate a team rolloutUse the enterprise adoption guideA controlled evaluation plan; not a claim of commissioned cloud or enterprise service.
Audit the trust model firstRead the security model and threat modelDocumented controls, assumptions, and residual risks.

Why Phantom?

AI coding agents routinely work in repositories that also contain local credentials. Once a real API key enters an agent context, transcript, tool call, or generated file, you have lost control of where that value may persist.

Traditional secrets managers focus on keys *at rest* and *in transit*. Phantom adds a boundary for agent context:

  • 🔒 Reduces one credential-exposure path — managed project dotenv files contain sensitive `phm_` mappings, MCP responses remain value-blind, and exact proxy routes inject their own configured authentication values. Unmanaged files, broader shell authority, and same-user processes remain in the threat model.
  • Fast local setup — after installing the reviewed `v0.7.5` GitHub release, `phantom init` protects a project without requiring an account, DNS changes, or a custom CA.
  • 🧰 Agent-native integrations — setup helpers and value-blind MCP workflows for Claude Code, Cursor, Windsurf, and Codex, plus project instructions for GitHub Copilot.
  • 🦀 Open source, local-first, MIT — secrets use the native OS credential store when it is available, with an explicit encrypted-file fallback. Optional cloud sync encrypts vault payloads client-side before the server stores them.

Project status and trust boundary

Phantom's implemented user-facing surfaces are the CLI, vault, authenticated local proxy, MCP server, and optional cloud/team workflows documented below. Cloud and team behavior additionally depends on the deployed service, account plan, and provider configuration; source code alone is not deployment or customer-acceptance evidence. The conversation facade is intentionally narrow:

  • `phantom_do` is proposal-only. It canonicalizes a closed Cargo action and reports its digest, effect, and activation blockers; `execute` is hard denied.
  • `phantom_setup_workspace` can propose setup, create a bearerless request, and report authenticated status. Applying a request remains a separate trusted-terminal operation.
  • Advanced MCP tools remain a compatibility catalog, disabled by default, with separate explicit confirmation and informed terminal-approval gates. They are not governed by the conversation facade's capability card.
  • `phantom grant` retains value-blind lifecycle metadata and design-source foundations, but 0.7.5 hard-denies every live provider issuance/renewal path before credential or network access. A provider grant is not an execution-kernel authority grant, broker lease, or permission for an agent to execute work.
  • The authority, broker, runtime, session, and evidence crates are inactive, fail-closed foundations. They do not establish live Locus authority, broker credentials, execute agent actions, or produce externally trusted receipts today.

See the documentation map, architecture,

security policy, and threat model for the

evidence behind those boundaries.

Quick Start

Install both binaries from the reviewed `v0.7.5` GitHub release.

The Homebrew formula publishes the same reviewed `v0.7.5` binaries:

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

For exact `v0.7.5` on macOS, Linux, or Windows, use the matching release asset

in Installation. Then protect and verify the project:

bash
$ phantom init
# Auto-detects .env, .env.local, or .env in subdirectories
# Stores real secrets in the native credential store or encrypted vault,
# then rewrites .env with phantom tokens
# Auto-configures Claude Code MCP server if detected

$ phantom agent doctor
# One human-readable readiness check for AI-agent safety

$ phantom exec -- claude
# Authenticated proxy running on an ephemeral 127.0.0.1 port
# App/test processes use phantom tokens; agents use value-blind metadata

For a task contract you can hand to Claude Code, Codex, Cursor, Windsurf, or

Copilot, use the safe delegation quickstart and

the copyable policy and task templates.

Teams evaluating a controlled rollout can start with the

enterprise adoption guide.

Windows

The same core command surface is implemented for native Windows, with remaining

native acceptance limits tracked in the platform matrix. Install the exact `v0.7.5`

Windows ZIP for your architecture from Installation, verify its

published `.sha256` sidecar, and place both executables on `PATH`. WSL is a

separate Linux environment with its own filesystem and credential-store context.

For an explicitly supervised foreground proxy, run `phantom start` with stdin,

stdout, and stderr each attached to a trusted terminal. Terminal attachment is

an admission check, not proof of who controls a PTY. The CLI detects your shell and prints the matching env-var syntax;

copy those exports into the terminal that launches the client, keep the owning

terminal open, and press Ctrl-C there to stop. Detached `--daemon` mode and

external process control are fail-closed until Phantom has a separately reviewed

private cross-platform control channel. `phantom stop` only authenticates a

legacy v0.7.3 `.phantom.pid` session to report migration guidance; v0.7.3 had no

authenticated shutdown endpoint, so the new binary never kills that process or

deletes its record. Stop it from its owning v0.7.3 terminal with Ctrl-C, or use

the bounded recovery procedure in Troubleshooting.

For reference:

PowerShell:

powershell
$env:OPENAI_BASE_URL = "http://127.0.0.1:PORT/openai/_phantom/TOKEN/"
$env:PHANTOM_PROXY_PORT = "PORT"
$env:PHANTOM_PROXY_TOKEN = "TOKEN"

cmd.exe:

cmd
set OPENAI_BASE_URL=http://127.0.0.1:PORT/openai/_phantom/TOKEN/
set PHANTOM_PROXY_PORT=PORT
set PHANTOM_PROXY_TOKEN=TOKEN

Git Bash / WSL: use the `export X=Y` syntax from the main quick-start.

Notes:

  • `PHANTOM_PROXY_TOKEN` is the proxy session authenticator. By default, `phantom exec` and `phantom start` include it in local `*_BASE_URL` values as `/_phantom/TOKEN/` so unmodified SDKs work. Header-aware clients can set `PHANTOM_PROXY_HEADER_AUTH_ONLY=1` and send `x-phantom-proxy-token: $PHANTOM_PROXY_TOKEN` instead.
  • If `phantom.exe` is blocked by Windows application-control policy, do not automatically remove Mark-of-the-Web. First verify the archive checksum and both binary identities against the release metadata. If local policy permits the verified binaries, a user may then remove the mark explicitly with PowerShell: `Get-ChildItem "$env:USERPROFILE\.phantom-secrets\bin\*.exe" | Unblock-File`.
  • The pre-commit hook installed by `phantom init` is a `#!/bin/sh` script. Native git from the command line invokes it via Git for Windows' bundled `sh.exe`, which is what the official Git for Windows installer ships. GUI clients (GitHub Desktop, some IDE integrations) may run with a stripped-down `PATH` that lacks `sh.exe` and silently skip the hook — for these, run commits from a terminal, or use `phantom check --staged` directly. CI is the durable safety net regardless.
  • The immutable `v0.7.5` release contains x64 and ARM64 Windows ZIPs, and both native Windows rows passed the tag-bound release acceptance workflow. The archives are not Authenticode-signed; this receipt does not prove every enterprise application-control policy will accept them. See the platform support matrix.

How It Works

code
.env file (AI read denied)       OS Keychain / Vault
  +--------------------------+      +---------------------+
  | OPENAI_API_KEY=phm_a7f3  | ---> | sk-real-secret-key  |
  | STRIPE_KEY=phm_c9d1...   |      | sk_live_real-key... |
  +--------------------------+      +---------------------+
           |                                 |
           v                                 v
  App / test process                Phantom Proxy (127.0.0.1)
  +--------------------------+      +------------------------------+
  | Loads phm_ tokens        |      | Intercepts HTTP requests     |
  | Agent gets MCP metadata  | ---> | Injects route-owned auth key |
  | Makes API calls to proxy |      | Forwards over TLS to real API|
  +--------------------------+      +------------------------------+

1. `phantom init` reads `.env`, stores real secrets in the native OS credential store or encrypted-file fallback, and rewrites `.env` with `phm_` tokens

2. `phantom exec -- claude` starts a local reverse proxy, sets SDK-compatible service base URLs such as `OPENAI_BASE_URL=http://127.0.0.1:PORT/openai/_phantom/TOKEN/`, exposes `PHANTOM_PROXY_TOKEN` to the child process, and launches the command

3. API calls hit the proxy, which authenticates the local session, removes its local auth token, injects only the matched route's vault value into that route's exact configured authentication header, and forwards over TLS. Client-controlled headers and bodies never resolve `phm_` tokens.

4. When the session ends, the proxy shuts down and its bearer is invalid. `phantom exec` also replaces project tokens with fresh child-process tokens for that run. Project `phm_` values persist until rotation; they are not provider credentials and are never client-resolved, but a process controlling an authenticated active proxy can still invoke its configured provider routes.

Phantom does not grant AI tools permission to read `.env` or other dotenv files. `phantom setup` removes legacy Phantom-managed dotenv read grants and preserves deny rules; agents use value-blind MCP inventory instead.

Provider grants

`phantom grant` retains value-blind lifecycle metadata and provider protocol

design foundations. In 0.7.5, all live provider issuance, enrollment exchange,

refresh, renewal, and revocation execution is hard-denied before Phantom reads a

provider credential or opens a provider network connection. Do not use grant or

rotation commands expecting a vendor-side change. Test-only mocks demonstrate

local transaction behavior only; they are not live-provider acceptance.

In these docs, provider grant means design-era credential lifecycle metadata;

no live grant flow runs in 0.7.5. Authority grant means the inactive, value-free execution

authority type in `phantom-authority`. A provider grant cannot be reinterpreted

as an authority grant, Locus credential, broker lease, or execution permit. See

the design-era grant lifecycle specification; the

issuance contract is the original design contract and

retains design-era status language.

MCP Integration (Claude Code, Cursor, Windsurf, Codex)

Phantom ships an MCP server so AI coding tools can inspect value-blind metadata

and request gated lifecycle operations. MCP responses do not return real secret

values.

First MCP task: verify the boundary

Use this read-only path before exploring the full tool catalog:

1. Install both binaries from the reviewed `v0.7.5` GitHub release.

2. From the project you want to inspect, run `phantom setup --client codex`,

replacing `codex` with `claude`, `cursor`, or `windsurf` when appropriate.

3. Restart the AI client so it loads the generated MCP configuration.

4. Ask the client: “Call `phantom_capability`, then `phantom_status`. Report the

value-blind authority, hard denials, vault backend, secret count, and service

mappings. Do not request or reveal secret values.”

5. Ask the client: “Call `phantom_check` with `staged: false`. Report findings

without changing files or credentials.”

These calls inspect the configured local surface. They do not prove that cloud,

team, deployment, provider, authority-kernel, or customer workflows are active

or accepted.

  • Conversation facade — `phantom_capability` reports authority and hard denials for the small facade (not the separately gated advanced compatibility catalog); `phantom_do` canonicalizes one closed Cargo action and reports the exact activation blockers without executing it; `phantom_setup_workspace` proposes an exact value-blind plan, creates a bearerless apply request after revalidation, or reads authenticated request status. Provisioning the machine-local seal key and creating a request both require `confirm` plus an out-of-band approval token; MCP never claims or applies the request.
  • Vault — `phantom_list_secrets`, `phantom_status`, `phantom_init`, `phantom_add_secret_interactive`, `phantom_add_secret` (deprecated; refuses plaintext), `phantom_remove_secret`, `phantom_rotate`, `phantom_copy_secret`
  • Detection + diagnostics — `phantom_doctor`, `phantom_why`, `phantom_check`, `phantom_env`, `phantom_validate_secret`, `phantom_validate_all`
  • Local-to-cloud — `phantom_wrap`, `phantom_unwrap`, `phantom_sync`, `phantom_cloud_push`, `phantom_cloud_pull`, `phantom_cloud_status`
  • Teams — `phantom_team_list`, `phantom_team_create`, `phantom_team_members`, `phantom_team_invite`, `phantom_team_key_publish`, `phantom_team_vault_push`, `phantom_team_vault_pull`
  • Advanced audit, rotation, expiry, and compliance — `phantom_audit_recent`, `phantom_audit_stats`, `phantom_audit_analytics`, `phantom_audit_anomalies`, `phantom_audit_anomalies_realtime`, `phantom_audit_hotspot_alerts`, `phantom_audit_incidents`, `phantom_leak_incidents_realtime`, `phantom_audit_alerts`, `phantom_audit_export_report`, `phantom_compliance_status`, `phantom_rotate_with_candidate`, `phantom_rotate_promote`, `phantom_rotate_provider`, `phantom_rotate_with_expiry`, `phantom_list_with_expiry`, `phantom_secret_rotation_due`, `phantom_validation_schedule`, `phantom_validation_history`, `phantom_secrets_expiry_check`, `phantom_secrets_auto_rotate`, `phantom_expiry_enforce`, `phantom_rotation_schedule_next`, `phantom_apply_expiry_policy`

`phantom_secrets_auto_rotate` and `phantom_rotate_with_expiry` are deprecated

compatibility names for approved local `phm_` token remaps. They do not rotate

a provider credential, renew TTL/`rotated_at` metadata, clear leak incidents,

or sync credentials. `phantom_rotate_provider` is also hard-denied before

credential or network access in 0.7.5. Team invites may assign only `member` or `admin`; ownership transfer

is not an invite role.

Tools that write state, retrieve or use credentials, or make provider/network

requests are disabled by default. They can reach their `confirm: true` and

one-use `approval_token` gates only when the operator sets

`PHANTOM_MCP_EFFECTS=trusted-terminal` in a server environment outside agent

authority. `phantom mcp-approve` requires attached stdin/stderr, shows the

bounded value-blind effect plus exact parameters, and requires a fresh typed

challenge before approval. A same-user shell or agent-controlled PTY can

defeat that ceremony; leave effects disabled unless the approval command and

`~/.phantom` approval storage are outside the requesting agent's authority.

Conditional tools keep

their inspection mode ungated and activate both gates only for the effectful

parameters. Real secret values are never accepted as MCP tool arguments; new

secrets are entered out-of-band in a trusted terminal. The exact 54-tool names,

descriptions, and JSON schemas are mirrored from runtime `tools/list` into

`mcp-registry/server.json`, and release smoke tests

reject any drift.

`phantom_rotate_with_candidate` and `phantom_rotate_promote` remain in the

54-tool compatibility catalog as deprecated hard denials. They never create,

validate, or promote a candidate and never change vault or shadow metadata;

`phantom_rotate_provider` is also hard-denied before credential or network

access in 0.7.5. `phantom add` creates new names only and refuses existing-name

replacement before reading a value. Replacing a credential therefore requires

a separately reviewed provider rotation plus an explicit trusted-terminal

remove-and-add sequence; those are distinct, non-atomic operations.

Workspace setup is deliberately split across trust boundaries. MCP can call

`phantom_setup_workspace` with `phase=propose`, then `phase=request_apply` using

the exact returned `plan_id` and `pre_state_id`. The first proposal requires

dual approval only when it must provision the machine-local plan-seal key;

`request_apply` always requires dual approval because it persists a value-free

request outside the repository. Apply it from an attached trusted terminal

with `phantom workspace apply --request `; MCP has no claim or apply

operation.

One command per AI client — Phantom writes the right config file in the right place:

bash
phantom setup --client claude     # .claude/settings.local.json (project)
phantom setup --client cursor     # ~/.cursor/mcp.json
phantom setup --client windsurf   # ~/.codeium/windsurf/mcp_config.json
phantom setup --client codex      # ~/.codex/config.toml
phantom setup --client claude --print   # snippet to stdout for any other client

Install both `v0.7.5` release binaries before setup. Version `0.7.5` records the

running `phantom` executable with `mcp serve` when it can resolve that executable,

otherwise it looks for a local standalone `phantom-mcp`. Setup has no network

package-runner fallback and fails closed when neither local runtime is

executable. Inspect the generated entry, then restart the AI tool so it picks up

the new config.

Phantom's stdio MCP server can be configured in MCP clients that support local

command servers. The setup writer currently has reviewed presets for Claude

Code, Cursor, Windsurf, and Codex; other clients require their own compatible

configuration.

Cloud backup + Dashboard

Back up and restore a vault on the same keychain machine with client-side

encryption. Phantom Cloud receives the encrypted vault payload rather than the

decrypted secret values; endpoint, client, account, and OS-keychain security

remain part of the trust boundary. The cloud encryption key is generated and

stored in the local OS keychain. Phantom does not currently ship key transfer or

recovery, so account sign-in without that key cannot decrypt this backup.

Login, logout, cloud push/pull, and browser open are not headless agent actions:

run them with stdin, stdout, and stderr attached to a terminal outside the

requesting agent's authority and complete each fresh exact typed challenge.

The public hosted service is not currently commissioned for authenticated

cloud or dashboard use. The commands below document the source-backed flow for

a future verified deployment and entitled account; they are not a live-service

acceptance receipt.

bash
$ phantom login
# Opens GitHub OAuth (device code flow)

$ phantom cloud push
# After commissioning: encrypted client-side and uploaded to the configured service

$ phantom cloud pull   # restore on the machine that holds the original cloud key
# Downloaded and decrypted locally

$ phantom open
# After commissioning: opens the configured read-only dashboard.

Cloud backup uses ChaCha20-Poly1305 with a random client-side passphrase stored

in the OS keychain and derived via Argon2id for encryption. The server stores

only ciphertext. Team vaults are separate: they wrap a shared vault key to each

registered member's X25519 public key; that does not make personal cloud backups

portable.

Team vaults (source-backed pilot)

The repository includes fixed-membership team-vault workflows intended for a

planned hosted Pro pilot. Pilot eligibility, team and vault limits, and pricing

are TBD; no self-serve checkout is commissioned. The

service path stores ciphertext plus per-member encrypted key shares. Team roles

gate invitation management, but all members can read and write the shared vault;

member removal and atomic offboarding rotation are not shipped. Treat this as a

pilot capability until the hosted service and account entitlement are commissioned.

CLI team mutations require the same attached trusted-terminal ceremony before

credential, keypair, vault-value, or network access. MCP team reads and writes

are provider requests and remain disabled by default behind `confirm` plus a

one-use out-of-band approval token.

bash
$ phantom team create "engineering"
# Creates a team; you become the owner.

$ phantom team invite  
# Invites by GitHub login.

$ phantom team key-publish 
# Registers your X25519 public key on the team.
# (Run once per team; the private key stays in the OS keychain.)

$ phantom team vault-push 
# Encrypts the current project's vault with a fresh symmetric key,
# wraps that key (X25519 + ChaCha20-Poly1305) for every member that
# has a registered public key, then uploads.

$ phantom team vault-pull    # on a teammate's machine
# Pulls, decrypts the per-member share with their private key,
# decrypts the vault, writes secrets locally.

After a hosted deployment is commissioned and accepted, its read-only team

dashboard is designed to show team memberships and member lists.

Command Reference

CommandDescription
`phantom init`Import `.env` secrets into vault and rewrite with phantom tokens. Use `--empty` to initialize a new project before its first `phantom add`; `add` does not auto-create project state. `--all ` processes eligible repositories found by the bounded five-level scan; discovery stops below the first matching repository. Use `--dry-run` to inspect the exact set and `--jobs N` / `-j N` to control parallelism.
`phantom exec -- `Start an authenticated proxy and run a command with secret injection
`phantom start`Run an explicitly supervised foreground proxy; keep its trusted terminal open and press Ctrl-C there to stop
`phantom start --daemon` / `phantom stop`Detached start fails closed; stop is a TTY-only legacy-state diagnostic that never kills or deletes, not current process control
`phantom list`Show secret names stored in vault (never values; `--json` for machine-readable output)
`phantom add `Create a new secret name transactionally in an initialized project through a hidden terminal prompt or trusted `--stdin` producer; existing names are denied before any value read and are never replaced
`phantom remove `After exact trusted-terminal confirmation, transactionally remove the vault value, lifecycle config, and exact managed-dotenv mapping; headless use fails before value access or mutation
`phantom reveal `From an attached trusted terminal, review and type the exact challenge before printing one value or copying it for an auto-cleared 30-second clipboard window
`phantom status`Show vault/mapping state and whether the machine-local lifecycle lock is held; a held lock does not authenticate or identify a listener
`phantom rotate`After an exact attached-terminal challenge bound to the project, config, managed dotenv, and sorted protected-name digest, regenerate every local phantom token (old mappings become invalid). Headless use fails before vault access or mutation. Provider-backed `--name`/`--provider` execution is hard-denied before credential or network access in 0.7.5.
`phantom grant add `Reserved provider-enrollment surface; hard-denied before credential or network access in 0.7.5. See Provider grants.
`phantom grant list` / `status`Read provider-grant names, providers, lifecycle state, and expiry metadata without returning credential values.
`phantom grant revoke `Reserved remote-revocation surface; currently fails closed before local mutation because provider revocation is not wired.
`phantom doctor`Check configuration and vault health (`--fix` to auto-repair). Reports install source, vault backend, audit-log status, Argon2 params, and MCP wiring per client
`phantom agent report`Emit a read-only AI-agent readiness report (`--json` for automation). Reports `unsafe`, `protected`, `verified`, `team-ready`, or `compliance-ready`
`phantom agent doctor`Human-readable agent readiness view backed by the same policy engine
`phantom agent setup`Preview or apply safe defaults for agent use (`--dry-run` first, `--apply` to write changes)
`phantom workspace plan [--json]`Build an exact sealed setup plan and create a value-free pending request; does not change the workspace or vault
`phantom workspace apply --request `Recompute and claim the exact request in an attached trusted terminal, require typed confirmation, then apply transactionally with rollback on failure
`phantom workspace status --request [--json]`Read authenticated, value-free request state
`phantom check`Scan for unprotected secrets (pre-commit hook, `--staged`, `--runtime`)
`phantom sync`Push secrets to Vercel / Railway (`--dry-run --json` previews safely; `--only PATTERN` filters by glob, repeatable)
`phantom pull`Pull secrets from Vercel / Railway into vault
`phantom setup`Wire Phantom into an AI client. `--client claude` (default), `cursor`, `windsurf`, or `codex`. Add `--print` to emit the config snippet to stdout
`phantom env`Generate `.env.example` for team onboarding
`phantom export`From an attached trusted terminal, review an exact value-blind plan, type its fresh challenge, and enter a dedicated passphrase through the hidden prompt. Export `--passphrase-file`, plaintext export, argv passphrases, existing targets, symlinks, and paths outside the project fail closed.
`phantom import`From an attached trusted terminal, review and type the exact source/target/name/overwrite challenge before restoring a backup or importing Doppler, Infisical, dotenvx, 1Password, or env data. `--force` selects the reviewed overwrite set but never bypasses consent. A bounded private passphrase file is accepted only on non-Windows platforms and still requires the terminal ceremony.
`phantom audit show`Print recent audit events (`--last N`, `--op OP`, `--name NAME`, `--json`). Requires `PHANTOM_AUDIT=1`
`phantom audit tail`Follow the audit log live (`--op`, `--name` filters)
`phantom audit path`Print the absolute path to the audit log file
`phantom audit verify`Verify HMAC-SHA256 chain integrity; exits 1 if tampering detected
`phantom login`From an attached trusted terminal, approve an exact network plan, then separately approve browser opening/polling and keychain persistence
`phantom logout`From an attached trusted terminal, approve deletion of persistent cloud authorization from the OS keychain
`phantom cloud push`After exact trusted-terminal confirmation, push a client-encrypted vault. A remote success followed by local reconciliation failure is partial success and must not be retried automatically.
`phantom cloud pull`After exact trusted-terminal confirmation, pull and decrypt a vault. With `force=false`, skipped existing entries preserve the prior merge base and block later push until a fully reconciled approved pull.
`phantom cloud status`Authenticated provider read; requires attached trusted terminals and an exact challenge before stored-bearer or network access
`phantom wrap`Wrap package.json scripts with `phantom exec` automatically
`phantom unwrap`Restore original package.json scripts
`phantom watch`Watch managed dotenv files and report new unprotected secrets. `--auto` hard-denies before mutation in 0.7.5; use transactional `phantom init`.
`phantom why `Explain why a key is or is not protected
`phantom copy `Copy a secret to an initialized target after exact trusted-terminal confirmation; refuses existing target vault, config, or managed-dotenv ownership rather than overwriting
`phantom team list/members`Authenticated, value-blind provider reads. CLI requires attached trusted terminals and an exact challenge before bearer/network access; MCP requires `confirm` plus out-of-band approval.
`phantom team create/invite/key-publish/vault-push/vault-pull/rotate-vault`Run CLI team effects only from an attached trusted terminal and complete the exact challenge before credential, keypair, vault-value, or network access. Invites assign only `member` or `admin`.
`phantom validate` / `--watch`Send selected credentials to configured validators only after exact trusted-terminal consent; watch authorization ends when config or the vault name set changes
`phantom validate schedule`Read status without mutation; setting or disabling persistent scheduler policy requires attached terminals and an exact typed challenge
`phantom expiry set`Persist lifecycle policy only after attached-terminal confirmation; `expiry enforce` is read-only, while `expiry rotate` is only a deprecated local token remap
`phantom open [page]`From an attached trusted terminal, open only the reviewed aliases `dashboard`, `billing`, `team`, `docs`, `pricing`, `github`, `issues`, or `site`; arbitrary URLs, paths, and unknown aliases are rejected
`phantom upgrade``--check-only` performs a read-only version lookup only for an eligible standalone install. Live standalone replacement requires attached terminals and two exact challenges; managed installs route to their owner, ambiguous installs fail closed, and `--force` is rejected.
`phantom completion `Print a shell-completion script (bash, zsh, fish, powershell, elvish)

Rotating real provider credentials

Phantom 0.7.5 does not execute live provider issuance or rotation. Every

provider path—single-provider CLI, batch CLI, MCP, grant enrollment, additive

issuance, and destructive/rolling refresh—is hard-denied before provider

credential access and before network I/O. Operators must rotate at the vendor,

then use Phantom's trusted local secret-entry path. Source adapters and exact

`cfg(test)` mocks are transaction-design evidence, not provider activation,

commissioning, or acceptance.

Provider support matrix

ProviderSupportNotes
`vercel`Hard deniedAdditive issuance can orphan a live successor after a local failure; no provider call in 0.7.5
`google`Hard deniedSecret Manager version creation remains disabled pending durable successor recovery and verified abort
`github`Hard deniedGitHub App installation-token issuance remains disabled pending the same recovery contract
`stripe`Hard deniedRaw keys are manual; rolling OAuth refresh can invalidate the predecessor before successor recovery
`aws`Hard deniedSigV4 access-key-pair rotation is not implemented
`sentry`Hard deniedInstallation-token issuance remains disabled pending durable successor recovery
`supabase`Hard deniedPAT rotation is manual; OAuth/additive issuance paths are not commissioned

`phantom rotate --batch` remains metadata-only discovery/manual guidance and

fails closed before vendor execution. No single-provider exception exists.

Features

  • Encrypted vault -- macOS Keychain, Linux Secret Service, or Windows Credential Manager, with a ChaCha20-Poly1305 encrypted-file fallback for CI and headless environments. Phantom does not claim Secure Enclave hardware binding. Argon2id uses m=64 MiB, t=3, p=1.
  • Phantom tokens -- 256-bit CSPRNG `phm_` placeholders in `.env`, rotatable on demand
  • Authenticated proxy sessions -- each proxy run generates a fresh `PHANTOM_PROXY_TOKEN`; CLI-generated SDK URLs include it for compatibility, and header-aware clients can opt into `x-phantom-proxy-token` with `PHANTOM_PROXY_HEADER_AUTH_ONLY=1`
  • Route-owned credential injection -- Client headers and bodies never resolve `phm_` tokens. After authenticating and matching an exact built-in route, the proxy injects that route's configured vault secret only into its fixed authentication header; a missing mapping fails before any upstream call. Request bodies are still collected under a hard byte cap before forwarding.
  • Full SSE/streaming support -- Response streaming preserved end-to-end for OpenAI, Anthropic, and other streaming APIs
  • Smart detection -- Heuristic engine distinguishes secrets (`*_KEY`, `*_TOKEN`, `sk-*`, `ghp_*`) from config (`NODE_ENV`, `PORT`)
  • Platform sync -- Push/pull secrets to Vercel and Railway
  • Pre-commit hook -- Runs `phantom check --staged` when Git invokes the hook; it checks staged dotenv content plus a bounded set of hardcoded-key prefixes. Hooks can be bypassed or skipped, so CI and a broader secret scanner remain necessary.
  • MCP server -- value-blind vault, diagnostics, cloud, team, audit, rotation, validation, expiry, and compliance responses for Claude Code, Cursor, Windsurf, and Codex; effectful compatibility tools remain separately gated and disabled by default
  • Cloud backup -- client-encrypted same-keychain-machine backup and restore; key transfer and recovery are not shipped, and deployed-service and account configuration remain separate operational gates
  • Export/import -- Encrypted export requires an attached terminal, exact challenge, and hidden passphrase; export passphrase files, plaintext, and argv passphrases are disabled. Import uses its own exact terminal ceremony; only non-Windows encrypted-backup import may read a bounded private passphrase file. Competitor imports support Doppler, Infisical, dotenvx, 1Password, and plain `.env`.
  • Tamper-evident audit log -- `PHANTOM_AUDIT=1` writes vault events as JSONL to `~/.phantom/audit.log`. Each entry is chained with HMAC-SHA256; `phantom audit verify` detects tampering. `phantom audit show/tail/path` for log access.
  • Response scrubbing -- Scrubs configured secret values from supported API response paths before returning data to the caller
  • Script wrapping -- `phantom wrap` wraps selected runtime/build scripts (`dev`, `start`, `serve`, `build`, `deploy`, `preview`) and deliberately leaves test, lint, type, and format scripts alone
  • Watch mode -- `phantom watch` reports new unprotected secrets; legacy `--auto` hard-denies before mutation, so protection stays a reviewed transactional `phantom init`
  • Multi-project scanner -- `phantom init --all ` processes eligible repositories found within a five-level bounded scan and stops below the first matching repository; use `--dry-run` to verify the exact set and `--jobs N` to control parallelism
  • Multi-IDE setup -- `phantom setup --client claude|cursor|windsurf|codex` writes the right MCP config for each AI tool, or `--print` for a generic snippet
  • Agent readiness -- `phantom agent doctor` and `phantom agent report --json` report bounded protection findings and activation gaps; they do not certify a repository or agent as safe
  • Enriched diagnostics -- `phantom doctor` reports install source, vault backend, audit-log status, Argon2 params, and MCP wiring per client
  • Secret explainer -- `phantom why ` explains detection heuristics
  • Cross-project copy -- `phantom copy` shares secrets between project vaults
  • Team vaults -- Fixed-membership encrypted sharing; owner/admin roles gate invitations, while current vault access is member-wide and offboarding rotation is not shipped
  • Fail-closed service routing -- agentic proxy sessions accept Phantom's exact built-in OpenAI, Anthropic, Stripe, Supabase, and other reviewed routes; repository-defined destinations are rejected pending trusted-terminal approval support
  • Threat model -- See THREAT_MODEL.md for assets, actors, mitigations, and known gaps

Installation

Homebrew (macOS, v0.7.5)

Homebrew 6 requires explicit formula trust for third-party taps:

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

This formula installs both `phantom` and `phantom-mcp` from the immutable

`v0.7.5` GitHub release.

Exact v0.7.5 GitHub assets

Use the asset matching your OS and architecture. Download its adjacent

`.sha256` file from the release, verify it before extraction, and place both

`phantom` and `phantom-mcp` (`.exe` on Windows) on `PATH`.

On Linux, verify with `sha256sum -c

If Phantom saves you from leaking a key — or even just from worrying about it — please **star the repo ⭐**. It's the single biggest signal we use to know what to build next.

License

MIT — see LICENSE.

Frequently asked questions

What is phantom-secrets?

phantom-secrets is Stop AI coding agents from leaking your API keys. Local proxy + MCP that swaps real secrets for phm_ tokens — works with Claude Code, Cursor, Windsurf, and Codex.

How do I install phantom-secrets?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is phantom-secrets open source?

Yes — it is hosted on GitHub at https://github.com/ashlrai/phantom-secrets and has 16 stars.

Related MCP tools

IvanMurzakUnity-MCP

AI Skills, MCP Tools, and CLI for Unity Engine. Full AI develop and test loop. Use cli for quick setup. Efficient token usage, advanced tools. Any C# method may be turned into a tool by a single line. Works with Claude Code, Gemini, Copilot, Cursor and any other absolutely for free.

4,137 C#
aiai-integrationgame-development+16
jgravellejcodemunch-mcp

Cut AI token costs 95%+ on code exploration. The leading MCP server for precise, symbol-level GitHub code retrieval via tree-sitter AST. Works with Claude Code, Cursor & any MCP client. 313B+ tokens saved.

2,651 Python
claudeclaude-codeai-coding+17
Houseofmvpscodesight

Universal AI context generator. Saves thousands of tokens per conversation in Claude Code, Cursor, Copilot, Codex, and more.

1,397 TypeScript
aiclaudecli+11
riponcmprojectmem

Open-source coding agent memory. Records issues, attempts, fixes and decisions, then warns your agent before it repeats an approach that already failed. Native MCP server for Claude Code, Cursor, Antigravity and Codex. 100% local, no cloud, no telemetry. MIT.

796 Python
ai-agentsai-memoryai-tools+17
AVIDS2memorix

Open-source cross-agent memory layer for coding agents via MCP. Compatible with Claude Code, Codex, Cursor, Windsurf, Gemini CLI, Antigravity, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Copilot, Kiro, OpenCode, and Trae.

721 TypeScript
ai-codingclaude-codecopilot+17
0xMassiwebclaw

Fast, local-first web content extraction for LLMs. Scrape, crawl, extract structured data — all from Rust. CLI, REST API, and MCP server.

2,319 Rust
ai-agentsclillm+17

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP