PI-Desktop 설치하는 법

핵심 요약 (TL;DR)

vastsa/PI-Desktop은 로컬 프로젝트 위에서 AI 코딩 에이전트(목표를 받아 도구를 쓰며 일을 이어 가는 프로그램)를 돌리는 데스크톱 워크스페이스다. 터미널·에디터 확장·호스팅 채팅창이 아니라, 프로젝트·세션·리뷰·프리뷰·모델·권한·확장이 한 창에 모인다. 계정 강제·필수 중계는 없고, 모델 요청은 내가 설정한 제공자로 바로 간다.

이 글은 공식 README·문서에 적힌 바이너리 설치 → 모델 연결 → 첫 프로젝트만 따라간다. Early Preview이고, 글을 쓰는 시점의 최신 릴리스는 v0.14.6(2026-09-10)이다. VRAM 같은 숫자는 문서에 없으면 추정하지 않는다.

배경 및 맥락

코딩 에이전트는 보통 CLI, IDE 플러그인, 또는 클라우드 채팅에 산다. PI-Desktop은 그 워크플로에 자기 창을 준다. 엔진은 pi-mono 계열(pi-ai, pi-agent-core)이고, 데스크톱은 Electron + React UI + Rust Host Core + pi Agent Sidecar로 나뉜다. 하네스(에이전트를 감싸 세션·도구·검증을 묶는 실행 틀)를 “내 머신·내 모델·내 권한”으로 고정하고 싶을 때 후보가 된다.

README는 Local-first · Model-agnostic · Extensible · macOS/Windows/Linux를 내건다. 대화는 로컬 JSONL(+ SQLite 인덱스), 자격 증명은 OS 키체인, PI-Desktop 텔레메트리는 없다고 적혀 있다. 원격 모델을 쓰면 그 요청에 필요한 컨텍스트는 해당 제공자 정책으로 나간다 — “완전 오프라인”이 아니라 로컬 우선이다.

이걸로 할 수 있는 일

• 로컬 프로젝트를 워크스페이스로 열기 — 세션·파일·리뷰·프리뷰를 한곳에 둔다.
• 내 모델 쓰기 — OpenAI·Anthropic·OpenAI 호환 API·게이트웨이·Ollama·LM Studio 등. Composer에서 세션별 모델·추론 수준을 바꾼다.
• Agent / Plan / Goal — 바로 일시키기, 계획 승인 후 실행, 결과·수락 기준만 고정하고 경로를 맡기기.
• 권한 레이어 — 읽기·편집·명령은 가되, 민감한 동작은 승인 경로를 탄다. diff·명령 출력을 Review 패널에서 본다.
• 확장 — Skills(짧은 지침 묶음), MCP(Model Context Protocol, 외부 도구 연결 규약), Subagents, pi extensions, .piplug 플러그인.
• 기존 세션 가져오기 — Claude Code·Codex·OpenCode·Pi 로컬 세션을 Settings → Import로.

필요한 것

일반 사용자는 GitHub Releases 최신 바이너리면 된다. 개발 빌드만 Node/pnpm/Rust가 필요하다.

Windows 릴리스는 SignPath.io / SignPath Foundation 경로로 코드 서명된다고 README에 적혀 있다. macOS 태그 릴리스 기본은 unsigned 아티팩트다.

단계: 바이너리 설치

1. Releases 최신에서 OS·아키텍처에 맞는 파일을 받는다. 이 글 기준 태그는 v0.14.6.
2. macOS — PI-Desktop.app을 /Applications로 옮긴 뒤 연다. “손상됨”·열기 거부가 나오면 README의 unsigned 안내대로 quarantine만 제거한다.

xattr -r -d com.apple.quarantine /Applications/PI-Desktop.app

DMG에는 If app won't open, read this.txt가, ZIP에는 같은 작업을 돕는 PI-Desktop-macOS-open.command가 있다고 문서에 있다. 신뢰할 수 없는 앱에는 쓰지 말 것.

3. Windows — NSIS 설치기 또는 portable .exe. NSIS·Linux AppImage는 앱 안에서 업데이트 다운로드·설치가 가능하다고 적혀 있다.
4. Linux — AppImage/deb/rpm 중 하나. glibc 2.35 미만(Ubuntu 20.04, Debian 11 등)은 번들 호스트를 못 올린다. .asar는 시스템 Electron으로 감싸는 경로용이다.

electron PI-Desktop-<version>-linux-x64.asar

단계: 모델 연결 · 첫 프로젝트

1. Settings → Model configuration에서 제공자 또는 호환 API를 고르고 자격 증명을 넣는다.
2. 사이드바에서 로컬 저장소·프로젝트 폴더를 연다.
3. Agent / Plan / Goal 중 하나를 고른다. Agent는 바로 읽고·고치고·돌리고, Plan은 불변 구현 계획을 만든 뒤 승인 대기, Goal은 목표·수락 기준을 고정하고 경로를 맡긴다. 특권 도구는 모드와 무관하게 권한 레이어를 탄다.
4. 결과가 나오면 Review 패널에서 diff·명령 출력을 보고, 필요하면 프리뷰로 이어간다.

이미 다른 에이전트를 쓰고 있다면 Settings → Import로 Claude Code·Codex·OpenCode·Pi 로컬 세션을 가져올 수 있다.

단계(선택): 소스에서 개발 빌드

문서 Development 절 기준이다. 일상 사용이면 바이너리로 충분하다.

git clone https://github.com/vastsa/PI-Desktop.git
cd PI-Desktop

pnpm install

cargo build -p host-core
pnpm build:js

pnpm dev

검증 명령 예: pnpm typecheck, pnpm lint, pnpm test. 문서 사이트는 pnpm docs:dev.

막히는 지점 / 표

실사용자 반응

확인 가능한 메타만 적는다.

• GitHub 별 ≈ 3,082, 포크 ≈ 236 (조회 시점).
• 최신 태그 v0.14.6 (2026-09-10). 0.14.x 라인에 Agent/Plan/Goal, 권한, Import, MCP/Skills/Subagents, 플러그인 마켓 등이 README Project status에 나열되어 있다.
• 문서 사이트·스크린샷 페이지가 공개되어 있고, README는 Product Hunt 위젯·“계정 없음·릴레이 없음”을 강조한다.
• “쉽다/어렵다” 후기는 공식 README에 인용된 사용자 코멘트가 없어 만들지 않는다.

의미와 시사점

검색창에 “PI-Desktop 설치”를 치는 사람은 보통 모델을 고르는 게 아니라 에이전트 워크플로를 내 디스크에 고정하고 싶다. PI-Desktop은 하네스를 데스크톱으로 끌어올리고, 모델은 교체 부품으로 둔다. Skills·MCP·Subagents가 같은 창에 있으면, TWMS에서 자주 보는 “스킬·하네스·로컬 코딩 에이전트” 흐름과도 맞물린다.

대신 Early Preview다. 서명되지 않은 macOS 빌드, glibc 하한, 플러그인 신뢰 모델은 설치 전에 표로 한 번 보는 편이 안전하다.

마치며

설치는 Releases에서 OS 패키지를 받아 풀고, Settings에서 모델을 붙인 뒤 프로젝트를 열면 된다. macOS는 quarantine, Linux는 glibc 2.35+. 소스로 파고들 때만 Node 22.19+·pnpm·Rust. 오늘 따라갈 명령은 그뿐이다.

출처

• GitHub — vastsa/PI-Desktop
• README (Download · From install to first patch · Development)
• Releases — v0.14.6
• Documentation — pi-docs.aiuo.net
• docs/guide/screenshots.md
• pi-mono (agent engine)

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.