Phantom: 에이전트에게 API 작업을 위임하되 실제 키를 컨텍스트에 넣지 마세요

실제 키를 에이전트 컨텍스트에 넣지 않고도 AI에게 더 많은 작업을 위임하세요.

Phantom은 프로젝트 시크릿(secrets)을 범위가 지정된 phm_ 플레이스홀더로 대체합니다. 애플리케이션은 이 플레이스홀더들을 인증된 로컬 프록시를 통해 사용하며, 에이전트는 인벤토리, 진단 및 관리되는 요청을 위해 값에 맹목적인(value-blind) MCP 도구를 사용합니다.

CI

Verified GitHub release

Source version

Pinned toolchain: Rust 1.95

License: MIT

빠른 시작(Quick start) ·
안전하게 위임하기(Delegate safely) ·
Phantom이란? (Why Phantom?) ·
MCP 설정 ·
문서(Docs) ·
기여하기(Contribute) ·
phm.dev

설치 (Install)

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

macOS의 경우 Homebrew를 통해 설치하며, phantom과 phantom-mcp가 설치됩니다(검토된 버전: v0.7.8). Linux 및 Windows 사용자는 해당 릴리스 에셋을 사용하세요. 그런 다음 프로젝트에서 phantom init을 실행하고 phantom setup --client claude (또는 cursor, windsurf, codex)를 실행합니다. 전체 과정은 빠른 시작을 참고하세요.

▶ 과거 버전 v0.4 데모 — 현재 동작 방식이 다름  · 
🛡 보안 모델(Security model)  · 
📋 위협 모델(Threat model)  · 
💬 토론(Discussions)

여기서 시작하기 (Start here)

다음 질문에 답하는 가장 작은 경로를 선택하세요. 첫 번째 경로는 자격 증명(credential)을 사용하지 않고, 네트워크 요청도 수행하지 않으며, Phantom을 설치하거나 구성할 필요가 없습니다.

Phantom을 사용하는 이유?

AI 코딩 에이전트는 로컬 자격 증명을 포함하는 저장소에서 일상적으로 작동합니다. 실제 API 키가 에이전트 컨텍스트, 기록(transcript), 도구 호출 또는 생성된 파일에 들어가면, 해당 값이 어디에 지속될지 통제력을 잃게 됩니다.

기존의 비밀 관리자(secrets managers)는 저장 상태 및 전송 중인 키에 초점을 맞춥니다. Phantom은 에이전트 컨텍스트를 위한 경계를 추가합니다:

• 🔒 하나의 자격 증명 노출 경로 감소 — 관리되는 프로젝트 dotenv 파일에는 민감한 phm_ 매핑이 포함되어 있고, MCP 응답은 값에 무지(value-blind)하며, 정확한 프록시 경로는 자체 구성된 인증 값을 주입합니다. 관리되지 않는 파일, 광범위한 셸 권한, 동일 사용자 프로세스는 위협 모델에 남아 있습니다.
• ⚡ 빠른 로컬 설정 — 검토된 v0.7.9 GitHub 릴리스를 설치한 후, phantom init은 계정, DNS 변경 또는 사용자 지정 CA가 필요하지 않은 상태에서 프로젝트를 보호합니다.
• 🧰 에이전트 네이티브 통합 — Claude Code, Cursor, Windsurf, Codex용 설정 도우미 및 값에 무지한 MCP 워크플로우와 GitHub Copilot을 위한 프로젝트 지침이 제공됩니다.
• 🦀 오픈 소스, 로컬 우선, MIT 라이선스 — 비밀 정보는 사용 가능한 경우 네이티브 OS 자격 증명 저장소를 사용하며, 명시적인 암호화 파일 대체(fallback)를 가집니다. 선택적 클라우드 동기화는 서버가 저장하기 전에 볼트 페이로드를 클라이언트 측에서 암호화합니다.

프로젝트 상태 및 신뢰 경계

Phantom이 구현한 사용자 대상 인터페이스는 CLI, vault, 인증된 로컬 프록시(authenticated local proxy), MCP 서버, 그리고 아래에 문서화된 선택적 클라우드/팀 워크플로우입니다. 클라우드 및 팀 동작은 배포된 서비스, 계정 플랜, 제공업체 구성에 추가적으로 의존하며, 소스 코드만으로는 배포 또는 고객 수용 증거가 될 수 없습니다. 대화 파사드(conversation facade)는 의도적으로 좁게 설계되었습니다:

