Phantom

Delegate more to AI without putting real keys in agent context.

Phantom replaces project secrets with scoped phm_ placeholders. Applications use those placeholders through an authenticated local proxy, while agents use value-blind MCP tools for inventory, diagnostics, and governed requests.

Quick start · ⭐ Star Phantom · Delegate safely · Why Phantom? · MCP setup · Docs · Contribute · phm.dev

---

▶ Historical v0.4 demo — current behavior differs  ·  🛡 Security model  ·  📋 Threat model  ·  💬 Discussions

[!IMPORTANT] Release-state snapshot (verified 2026-09-05): the immutable v0.7.8 GitHub release at source commit f065b13462f9eaf27e0443f8911f021575b7c409. Its 19-asset release set, checksums, archive-specific SPDX SBOMs, GitHub provenance and SBOM attestations, and all six native release rows are bound to that immutable release record by tag-bound workflow 33952398697. Exact public registry endpoints were requeried on 2026-09-05. Homebrew independently publishes reviewed v0.7.8; 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.

Goal	Start	What it establishes
See the delegation boundary with no secret or setup	Run node examples/first-five-minutes/run.mjs, then read the first-five-minutes walkthrough	A deterministic, read-only example contract; not vault, proxy, provider, or deployment acceptance.
Protect a real local project	Follow Quick Start with the reviewed v0.7.8 GitHub release	Local initialization and diagnostics on your machine.
Connect an AI coding client	Complete the first MCP task	Value-blind capability, status, and repository checks; no provider action.
Define a bounded task for an agent	Use the safe delegation quickstart	A reviewable task contract with explicit authority and acceptance boundaries.
Evaluate a team rollout	Use the enterprise adoption guide	A controlled evaluation plan; not a claim of commissioned cloud or enterprise service.
Audit the trust model first	Read the security model and threat model	Documented 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.8 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.8 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.8 GitHub release. The Homebrew formula separately publishes the reviewed v0.7.8 binaries:

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

For exact v0.7.8 on macOS, Linux, or Windows, use the matching release asset in Installation. Then protect and verify the project:

$ 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.8 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:

$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:

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.8 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

  .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.8, 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.8. 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.8 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.8. 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.8. 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 <ID>; MCP has no claim or apply operation.

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

phantom setup --client claude     # project MCP; see docs/claude-code.md for v0.7.8 migration
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.8 release binaries before setup. Version 0.7.8 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.

$ 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)