phantom-secrets

<div align="center">

<img src="https://phm.dev/og-image.png" alt="Phantom — Delegate supported API work to AI" width="720" />

<h1>Phantom</h1>

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

[![GitHub stars](https://img.shields.io/github/stars/ashlrai/phantom-secrets?style=for-the-badge&logo=github&color=blue&labelColor=0b0b14)](https://github.com/ashlrai/phantom-secrets/stargazers)
[![CI](https://img.shields.io/github/actions/workflow/status/ashlrai/phantom-secrets/ci.yml?style=for-the-badge&label=CI&logo=github&labelColor=0b0b14)](https://github.com/ashlrai/phantom-secrets/actions/workflows/ci.yml)
[![Verified GitHub release](https://img.shields.io/badge/verified_GitHub_release-v0.7.9-2f81f7?style=for-the-badge&labelColor=0b0b14)](https://github.com/ashlrai/phantom-secrets/releases/tag/v0.7.9)
[![Source version](https://img.shields.io/badge/source_version-v0.7.9-f5a623?style=for-the-badge&labelColor=0b0b14)](CHANGELOG.md#079---2026-09-06)
[![Pinned toolchain: Rust 1.95](https://img.shields.io/badge/pinned_toolchain-Rust_1.95-CE412B?style=for-the-badge&logo=rust&labelColor=0b0b14)](rust-toolchain.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge&labelColor=0b0b14)](LICENSE)

[**Quick start**](#quick-start) ·
[**Delegate safely**](docs/delegation-quickstart.md) ·
[**Why Phantom?**](#why-phantom) ·
[**MCP setup**](#mcp-integration-claude-code-cursor-windsurf-codex) ·
[**Docs**](docs/README.md) ·
[**Contribute**](CONTRIBUTING.md) ·
[**phm.dev**](https://phm.dev)

</div>

---

## Install

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

macOS via Homebrew; installs `phantom` and `phantom-mcp` (reviewed `v0.7.8`). Linux and Windows:
use the matching [release asset](#exact-v079-github-assets). Then run
`phantom init` in your project and `phantom setup --client claude` (or
`cursor`, `windsurf`, `codex`). Full walkthrough: [Quick Start](#quick-start).

> **▶ [Historical v0.4 demo — current behavior differs](https://github.com/ashlrai/phantom-secrets/releases/download/v0.4.0/phantom-demo.mp4)** &nbsp;·&nbsp;
> **🛡 [Security model](SECURITY.md)** &nbsp;·&nbsp;
> **📋 [Threat model](THREAT_MODEL.md)** &nbsp;·&nbsp;
> **💬 [Discussions](https://github.com/ashlrai/phantom-secrets/discussions)**

## 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](examples/first-five-minutes/README.md) | A deterministic, read-only example contract; not vault, proxy, provider, or deployment acceptance. |
| Protect a real local project | Follow [Quick Start](#quick-start) with the reviewed `v0.7.9` GitHub release | Local initialization and diagnostics on your machine. |
| Connect an AI coding client | Complete the [first MCP task](#first-mcp-task-verify-the-boundary) | Value-blind capability, status, and repository checks; no provider action. |
| Copy a tested client or CI setup | Run the [Claude Code](examples/claude-code/README.md), [Cursor](examples/cursor/README.md), or [GitHub Actions](examples/github-actions/README.md) recipe (`node examples/<name>/run.mjs`) | Each recipe runs your `phantom` binaries (from `PATH` or `--phantom <path>`) in a temporary HOME with a fake, non-provider key and is exercised in CI. |
| Define a bounded task for an agent | Use the [safe delegation quickstart](docs/delegation-quickstart.md) | A reviewable task contract with explicit authority and acceptance boundaries. |
| Evaluate a team rollout | Use the [enterprise adoption guide](docs/enterprise-adoption.md) | A controlled evaluation plan; not a claim of commissioned cloud or enterprise service. |
| Audit the trust model first | Read the [security model](SECURITY.md) and [threat model](THREAT_MODEL.md) | 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.9` 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.9 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](docs/README.md), [architecture](docs/architecture.md),
[security policy](SECURITY.md), and [threat model](THREAT_MODEL.md) for the
evidence behind those boundaries.

## Quick Start

Install both binaries from the reviewed [`v0.7.9` GitHub release](#installation).
On macOS, the Homebrew formula is the shortest path; it currently installs the
previous reviewed `v0.7.8` binaries until the tap is bumped to `v0.7.9`:

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

For exact `v0.7.9` on macOS, Linux, or Windows, use the matching release asset
in [Installation](#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](docs/delegation-quickstart.md) and
the [copyable policy and task templates](examples/agent-delegation/README.md).
Teams evaluating a controlled rollout can start with the
[enterprise adoption guide](docs/enterprise-adoption.md).

### 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.9`
Windows ZIP for your architecture from [Installation](#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 rec