KeyHarbor

소개 · 설치 · 시작하기 · 관리 앱 · 동작 방식 · 명령 · 알아 둘 것 · 자주 묻는 질문 · 문서

소개

에이전트에게 로그인을 맡기려면 비밀번호를 대화에 붙여 넣거나 .env를 통째로 보여 줘야 했습니다. 그러면 값이 모델의 문맥과 기록에 남습니다. KeyHarbor는 값을 내 Mac의 금고에 두고, 에이전트에게는 {{secret:github.password}} 같은 이름(placeholder)만 줍니다. 에이전트가 그 이름으로 입력하면 KeyHarbor가 등록된 사이트의 입력칸에서만 진짜 값으로 바꿔 넣고, 에이전트가 받는 결과에서는 값을 다시 이름으로 가립니다.

flowchart LR
    agent["에이전트"] -->|"{{secret:github.password}}"| kh["KeyHarbor<br/>정책 · origin 확인"]
    kh -->|"진짜 값 (github.com 칸에만)"| browser["전용 브라우저 세션"]
    kh -->|"값이 가려진 결과"| agent
    vault[("내 Mac의 금고<br/>Keychain + 암호화 DB")] --> kh
    you(["사람"]) -->|"요청에 답하기 · 확인 · 기록 보기"| app["관리 앱"] --> vault

외부 금고도, 클라우드 계정도 필요 없는 무료 오픈소스입니다.

상태: v0.3.1 (macOS). 금고 CLI, 브라우저 세션 MCP 도구, 치환·마스킹·정책·사용 기록, keyharbor run, Claude Code·Codex 플러그인, 관리 앱, 사람용 자동 완성(확장), ego lite 브라우저 지원이 들어 있습니다(로드맵).

설치

	brew install --cask leeswallow/tap/keyharbor (CLI)
	Releases의 keyharbor-app-<버전>-arm64.dmg를 열어 KeyHarbor.app을 응용 프로그램으로 끌어다 놓기. CLI가 앱 안(Contents/Helpers/keyharbor)에 들어 있습니다. Apple silicon
	keyharbor_<버전>_darwin_<arm64·amd64>.tar.gz를 풀어 keyharbor를 PATH에 두기
	cargo build --release -p keyharbor → target/release/keyharbor

아직 서명·공증하지 않았습니다. Homebrew는 설치할 때 격리 표시를 지웁니다. 직접 받은 CLI나 앱은 처음 한 번 xattr -dr com.apple.quarantine <경로>를 실행하거나, Finder에서 앱을 우클릭 → 열기로 엽니다. 받은 파일은 함께 올린 checksums.txt·.sha256로 확인할 수 있습니다. 설치는 keyharbor --version으로 확인합니다.

시작하기

1. 금고를 만듭니다. 루트 키가 로그인 Keychain에 들어가고, macOS가 확인 창을 띄울 수 있습니다.

keyharbor vault init

2. 로그인 하나를 넣습니다. 값은 숨김 프롬프트나 --stdin으로만 받습니다(명령행 인자로는 받지 않습니다). 관리 앱의 [항목] → [새 항목]에서도 됩니다.

printf '{"username":"me","password":"…"}' | \
  keyharbor vault add github --kind login --origin https://github.com --stdin

비밀 필드에 "해당없음"·"none" 같은 흔한 말이나 4자 미만 값을 넣으면 페이지에서 오탐이 나거나 가려지지 않으므로 항목·필드·이유만 담아 경고합니다(값은 출력하지 않고, 저장은 됩니다).

Chrome에 저장된 비밀번호가 있으면 한 번에 가져올 수 있습니다: Chrome 설정 → 비밀번호 관리자 → 내보내기 → keyharbor vault import-chrome ~/Downloads/passwords.csv.

3. 에이전트를 연결합니다. Claude Code에서:

/plugin marketplace add LeeSwallow/KeyHarbor
/plugin install keyharbor@keyharbor

Codex와 다른 MCP 클라이언트는 docs/plugin.md에 있습니다.

4. 에이전트에게 맡깁니다. "github에 로그인해서 이슈 목록을 가져와"처럼 말하면, 에이전트는 세션을 열고 browser_login {item: "github"}으로 폼을 채웁니다. 에이전트가 모르는 정보(카드, 처음 보는 사이트의 비밀번호)가 필요하면 vault_request로 묻고, 관리 앱의 보안 입력 창에 사람이 답합니다. 에이전트는 값이 아니라 placeholder만 받습니다.

관리 앱

