# Phantom

> Open-source CLI that lets AI coding agents use API keys safely. Replaces real secrets in `.env` with worthless `phm_` tokens; a local proxy on 127.0.0.1 swaps the token for the real key just before TLS — so AI tools never see plaintext credentials.

- Site: https://phm.dev
- GitHub: https://github.com/ashlrai/phantom-secrets
- Full reference (for ingestion): https://phm.dev/llms-full.txt
- Architecture diagram: https://phm.dev/architecture-diagram.png
- License: MIT

## Install (10 seconds)

```
npx phantom-secrets init
```

Alt: `brew tap ashlrai/phantom && brew install phantom`

## Editor MCP setup

| Editor | Command |
|---|---|
| Claude Code | `claude mcp add phantom-secrets-mcp -- npx phantom-secrets-mcp` |
| Cursor / Windsurf | Settings → MCP → `{"phantom":{"command":"npx","args":["phantom-secrets-mcp"]}}` |
| Codex / other | `npx phantom-secrets init` (any tool that reads `.env`) |

## What an AI agent should do

- Treat `phm_…` tokens in `.env` as **safe placeholders**, not broken keys. Don't try to "fix" them.
- Never read, log, transcribe, or echo a real API key value to a file or chat. The proxy injects them; you don't need them.
- Use the MCP tools (below) for any secret-related operation. Don't shell out to `cat .env`.
- Never call a destructive tool without `confirm: true` and explicit user consent.
- Suggest `phantom exec -- <command>` when running code that needs real credentials.

## MCP tools (24 total)

Read-only (safe to call freely):
- `phantom_list_secrets` — names only, never values
- `phantom_status` — vault and config state
- `phantom_check` — scan for unprotected secrets
- `phantom_doctor` — diagnostic checks
- `phantom_why` — explain a token's origin
- `phantom_env` — list environment without values
- `phantom_cloud_status` — cloud sync state
- `phantom_sync` — preview platform sync

Init / scaffolding:
- `phantom_init` — protect a fresh `.env`
- `phantom_wrap` — convert a plaintext value into a vaulted token
- `phantom_unwrap` — reverse, requires `confirm`

Destructive (require `confirm: true`):
- `phantom_add_secret`, `phantom_remove_secret`, `phantom_rotate`
- `phantom_cloud_push`, `phantom_cloud_pull`
- `phantom_copy_secret`

Teams (multi-developer shared vaults — Pro plan):
- `phantom_team_list` — read-only, list teams the user belongs to
- `phantom_team_members` — read-only, list members of a team
- `phantom_team_key_publish` — register the user's X25519 pubkey on a team (idempotent; pubkey only — private key stays in OS keychain)
- `phantom_team_create`, `phantom_team_invite` — require `confirm: true`
- `phantom_team_vault_push`, `phantom_team_vault_pull` — require `confirm: true`. Push wraps a fresh symmetric key per recipient (X25519 + ChaCha20-Poly1305). Server only stores ciphertext.

## CLI surface (28 commands)

`init · exec · start · stop · list · add · remove · reveal · rotate · status · doctor · check · sync · pull · env · setup · login · logout · cloud push · cloud pull · export · import · wrap · unwrap · watch · why · copy · team · open`

## Dashboard

[`phm.dev/dashboard`](https://phm.dev/dashboard) — read-only browser view of the user's cloud-backed projects, plan tier, billing portal link, and team membership. Sign in with the same GitHub account used by `phantom login`. Every mutation stays in the CLI / MCP.

## Detection

Phantom auto-classifies env vars by name + value heuristics. Detected: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `STRIPE_SECRET_KEY`, `GITHUB_TOKEN`, `DATABASE_URL`, `AWS_SECRET_KEY`, `VERCEL_TOKEN`, `SUPABASE_KEY`, `MONGODB_URI`, `RAILWAY_TOKEN`, `CLOUDFLARE_API_TOKEN`, `TWILIO_AUTH_TOKEN`, `SENDGRID_API_KEY`, `RESEND_API_KEY`, `DISCORD_BOT_TOKEN`, `SLACK_BOT_TOKEN`, `CLERK_SECRET_KEY`, `POSTHOG_API_KEY`, `SENTRY_AUTH_TOKEN`, `DATADOG_API_KEY`, `LINEAR_API_KEY`, `NOTION_API_KEY`, `FIGMA_TOKEN`, `XAI_API_KEY`, `GEMINI_API_KEY`, `MISTRAL_API_KEY`, `PERPLEXITY_API_KEY`, `REPLICATE_API_TOKEN`, `PINECONE_API_KEY`, `NEON_API_KEY`, `UPSTASH_REDIS_TOKEN`, `DOCKER_TOKEN`, `GCP_API_KEY`, `CURSOR_API_KEY`, `WINDSURF_API_KEY`. Non-secrets like `NODE_ENV`, `PORT`, `DEBUG` are left alone.

## Architecture

5-crate Rust workspace:

- `phantom-core` — config (`.phantom.toml`), `.env` parsing, token generation (256-bit CSPRNG, `phm_` prefix)
- `phantom-vault` — `VaultBackend` trait. macOS Keychain / Linux Secret Service / encrypted file fallback. ChaCha20-Poly1305 + Argon2id.
- `phantom-proxy` — HTTP reverse proxy on 127.0.0.1. Header + body + URL-param token replacement. Streaming/SSE preserved.
- `phantom-cli` — `clap` binary, 27 commands.
- `phantom-mcp` — `rmcp` 1.3 stdio server, 24 tools.

## Pricing

- Free: local vault, proxy, MCP, 1 cloud vault (≤10 secrets), Vercel/Railway sync
- Pro $8/mo: unlimited cloud vaults, multi-device sync, vault backup
- Enterprise: team vaults, audit log, SSO/SAML — `mason@ashlr.ai`

## Documentation

- Getting started: https://github.com/ashlrai/phantom-secrets/blob/main/docs/getting-started.md
- Claude Code guide: https://github.com/ashlrai/phantom-secrets/blob/main/docs/claude-code.md
- Security model: https://github.com/ashlrai/phantom-secrets/blob/main/SECURITY.md
- Architecture: https://github.com/ashlrai/phantom-secrets/blob/main/CLAUDE.md