<p align="center">
  <img src="docs/assets/hero.webp" alt="Personal Device Agent private device orchestration" width="100%" />
</p>

<h1 align="center">Personal Device Agent</h1>

<p align="center">
  <strong>대화 한마디를, 승인 가능한 안전한 PC 작업으로.</strong><br />
  여러 Windows 장치를 비공개 Tailscale 네트워크에서 연결하는 오픈소스 MCP 에이전트
</p>

<p align="center">
  <a href="https://github.com/kyj2294/personal-device-agent/actions/workflows/ci.yml"><img src="https://github.com/kyj2294/personal-device-agent/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
  <a href="https://github.com/kyj2294/personal-device-agent/releases"><img src="https://img.shields.io/github/v/release/kyj2294/personal-device-agent?include_prereleases&style=flat-square&color=35c7e8" alt="Release" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-5b7694?style=flat-square" alt="Apache 2.0" /></a>
  <img src="https://img.shields.io/badge/Windows-10%20%7C%2011-1673c9?style=flat-square&logo=windows11" alt="Windows 10 and 11" />
  <img src="https://img.shields.io/badge/Node.js-%E2%89%A520-3c873a?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js 20 or newer" />
  <img src="https://img.shields.io/badge/MCP-compatible-ff7e6b?style=flat-square" alt="MCP compatible" />
</p>

<p align="center">
  <a href="#60초-설치"><strong>빠른 설치</strong></a> ·
  <a href="#어떻게-동작하나요">동작 구조</a> ·
  <a href="#위험도-기반-승인">보안 모델</a> ·
  <a href="docs/tailscale-setup.md">Tailscale 설정</a> ·
  <a href="README.en.md">English</a>
</p>

---

Personal Device Agent는 Codex 같은 MCP 클라이언트에서 등록된 개인 Windows PC를 확인하고
조작하게 해줍니다. 모델에 셸 전체를 넘기지 않습니다. 허용된 작은 도구만 공개하고, 파일 변경·
화면 캡처·키보드와 마우스 입력 같은 작업은 **장치, 명령, 인자가 정확히 일치하는 승인**을
받아야 실행됩니다.

> [!IMPORTANT]
> 현재 `v0.1.0-alpha.3`는 개인용 개발자 미리보기입니다. 조작 대상은 Windows 10/11이며,
> 원격 연결은 Tailscale Serve를 사용하는 비공개 tailnet 안에서만 지원합니다. Funnel과 공용
> 인터넷 노출은 지원하지 않습니다.

## 왜 만들었나요?

| 일반적인 PC 자동화 | Personal Device Agent |
|---|---|
| 모델에 셸이나 데스크톱 전체 권한 부여 | 기능이 제한된 MCP 도구만 공개 |
| 실행 직전 무엇이 바뀌는지 불명확 | 장치·작업·인자를 보여주고 정확히 승인 |
| 원격 포트를 공용 인터넷에 노출 | Tailscale의 비공개 HTTPS만 사용 |
| 여러 장치가 하나의 모호한 연결로 섞임 | `pda-office-pc`처럼 장치별 이름으로 등록 |
| 실행 기록을 나중에 확인하기 어려움 | 각 장치에 민감 정보가 제거된 감사 로그 저장 |

## 60초 설치

