This guide is for a developer who wants Claude Code, Codex, Cursor, Windsurf, or GitHub Copilot to work on a repository that uses API credentials. It creates a bounded delegation contract around Phantom's shipped CLI, vault, local proxy, and value-blind MCP tools.
Completing this guide protects managed dotenv values and verifies local setup. It does not grant an agent general production authority, approve provider or deployment changes, activate Locus, or prove that a customer workflow works.
You need:
- a Git repository and a supported local shell;
- both
phantomandphantom-mcpfrom the reviewedv0.8.7GitHub release, or the separately published Homebrew distribution (see distribution status); - the AI client you intend to use; and
- an independent recoverable copy of each real credential, such as the provider's credential console or an approved password manager.
Never paste a real credential into chat, a task brief, an agent instruction
file, or a command-line argument. Use secret names such as
STRIPE_SECRET_KEY, not values.
From the repository root, run:
phantom agent setup --dry-runThis is a read-only preview. Review the listed files, commands, and any item
marked requires_approval. A readiness status is a local configuration signal;
it is not a security certification or permission for the agent to act.
Stop if Phantom reports an unexpected dotenv path, an inaccessible vault, or a configuration you do not own.
The readiness preview does not apply setup changes, but it probes the configured vault and cloud-login state, which can involve the OS keychain. For a disposable check that deliberately avoids those probes, run the installed-runtime smoke example.
init is a local mutation: it stores detected secret values in the selected
vault backend, atomically rewrites the managed dotenv file with phm_
placeholders, writes Phantom configuration, generates .env.example when the
project has none (an existing one is left byte-for-byte unchanged), and
attempts to install the repository pre-commit check.
Install the reviewed v0.8.7 GitHub release using the platform-specific path in
getting started, then run phantom init.
If auto-detection selects the wrong file, stop and use an explicit path shown by
phantom init --help. Phantom intentionally does not leave a plaintext
project-local backup. Recover a lost provider value from the independent source
named in the prerequisites, not from an agent transcript.
Confirm that secret names are present without printing values:
phantom list
phantom checkPreviewing prints configuration without changing the client:
phantom setup --client codex --printApply one supported setup writer, then restart the client:
| Client | Configure MCP | Start a proxy-scoped session | Detailed guide |
|---|---|---|---|
| Claude Code | phantom setup --client claude |
phantom exec -- claude |
Claude Code |
| Codex | phantom setup --client codex |
phantom exec -- codex |
Codex |
| Cursor | phantom setup --client cursor |
phantom exec -- cursor . |
Cursor |
| Windsurf | phantom setup --client windsurf |
phantom exec -- windsurf . |
Windsurf |
For GitHub Copilot, Phantom does not ship a Copilot-specific setup writer.
Repository instructions can live in .github/copilot-instructions.md; MCP is
configured through the supported VS Code surface. Keep build or test processes
that need local credentials inside a phantom exec -- <command> session.
The setup writers change client configuration. Review the preview first and retain the previous client file if your organization requires rollback. Phantom merges its MCP entry, but it is not a general client-configuration manager.
phantom agent doctor
phantom agent report --json
phantom agent status --json # read-only MCP approval counts; no nonces or valuesResolve critical findings before continuing. The JSON report can return
unsafe, protected, verified, team-ready, or compliance-ready.
Those names describe Phantom's local readiness policy:
unsafemeans a critical local finding remains;protectedmeans critical findings are absent but optional or verification work remains;verifiedadditionally requires MCP wiring, a pre-commit check, and no warning findings;team-readyadditionally observes cloud login and configured sync targets;compliance-readyadditionally observes audit mode.
None of these states proves a deployment, provider permission, regulatory certification, organizational control, or customer acceptance.
Copy the agent policy into the instruction surface your repository already uses, and fill in the task brief for the specific job.
At minimum, state:
- the exact repository, branch, and objective;
- which files and external systems are in scope;
- secret names the task may depend on, without values;
- allowed read-only actions;
- mutations that require a fresh human approval;
- forbidden actions; and
- the tests and evidence required for completion.
A useful first task is narrow and reversible, for example:
Add a provider client behind the existing interface and test it with a local stub. You may inspect value-blind Phantom metadata. Do not reveal credentials, contact the live provider, deploy, sync secrets, rotate keys, or publish.
Start the selected client with the local proxy active. For example:
phantom exec -- codexApplication or test processes launched inside this session receive Phantom's
proxy routing. The child process can use the authenticated loopback proxy while
the session is alive, so phantom exec is a credential-injection boundary, not
a process sandbox.
Agents can inspect secret names and protection state through MCP. If a secret is
missing, have the agent report its name, then run phantom add SECRET_NAME in
your trusted terminal and enter the value at the hidden prompt. Do not put the
value in a command-line argument or an agent-controlled terminal.
The compatibility tool phantom_add_secret_interactive only returns that
terminal command; it does not open a prompt, receive the value, or store
anything. Because it is effect-free it works with MCP effects disabled and needs
neither confirm nor an approval_token. Leave effects disabled for this basic
workflow.
Before accepting the result:
phantom check
phantom agent doctor
git diff --check
git status --shortAlso run the repository's focused tests and review the diff. Record separately:
- source changes and local tests;
- any built artifact;
- any deployment or provider operation;
- any live acceptance; and
- anything skipped or blocked.
Local source and tests do not prove the later layers. If the task requires a deployment, secret sync, credential rotation, provider grant, cloud/team write, or workspace apply, stop and obtain approval for that exact target and recovery plan.
- A real value entered chat or logs: stop, remove it from the active surface where possible, rotate it at the provider, then update the Phantom vault.
- A readiness check becomes
unsafe: stop agent work and resolve the critical finding before retrying. - The proxy is unavailable: stop network-dependent tests; do not bypass it by exposing a real credential to the agent.
- Client configuration is wrong: restore the reviewed prior client config,
use
phantom setup --client <client> --print, and reconcile the exact MCP entry before restarting. - A live mutation was not authorized: stop, preserve logs without secret values, reconcile the affected provider or platform, and use its approved rollback path.
For a multi-person rollout, continue with the enterprise adoption guide.