Phantom Secrets: 실제 시크릿을 AI 코딩 에이전트로부터 숨기는 로컬 프록시와 MCP 서버

누구에게 맞는가

AI 코딩 에이전트를 일상 개발에 연결해 두고 프로젝트의 .env 에 실제 시크릿을 저장하고 있다면, 로그, 오류 출력, 컨텍스트 조각이 모두 시크릿 유출 경로가 될 수 있습니다. Phantom 은 “앱은 그대로 실제 값을 받는다”와 “에이전트는 절대 시크릿 값을 보지 못한다” 사이에 뚜렷한 경계를 세워야 하는 개발자와, 시크릿을 일괄 배포하고 회전시키면서도 각자의 툴체인에 내려놓고 싶지 않은 팀에 적합합니다.

형태는 “로컬 프록시 + MCP 서버” 입니다. 프로젝트 시크릿은 스코프가 있는 phm_ 자리표시자로 바뀌고, 앱은 인증된 로컬 프록시를 통해 실제 값을 받아 오며, 에이전트 쪽에는 값을 볼 수 없는 MCP 도구만 노출되어 목록화, 진단, 통제된 요청에 쓰입니다. 전제는 프록시 프로세스를 내 컴퓨터에 계속 상주시키고 .env 덮어쓰기를 내가 관리하는 버전 관리 흐름에 넣는 것입니다. 이 단계는 아무데나 건너뛸 수 있는 절차가 아닙니다.

3분 만에 첫 시도

권장되는 공식 경로는 Homebrew 입니다. 저장소가 안내하는 macOS 설치는 3단계 순서입니다. 먼저 tap, 그다음 trust, 마지막으로 install 이고, 설치되는 것은 phantom 과 phantom-mcp 두 실행 파일로 저장소가 표기한 v0.7.9 버전에 해당합니다.

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

전제 조건: macOS 에 Homebrew 가 설치되어 있어야 합니다. Homebrew 를 쓰지 않고 소스에서 직접 빌드한다면 저장소가 컴파일러 툴체인 버전을 고정해 두었으므로 빌드 환경에 해당 버전의 Rust 툴체인이 맞아야 합니다.

이어서 순서대로 두 단계 설정입니다. 먼저 프로젝트 디렉터리로 이동해 phantom init 을 실행합니다. 이는 쓰기 작업이라는 점을 주의해야 합니다. 해당 프로젝트의 .env 를 덮어써 실제 키 값을 phm_ 자리표시자로 바꿉니다. 확인 지점은 실행 전에 .env 가 백업되었거나 커밋되었는지 확인하고, 명령 출력에서 치환 건수가 예상과 일치하는지 대조하는 것입니다. 두 번째 단계는 클라이언트별 설정을 기록하는 것입니다.

phantom init
phantom setup --client claude

그다음 읽기 전용 단계로 저위험 검증합니다. phantom list 는 시크릿 목록은 보여 주되 어떤 값도 표시하지 않습니다. 관찰 가능한 성공 신호는 터미널에 항목 이름만 나열되고 각 항목 뒤에 실제 시크릿 문자가 따라오지 않는 것입니다. 그다음 에이전트에게 저장소를 한 번 더 읽게 하면 실제 값 대신 phm_ 로 시작하는 것만 얻습니다.

전체 명령과 옵션 설명은 공식 저장소 https://github.com/ashlrai/phantom-secrets 를 참고하세요

활용 사례

사례 하나: 에이전트에게 “목록은 보지만 값은 안 보이는” 통로를 제공합니다. 에이전트 측의 MCP 도구는 값을 볼 수 없는 도구로, 목록화, 진단, 통제된 요청 세 가지 용도를 덮습니다. 저장소는 이 도구들의 위치를 능력, 상태, 저장소 상태 점검으로 규정하며 provider 측 동작을 전혀 촉발하지 않습니다. 따라서 “이 프로젝트에 어떤 시크릿이 설정되어 있는지, 현재 경로가 통하는지, 저장소 안에서 어떤 파일이 자리표시자를 참조하는지”를 에이전트에게 안심하고 물어볼 수 있습니다. 에이전트는 시크릿 값을 되돌려 주지도, 점검 중에 클라우드 자원을 함부로 바꾸지도 않습니다.

사례 둘: 업무 코드는 실제 값으로 계속 돌게 하면서도 실제 값을 에이전트의 시야 밖에 두는 경우입니다. 치환은 초기화 단계에서 일어납니다. .env 의 실제 키 값이 스코프가 있는 phm_ 자리표시자로 바뀌고, 앱은 평소처럼 환경 변수를 읽고, 내보낸 요청은 로컬 프록시가 대신 받아 인증 이후 실제 값을 되찾아옵니다. 프록시 측의 통제된 요청 진입점과 목록, 진단 진입점은 같은 “값을 보이지 않는다” 제약을 공유하므로 앱은 정상 동작하면서 에이전트는 여전히 시크릿 자체를 손에 넣지 못합니다. 저장소 자료는 프록시가 “인증된” 로컬 프록시라는 것까지만 밝힐 뿐 인증 방식의 구체적인 형태는 다루지 않으므로, 이 부분은 저장소 설명을 따르세요.

사용 경계

첫째, phantom init 은 .env 를 덮어씁니다. 이것은 확실한 쓰기 작업입니다. 실행 전에 백업하거나 커밋하고, 치환 전후 차이를 그대로 공개 채널에 붙여 넣지 마세요.

둘째, 에이전트 측 도구의 값에 대한 무지 성질은 “값을 볼 수 없다”는 것만 보장할 뿐 “무엇이든 할 수 있다”는 뜻이 아닙니다. 저장소는 이를 능력, 상태, 저장소 상태 점검으로 규정하며 provider 동작을 대신 발동시키지 않습니다. 실제 클라우드 호출은 앱이 로컬 프록시를 통해 보내는 요청 경로에서 일어나므로, 문제를 좇을 때는 이 두 구간을 구분해야 합니다.

셋째, 이것은 무위험 도구가 아닙니다. 로컬 .env 와 클라이언트 설정 파일을 읽어야 하고, 로컬 프록시는 요청을 서드파티 provider 로 보내므로 시크릿은 여전히 사용자의 컴퓨터와 해당 provider 사이를 오갑니다. 이 경로를 받아들일지는 조직이 에이전트 측에 그 존재를 허용하느냐에 달려 있습니다.

넷째, 저장소의 설치 방식과 명령 설명은 버전에 따라 바뀌므로, 업그레이드 전에 공식 저장소로 돌아가 대조하세요.