필요한 것은 [Node.js 20 이상](https://nodejs.org/),
[Python 3.11 이상](https://www.python.org/downloads/windows/),
[Git for Windows](https://git-scm.com/download/win),
[Tailscale](https://tailscale.com/download/windows), 그리고 Windows 10/11입니다. Tailscale에
로그인한 뒤 **제어할 PC의 PowerShell**에서 실행하세요.

```powershell
npm install --global github:kyj2294/personal-device-agent
pda install
```

이 명령은 npm을 통해 최신 GitHub 패키지를 받아 사용자 전용 경로에 안정적으로 설치하고,
Python 가상환경·Windows 자동 시작·Codex 플러그인·비공개 Tailscale HTTPS 주소를 설정한 뒤
실제 MCP 연결까지 검사합니다. 관리자 권한은 필요하지 않습니다.

로컬에서만 쓰려면:

```powershell
pda install --local
```

설치 후 Codex에서 **새 작업**을 열고 말해보세요.

```text
이 PC의 연결 상태와 사용할 수 있는 기능을 보여 줘.
메모장을 열어 줘.
현재 창 목록을 확인해 줘.
```

변경 작업은 곧바로 실행되지 않고 승인 요청이 먼저 나타나는 것이 정상입니다.

## 여러 PC 연결하기

각 Windows PC에서 `install`을 실행하면 다음 형태의 비공개 주소가 출력됩니다.

```text
https://device-name.example.ts.net:9443/mcp
```

대화할 PC에서 장치 이름과 주소를 등록합니다.

```powershell
pda connect `
  --name office-pc `
  --endpoint https://office-pc.example.ts.net:9443/mcp
```

등록 전에 HTTPS 주소 형식과 실제 MCP 도구 목록을 검사합니다. 이후에는 다음처럼 대상을 분명히
지정할 수 있습니다.

```text
office-pc에서 메모장을 열어 줘.
home-pc의 CPU와 메모리 상태를 확인해 줘.
office-pc의 Downloads 폴더 파일을 보여 줘.
```

## CLI

전역 npm 패키지를 설치한 다음부터는 짧은 `pda` 명령을 사용할 수 있습니다. npm 패키지를
업데이트한 뒤 `pda install`을 다시 실행하면 안정적인 버전별 배포 경로와 자동 시작 항목도 함께
갱신됩니다.

| 명령 | 설명 |
|---|---|
| `pda install` | 설치 또는 현재 npm 버전으로 업데이트 |
| `pda install --local` | Tailscale 원격 주소 없이 로컬 전용 설치 |
| `pda connect --name NAME --endpoint URL` | 원격 장치를 Codex에 이름으로 등록 |
| `pda list` | 등록된 Personal Device Agent 장치만 표시 |
| `pda disconnect --name NAME` | Codex에서 장치 연결 해제 |
| `pda status` | 에이전트·Tailscale·Serve 상태 확인 |
| `pda enable-remote` | 비공개 원격 주소 활성화 및 MCP 검사 |
| `pda disable-remote` | 전용 `9443` Serve 경로만 비활성화 |
| `pda emergency-stop` | 모든 중·고위험 작업 즉시 정지 |

npm Registry 게시가 끝나면 GitHub 주소 없이 다음처럼 더 짧게 설치할 수 있습니다.

```powershell
npm install --global personal-device-agent
pda install
```

## 어떻게 동작하나요?

<p align="center">
  <img src="docs/assets/architecture.svg" alt="Conversation to Windows action architecture flow" width="100%" />
</p>

1. Codex가 선택한 장치의 제한된 MCP 도구를 호출합니다.
2. 원격 요청은 Tailscale의 비공개 HTTPS `:9443` 연결로만 전달됩니다.
3. 장치 내부 정책 엔진이 위험도와 정확한 인자를 독립적으로 검사합니다.
4. 승인이 필요한 작업은 사용자가 허용한 뒤에만 한 번 실행됩니다.
5. 결과와 승인 기록은 민감 내용을 제거해 해당 장치에 로컬 저장됩니다.

백엔드는 원격 사용 중에도 `127.0.0.1:9472`에만 바인딩됩니다. Tailscale Serve가 tailnet에서
허용된 HTTPS 요청만 전달하며, 기존 `443` Serve 설정은 변경하지 않고 전용 `9443`만 사용합니다.

## 위험도 기반 승인

| 위험도 | 대표 작업 | 처리 방식 |
|:---:|---|---|
| **LOW** | 상태·기능·창·파일 목록, 긴급 정지 | 즉시 실행 |
| **MEDIUM** | 앱/URL 열기, 화면 캡처, 파일 읽기·쓰기, 텍스트 입력 | 정확한 작업 승인 필요 |
| **HIGH** | 좌표 클릭, 휴지통 이동, 긴급 정지 해제 | 강화된 정확한 작업 승인 필요 |
| **BLOCKED** | 임의 셸, 자격 증명, 보안 해제, 영구 삭제, 결제 | 도구 자체를 제공하지 않음 |

승인은 장치·작업명·모든 인자의 SHA-256 지문에 묶입니다. 5분 후 만료되며 한 번만 사용할 수
있습니다. 경로, 좌표, 입력 내용 중 하나라도 달라지면 새 승인이 필요합니다.

## 제공 도구

<details>
<summary><strong>현재 제공되는 20개 MCP 도구 보기</strong></summary>

| 영역 | 도구 |
|---|---|
| 장치 | `setup_status`, `device_capabilities`, `system_status`, `remote_status` |
| 화면·앱 | `window_list`, `app_launch`, `browser_open`, `screen_capture` |
| 입력 | `input_type`, `input_click` |
| 파일 | `file_list`, `file_read`, `file_write`, `file_trash` |
| 안전 | `safety_status`, `safety_pause`, `safety_resume` |
| 승인·감사 | `approval_grant`, `approval_reject`, `audit_list` |

</details>

## 데이터 경계

- 에이전트: `127.0.0.1:9472`에서만 수신
- 원격 전송: Tailscale Serve `HTTPS :9443`
- 장치 키: 현재 Windows 사용자 계정의 DPAPI로 보호
- 기본 파일 범위: Desktop, Documents, Downloads
- 런타임 데이터: `%LOCALAPPDATA%\PersonalDeviceAgent\PersonalDeviceAgent`
- npm 배포본: `%LOCALAPPDATA%\PersonalDeviceAgent\distributions\<version>`
- 금지: Funnel, 공유기 포트포워딩, `0.0.0.0` 바인딩

더 엄격한 tailnet Grants 설정은 [Tailscale 설정 안내](docs/tailscale-setup.md), 상세한 신뢰
경계는 [위협 모델](docs/threat-model.md)을 참고하세요.

## 모바일과 지원 범위

Tailscale은 iPhone과 Android를 tailnet 피어로 연결할 수 있습니다. 하지만 현재 **조작 대상
에이전트는 Windows용**입니다. 휴대폰에서 Windows PC를 대화로 조작하려면 사용하는 대화 앱이
사용자 지정 비공개 MCP 주소를 지원해야 합니다. Tailscale 모바일 앱만 설치하면 Codex 모바일에
MCP가 자동 등록되는 구조는 아닙니다.

| 기능 | 상태 |
|---|:---:|
| Windows 10/11 로컬 제어 | ✅ |
| Tailscale을 통한 Windows PC 원격 제어 | ✅ |
| 여러 Windows PC 이름별 등록 | ✅ |
| npm/npx 설치 CLI | ✅ |
| iOS/Android 자체 조작 에이전트 | 계획 |
| 모바일·클라우드용 호스팅 게이트웨이 | 계획 |
| 서명된 Windows 설치 파일·자동 업데이트 | 계획 |
| 공공기관 운영 환경 | 기관별 보안성 검토 필요 |

## 개발

```powershell
git clone https://github.com/kyj2294/personal-device-agent.git
cd personal-device-agent

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest

npm test
npm run pack:check
```

기여 방법은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요. 보안 취약점은 공개 이슈 대신
[GitHub Security Advisory](https://github.com/kyj2294/personal-device-agent/security/advisories/new)로
알려 주세요.

## 라이선스

[Apache License 2.0](LICENSE) © kyj2294