• phantom_do는 제안 전용입니다. 이는 폐쇄된 Cargo 액션을 정규화하고, 그 다이제스트(digest), 효과(effect), 그리고 활성화 차단기(activation blockers)를 보고합니다. execute는 엄격히 거부됩니다.
• phantom_setup_workspace는 설정을 제안하고, 베어러리스 요청을 생성하며, 인증 상태를 보고할 수 있습니다. 요청을 적용하는 것은 별도의 신뢰 터미널 작업으로 남아있습니다.
• 고급 MCP 도구들은 호환성 카탈로그로 남아 있으며, 기본적으로 비활성화되어 있고, 별도의 명시적 확인 및 정보에 입각한 터미널 승인 게이트를 거쳐야 합니다. 이들은 대화 파사드의 기능 카드(capability card)에 의해 통제되지 않습니다.
• phantom grant는 가치에 둔감한 생명 주기 메타데이터와 설계 출처 기반을 유지하지만, 자격 증명 또는 네트워크 접근 전에 모든 라이브 제공업체 발급/갱신 경로를 차단합니다. 제공업체 부여(provider grant)는 에이전트가 작업을 실행할 수 있는 권한 부여(authority grant), 브로커 리스(broker lease), 또는 권한을 의미하지 않습니다.
• authority, broker, runtime, session, 그리고 evidence 크레이트는 비활성 상태의 기반입니다. 이들은 오늘날 라이브 Locus 권한, 브로커 자격 증명, 실행 에이전트 액션 등을 설정하거나 외부적으로 신뢰할 수 있는 영수증을 생성하지 않습니다.

세 경계에 대한 근거는 문서화 맵, 아키텍처, 보안 정책, 및 위협 모델을 참조하십시오.

측정된 내용: 스크립트화된 적대자에 대한 유출률 (leak rate)

python3 eval/leak-rate/harness.py 5로 재현합니다(약 3분 소요, Linux, phantom 0.7.9; 유료 키 없이 가짜 카나리아 키만 사용). 방법 및 제한 사항: eval/leak-rate/README.md.

450은 30가지 공격 기법 x 3가지 비밀 정보(secrets) x 5회 실행(cat .env, printenv, /proc/self/environ, base64 및 hex dump, git add -f, ps eww, phantom reveal/export/exec, confirm=true로 호출된 모든 MCP 도구, 그리고 스크립트 에이전트가 따르는 README 프롬프트 주입)를 의미합니다. 기법별 표는 eval/leak-rate/table.md를 참조하세요.

이것은 다음을 보여주지 않습니다: 이는 LLM(대규모 언어 모델)이 아닌 스크립트화된 최악의 시나리오이므로, 키가 나타날 수 있는 위치를 측정할 뿐, 모델이 얼마나 자주 찾으려고 하는지를 측정하는 것은 아닙니다. 범위를 벗어난 사례는 별도로 보고됩니다: 개발자가 .env에 넣지 않은 관리되지 않는 키 파일은 여전히 읽을 수 있습니다(두 설정 모두 15/15). OS 키체인에 대한 동일 사용자 접근은 문서화된 경계를 벗어나므로 테스트하지 않습니다. 허용된 경로에서 키를 프록시로 사용하는 것은 설계상 그렇습니다. 외부 감사는 한 대의 기기만 대상으로 합니다.

빠른 시작 (Quick Start)

검토된 v0.7.9 GitHub 릴리스에서 두 바이너리를 모두 설치하세요.
macOS에서는 Homebrew 포뮬러가 가장 짧은 경로입니다. 현재는 탭이 v0.7.9로 업데이트될 때까지 이전 검토된 v0.7.8 바이너리가 설치됩니다:

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

macOS, Linux 또는 Windows에서 정확한 v0.7.9를 사용하려면 설치의 일치하는 릴리스 에셋을 사용하세요. 그런 다음 프로젝트를 보호하고 검증합니다:

$ phantom init
# 서브디렉토리에서 .env, .env.local 또는 .env를 자동 감지합니다
# 실제 비밀 정보는 네이티브 자격 증명 저장소(native credential store) 또는 암호화된 볼트(encrypted vault)에 저장됩니다.
...

Claude Code, Codex, Cursor, Windsurf 또는 Copilot에 위임할 작업 계약(task contract)의 경우, safe delegation quickstart와 복사 가능한 정책 및 작업 템플릿을 사용하십시오. 통제된 출시(controlled rollout)를 평가하는 팀은 enterprise adoption guide로 시작할 수 있습니다.

Windows