메뉴 막대에 사는 앱입니다. 에이전트가 기다리는 것을 보여 주고, 값은 사람만 보고 넣습니다. 창을 닫아도 메뉴 막대에 남고, 새 요청·인계·draft·거부는 macOS 알림으로 알립니다.

항목	설정
값은 [보기]를 눌러야 30초 동안 보이고, [복사]는 클립보드에 숨김 표시로 넣었다가 설정한 시간 뒤 지웁니다. 검색(⌘F), 이름 바꾸기, 10초 실행 취소가 있습니다	보호를 약하게 하는 변경(기록 끄기, 클립보드 시간 늘리기 등)은 확인 창을 거칩니다

보안 입력 창	명령 팔레트
에이전트의 정보 요청에 답하는 작은 창입니다. 항상 위에 뜨고, 화면 캡처·화면 공유에 보이지 않습니다. 누가·무엇을·왜·어디에 쓰려는지 먼저 보여 줍니다	⌘K로 화면·항목·새 항목을 찾아갑니다. ⌘N은 새 항목입니다

다크 모드도 그대로 따릅니다.

대기 시간과 상한

2단계 인증 앱의 코드도 맡길 수 있습니다. 로그인 항목에 OTP 시드(base32 또는 otpauth:// URI)를 넣고 관리 앱 [설정] → 보안의 "에이전트가 OTP 코드 입력"(또는 keyharbor settings set agent_otp true)을 켜면, 에이전트가 {{otp:github}}을 쓸 때 KeyHarbor가 그 순간의 코드를 그 항목의 사이트에만 넣습니다. 기본은 꺼져 있고 켤 때 확인합니다: 비밀번호와 시드가 한 금고에 있으면 2단계 인증이 사실상 1단계가 되기 때문입니다(보안 백서 §3.8.1). 항목마다 keyharbor vault edit <항목> --otp-allowed off로 끌 수 있습니다.

느린 Mac에서 Chrome 첫 실행이 오래 걸리면 대기 시간을 늘립니다. 관리 앱 [설정] → 고급, 또는 keyharbor settings set <이름> <값>으로 바꿉니다.

설정	무엇	기본	범위	늘리면 확인
session_start_seconds	세션을 열 때 브라우저가 뜨기를 기다리는 시간(초)	15	5–300
session_stop_seconds	세션을 멈출 때 브라우저가 닫히기를 기다리는 시간(초)	15	15–300
browser_endpoint_seconds	--cdp 세션의 CDP 주소를 기다리는 시간(초)	15	5–120
browser_call_seconds	브라우저 명령 하나를 기다리는 시간(초), 새로 여는 세션부터	30	5–90
request_ttl_hours	에이전트의 정보 요청이 만료되는 시간	24	1–168	예
max_drafts	한 이름으로 쌓아 둘 수 있는 draft 수	20	1–100	예

동작 방식

값은 이름으로만 오간다

sequenceDiagram
  participant A as 에이전트
  participant M as keyharbor mcp
  participant G as guard
  participant B as 전용 브라우저
  A->>M: browser_fill {selector, "{{secret:github.password}}"}
  M->>G: 정책 · 항목 상태 · origin 확인
  Note over G: 입력칸의 frame이 github.com일 때만
  G->>B: 진짜 값 입력
  B-->>G: 결과 (페이지 텍스트, 스크린샷 등)
  G-->>A: 값이 placeholder로 가려진 결과

• 평문을 다루는 코드는 keyharbor-guard 한 곳에 있습니다. 에이전트가 쓰는 표면(MCP, CLI)에는 값을 보여 주는 도구나 명령이 없습니다.
• 브라우저는 세션마다 따로 있는 Chrome 프로필이고, 감독 프로세스가 CDP를 소유합니다. 에이전트는 raw CDP를 받지 않습니다(사람이 켤 때만).
• API 키와 .env는 keyharbor run --env myapp -- npm test처럼 자식 프로세스에만 넣고, 그 출력에서 값을 가립니다.

금고는 이렇게 기록된다

저장 위치	들어 있는 것
로그인 Keychain	루트 키 32바이트 하나
~/Library/Application Support/KeyHarbor/keyharbor.sqlite3	값의 암호문, 이름·사이트 같은 메타데이터(평문 + 서명), 세션·요청·정책·사용 기록
…/KeyHarbor/profiles/<세션 id>/	세션마다 전용 Chrome 프로필(쿠키·로그인 상태)

This is the beginning of the README. Read the rest at the original. Read the full README ↗