pi-hosts

Pi 코딩 에이전트에게 서버 접근 권한을 부여하세요.

pi-hosts는 Pi에게 이름이 지정된 SSH 대상(targets), 호스트 정보(host facts), 연결 재사용(connection reuse), 명령 위험 체크(command risk checks), 그리고 감사 추적(audit trail) 기능을 제공합니다.

web-1에서 docker 버전 확인해줘
api-1이 정상(healthy)이야?
web-1과 web-2의 디스크 사용량 비교해줘
...

존재 이유

Pi는 종종 스스로 ssh web-1 'command'를 추론할 수 있습니다. 이는 단순한 일회성 작업에는 작동하지만, 반복적인 작업이나 조사 과정에서는 취약해질 수 있습니다.

pi-hosts를 사용하면 Pi는 다음과 같은 기능을 얻습니다:

• 호스트 이름, 별칭(aliases), 태그(tags)를 통한 예측 가능한 대상 확인(target resolution)
• OS, 배포판(distro), 패키지 관리자(package manager), 서비스 관리자(service manager), Docker, sudo와 같은 캐싱된 호스트 정보(host facts)
• 원격 명령이 실행되기 전 위험 분류(risk classification)를 통한 보호된 실행
• Pi가 SSH 세부 정보를 다시 찾는 대신 유형화된 호스트 도구(typed host tools)를 호출하므로 반복적인 워크플로우에서 토큰 소모(token burn) 감소
• 도구 호출 횟수 감소 및 OpenSSH 연결 멀티플렉싱(connection multiplexing)을 통한 빠른 워크플로우 (최대 10분 동안 마스터 연결 재사용)
• 편의성: SSH 세부 정보를 일일이 나열하는 대신 web-1이라고 말하거나, 업그레이드, 상태(health), 트래픽 또는 장애(incidents) 확인 시 database servers 또는 prod라고 요청 가능
• 명령, 호스트, 정책 결정, 종료 코드(exit code), 지속 시간(duration), 타임아웃(timeout), 잘림(truncation)에 대한 JSONL 감사 기록(audit records)

web-1에서 Docker 버전 확인 프롬프트에 대한 측정 예시:

설치

pi install npm:pi-hosts

그 다음 Pi를 재시작하거나 /reload를 실행하세요.

퀵스타트 (Quickstart)

자연어를 사용하세요:

내 SSH 설정에서 모든 호스트를 가져와줘
10.0.0.12의 web-1을 deploy로 추가하고 web, prod 태그를 달아줘
10.0.0.20의 db-1을 deploy로 추가하고 database, prod 태그를 달아줘
...

또는 슬래시 명령어를 직접 사용하세요:

/hosts import ssh --all
/hosts list
/hosts upsert web-1 --address 10.0.0.12 --user deploy --port 22 --tags web,prod
...

호스트가 추가되면:

web-1에서 uptime 실행
모든 데이터베이스 서버의 facts 갱신
prod에서 실패한 서비스 확인

~/.ssh/config는 오직 가져오기(import) 소스로만 사용됩니다. 가져온 후, pi-hosts는 자체 인벤토리(inventory)를 ~/.pi/agent/extensions/pi-hosts/hosts.json에 저장합니다.

명령어 (Commands)

대상 식별 (Target Resolution)

사용자는 다음과 같은 방식으로 호스트를 참조할 수 있습니다:

• 이름 (name): web-1
• 별칭 (alias): frontend-1
• 태그 (tag): database, prod, web
• 명시적 호스트 마커 (explicit host marker): #web-1

대부분의 프롬프트(prompt)에서는 일반 이름을 사용하는 것이 좋습니다:

web-1에서 docker 버전 확인
모든 데이터베이스 서버 확인

#web-1은 호스트 언급을 모호하지 않게 만들고 싶을 때 사용할 수 있는 선택적인 탈출구(escape hatch)입니다:

#web-1 확인

식별(Resolution)은 퍼지(fuzzy) 방식이 아닌 정확한(exact) 방식입니다. 호스트에 database 태그가 붙어 있다면 check all database servers가 작동하며, 호스트에 db 태그가 붙어 있다면 check all db servers가 작동합니다.

실행은 내부적으로 명시적인 상태를 유지합니다. Pi가 자연어로부터 대상을 추론할 수는 있지만, host_exec는 구체적인 호스트 ID를 전달받습니다.

아키텍처 (Architecture)

pi-hosts는 몇 가지 작은 구성 요소로 이루어져 있습니다:

• Inventory (인벤토리): 이름, 별칭(alias), 태그, SSH 전송 필드, 메타데이터 및 캐시된 팩트(facts)를 포함하는 정형화된 JSON 호스트 저장소입니다.
• Import (임포트): ~/.ssh/config로부터 단방향으로 가져옵니다. 와일드카드 기본값이 적용되지만, SSH 설정은 실시간 상태(live state)가 아닙니다.
• Resolution (해결): 사용자의 프롬프트는 정확한 이름, 별칭, 명시적 호스트 마커 또는 태그를 통해 명시적인 호스트 ID로 해결됩니다. Target Resolution을 참조하세요.
• Facts (팩트): 원격 프로브(remote probes)가 OS, 커널, 배포판(distro), 패키지 관리자, 서비스 관리자, 컨테이너 런타임 및 sudo 사용 가능 여부를 캐시합니다.
• Policy (정책): 셸 명령은 safe (안전), caution (주의), danger (위험) 또는 critical (치명적)로 분류됩니다. 기본값인 balanced (균형) 정책은 안전/주의 명령을 실행하고, 위험 명령은 확인을 거치며, 치명적 명령은 차단합니다. Policy Config를 참조하세요.
• Transport (전송): 단발성 명령은 ControlMaster=auto 및 ControlPersist=10m 설정이 적용된 OpenSSH를 사용하며, 대화형 세션은 확장 프로그램 내에서 SSH 프로세스를 열린 상태로 유지합니다.
• Audit (감사): 원격 실행 기록은 ~/.pi/agent/extensions/pi-hosts/audit.jsonl에 JSONL 레코드로 추가됩니다.

Host Inventory (호스트 인벤토리)

최소 호스트 파일:

{
  "version": 1,
  "hosts": []
...

호스트 형태:

{
  "id": "web-1",
  "name": "web-1",
...

Policy Config (정책 설정)

원격 명령은 실제 머신을 조사, 변경 또는 파괴할 수 있습니다. 기본 balanced 모드는 일상적인 읽기 작업을 실행하고, 위험한 쓰기 작업 전에는 확인을 요청하며, 치명적인 명령은 차단합니다.

safe      run
caution   run
danger    confirm
...

예시:

docker --version              run
docker ps                     run
docker restart app            confirm
...

설정 파일:

./.pi/pi-hosts/config.json
~/.config/pi-hosts/config.json

최소 설정:

{
  "policy": {
    "approval": "balanced",
...

승인 모드:

Development (개발)

pnpm check
pnpm test
npm pack --dry-run