동일한 핵심 명령어 표면(core command surface)이 네이티브 Windows용으로 구현되었으며, 남아 있는 네이티브 승인 제한 사항은 플랫폼 매트릭스에 추적됩니다. 설치에서 아키텍처에 맞는 정확한 v0.7.9 Windows ZIP을 설치하고, 게시된 .sha256 사이드카를 확인한 다음, 두 실행 파일을 PATH에 배치하십시오. WSL은 자체 파일 시스템과 자격 증명 저장소(credential-store) 컨텍스트를 가진 별도의 Linux 환경입니다.

명시적으로 감독되는 포그라운드 프록시(foreground proxy)의 경우, stdin, stdout 및 stderr 각각이 신뢰할 수 있는 터미널에 연결되도록 phantom start를 실행하십시오. 터미널 연결은 인정 확인(admission check)일 뿐, PTY를 누가 제어하는지에 대한 증거는 아닙니다. CLI가 셸을 감지하고 일치하는 환경 변수 구문(env-var syntax)을 출력하므로, 해당 내보내기(exports)를 클라이언트를 실행하는 터미널에 복사하고, 소유 터미널을 열어둔 채 Ctrl-C를 눌러 중지하십시오. 분리된 --daemon 모드와 외부 프로세스 제어는 Phantom이 별도로 검토한 사설 크로스 플랫폼 제어 채널을 갖출 때까지 실패 폐쇄(fail-closed) 상태입니다. phantom stop은 레거시 v0.7.3 .phantom.pid 세션을 인증하는 용도로만 사용되며 마이그레이션 지침을 보고합니다. v0.7.3에는 인증된 종료 엔드포인트가 없었기 때문에, 새 바이너리는 해당 프로세스를 종료하거나 기록을 삭제하지 않습니다. 소유한 v0.7.3 터미널에서 Ctrl-C를 사용하거나 Troubleshooting의 제한적 복구 절차를 사용하십시오.
참고:

PowerShell:

$env:OPENAI_BASE_URL =

**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: 메인 퀵 스타트에서 사용된 export X=Y 구문을 사용하세요.

참고 사항:

• PHANTOM_PROXY_TOKEN은 프록시 세션 인증기입니다. 기본적으로, phantom exec과 phantom start는 이를 로컬 *_BASE_URL 값에 /_phantom/TOKEN/로 포함하므로 수정되지 않은 SDK도 작동합니다. 헤더를 인식하는 클라이언트는 PHANTOM_PROXY_HEADER_AUTH_ONLY=1을 설정하고 대신 x-phantom-proxy-token: $PHANTOM_PROXY_TOKEN을 전송할 수 있습니다.
• 만약 phantom.exe가 Windows 애플리케이션 제어 정책에 의해 차단된다면, Mark-of-the-Web을 자동으로 제거하지 마십시오. 먼저 아카이브 체크섬과 두 바이너리 식별자를 릴리스 메타데이터와 비교하여 확인하십시오. 로컬 정책이 검증된 바이너리를 허용하는 경우, 사용자는 PowerShell을 통해 명시적으로 다음 명령어로 표시를 제거할 수 있습니다: Get-ChildItem "$env:USERPROFILE\.phantom-secrets\bin\*.exe" | Unblock-File.
• phantom init으로 설치되는 pre-commit hook은 #!/bin/sh 스크립트입니다. 커맨드 라인의 네이티브 git은 Git for Windows에 번들된 sh.exe를 통해 이를 호출하며, 이는 공식 Git for Windows 설치 프로그램에서 제공하는 것입니다. GUI 클라이언트(GitHub Desktop, 일부 IDE 통합)는 sh.exe가 누락된 축소된 PATH로 실행될 수 있으며 이 경우 후크를 조용히 건너뜁니다 — 이런 경우에는 터미널에서 커밋을 실행하거나 phantom check --staged를 직접 사용하십시오. CI(지속적 통합)는 어떤 상황에서도 유지되는 안전망입니다.
• 불변의 v0.7.9 릴리스에는 x64 및 ARM64 Windows ZIP이 포함되어 있으며, 두 네이티브 Windows 행 모두 태그 기반 릴리스 수락 워크플로우를 통과했습니다. 이 아카이브는 Authenticode 서명되지 않았으므로, 이 영수증만으로는 모든 엔터프라이즈 애플리케이션 제어 정책이 이를 수락할 것이라는 것을 증명하지 않습니다. platform support matrix를 참조하십시오.

작동 방식

  .env 파일 (AI 읽기 거부)       OS Keychain / Vault
  +--------------------------+      +---------------------+ 
  | OPENAI_API_KEY=phm_a7f3  | ---> | sk-real-secret-key  |
...