가이드

팀의 API 키·시크릿을 한 곳에 두고, 사람은 이 웹 어드민에서 관리하고, 에이전트(Claude Code 등)는 MCP 툴로 사용합니다.

핵심 원칙: 값은 노출되지 않습니다. 에이전트는 키의 존재·메타데이터만 볼 수 있고, 실제 값은 명령을 실행할 때 자식 프로세스의 환경변수로만 주입됩니다. 출력·로그에 값이 섞이면 자동으로 *** 마스킹됩니다. 그래서 .env 파일을 만들거나 채팅에 키를 붙여넣을 필요가 없습니다.

이 어드민(https://purplekey.purpleworks.co.kr)에 회사 Google 계정(@purpleworks.co.kr)으로 로그인하면 끝입니다. 프로젝트를 만들면 내가 owner가 되고, Members에서 팀원을 초대합니다 — 아직 로그인한 적 없는 이메일도 초대해두면 첫 로그인 때 자동 합류합니다.

키 등록은 프로젝트 상세 → Secrets → "키 추가". 값은 저장 후 다시 표시되지 않으며, 필요하면 조회(눈 아이콘)로 확인합니다 — 조회는 감사 로그에 남습니다.

PurpleKey(팀 시크릿 매니저) 클라이언트를 이 머신에 설정해줘:

1. 설치(1회):
   pnpm add -g --allow-build=@purplekey/mcp "git+ssh://git@github.com/purpleworks/purplekey.git#main&path:packages/mcp"
   (pnpm 글로벌이 처음이면 먼저 pnpm setup 후 새 셸에서. purplekey-mcp 바이너리가 PATH에 생긴다.
   업데이트도 같은 명령 재실행. 서버 주소는 클라이언트에 기본값으로 박혀 있어 설정 불필요.)
2. 에이전트에 등록해줘. Claude Code라면 둘 중 하나:
   claude plugin marketplace add purpleworks/purplekey && claude plugin install purplekey@purplekey
   (플러그인 — 스킬 포함, 권장) 또는 claude mcp add purplekey -- purplekey-mcp (MCP만)
   (Codex/Gemini 등 다른 에이전트면 MCP 설정에 command "purplekey-mcp"로 등록)
3. 등록 직후에는 이 세션에서 purplekey 툴이 안 보일 수 있다 — 그 경우 나에게
   "/mcp 에서 재연결(또는 새 세션)" 하라고 안내하고 기다려줘.
4. purplekey 툴이 보이면 whoami로 로그인 상태를 확인하고, 로그인이 안 돼 있으면
   login 툴을 호출해줘(브라우저가 열리면 내가 회사 Google 계정으로 로그인할게).
5. 지금 작업 중인 프로젝트 폴더가 있으면 list_projects 확인 후 link_project로 연결해줘.
   프로젝트가 없으면 create_project로 만들어도 된다.
6. 앞으로 이 머신에서 시크릿이 필요한 실행은 .env 파일 대신 purplekey MCP의
   run_command/run_app을 쓰고, 키 값을 조회·출력·파일에 기록하지 마.

수동으로 하려면 아래 순서대로:

1. 클라이언트 설치 — 클론 불필요, 한 줄 (npm 미출간 상태의 현행 경로 — repo read 권한 + GitHub SSH 키 필요):

pnpm add -g --allow-build=@purplekey/mcp \
  "git+ssh://git@github.com/purpleworks/purplekey.git#main&path:packages/mcp"

pnpm 글로벌을 처음 쓰면 pnpm setup 1회 후 새 셸에서 실행하세요. 업데이트도 같은 명령 재실행이면 됩니다. 서버 주소는 클라이언트에 기본값(https://purplekey.purpleworks.co.kr)으로 박혀 있어 따로 설정할 것이 없습니다.

2. 에이전트에 등록 — Claude Code는 둘 중 하나:

# 플러그인 (스킬 포함, 권장)
claude plugin marketplace add purpleworks/purplekey
claude plugin install purplekey@purplekey

# 또는 MCP만
claude mcp add purplekey -- purplekey-mcp

Codex CLI는 ~/.codex/config.toml, Gemini CLI는 JSON 설정에 같은 명령(purplekey-mcp)을 등록하면 됩니다.

3. 처음 쓸 때 에이전트가 login 툴을 호출하면 브라우저가 열립니다 — 회사 Google 계정(@purpleworks.co.kr만 허용) 로그인 한 번이면 기기가 연결됩니다(90일 유지, My keys → 세션/기기에서 관리).

4. 프로젝트 폴더 연결은 에이전트가 link_project 툴로 직접 합니다 (.pk.json 생성) — 사람이 미리 해둘 것 없이 "이 프로젝트 purplekey 연결해줘" 한마디면 됩니다.

프로젝트 키는 멤버 전체가 쓰는 키(프로젝트 상세 → Secrets), 개인 키(My keys)는 나만 쓰는 키로 실행 시 프로젝트 키와 병합됩니다(같은 이름이면 프로젝트 키 우선). 환경(dev/staging/prod)별로 따로 등록합니다. 키는 등록한 이름 그대로 주입되며, 소비처가 다른 이름을 원하면 에이전트가 실행 명령에서 알아서 매핑합니다.

에이전트가 시크릿이 필요한 명령을 만나면 셸에서 직접 돌리는 대신 MCP run_command(유한 명령: 테스트·빌드) / run_app(dev 서버 같은 장기 실행)을 씁니다 — 값이 자식 프로세스 env로 주입되고, 출력은 마스킹됩니다. 앱 로그는 app_logs, 정지는 stop_app.

프로젝트의 AGENTS.md/CLAUDE.md에 넣어두면 좋은 규칙:

이 프로젝트의 시크릿은 PurpleKey로 관리된다.
- 키 값을 조회·출력·파일 기록하지 마라. .env 파일을 만들지 마라.
- 시크릿이 필요한 실행은 MCP run_command / run_app을 써라.
- 키 존재 확인은 check_key / list_keys / key_info. 없으면 웹 어드민 등록을 요청해라.

프로젝트 상세 → Machine tokens → "토큰 발급"(라벨·env 스코프·만료 지정 — prod용은 반드시 env를 prod로 스코프). 발급된 pk_ci_... 원문은 한 번만 표시되니 CI 시크릿 저장소에 PK_TOKEN으로 저장하세요. 머신 토큰은 해당 프로젝트 읽기 전용이라 유출돼도 그 토큰만 폐기하면 됩니다.

사용은 순수 HTTP — 핵심 호출:

curl -sSf -H "Authorization: Bearer $PK_TOKEN" -H "x-pp-client: ci" \
  "https://purplekey.purpleworks.co.kr/api/projects/<slug>/inject?env=staging"
# 응답: {"secrets": {"KEY": "value", ...}}  — env= 는 반드시 명시(생략 시 dev 폴백)

GitHub Actions용 하드닝 레시피 전문(마스킹 등록·예약어 차단 포함)은 클라이언트 repo의 purpleworks/purplekey → docs/ci-machine-token.md를 그대로 복사해 쓰세요.

owner(프로젝트당 1명, 생성자)는 프로젝트 삭제·복구·소유권 이전까지, admin은 키·멤버·토큰 관리, member는 키 사용을 할 수 있습니다. owner는 제거·강등되지 않으며 Members에서 소유권 이전으로만 바뀝니다.

프로젝트 삭제(owner, slug 입력 확인)는 30일 유예를 거칩니다 — 즉시 접근이 차단되고 머신 토큰이 폐기되며, Projects 하단 휴지통에서 복구할 수 있습니다(복구해도 토큰은 재발급 필요). 유예가 지나면 자동 영구 삭제되고 감사 로그만 남습니다.