Personal Device Agent

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

왜 만들었나요?

Related MCP server: Knossos

60초 설치

필요한 것은 Node.js 20 이상, Python 3.11 이상, Git for Windows, Tailscale, 그리고 Windows 10/11입니다. Tailscale에 로그인한 뒤 제어할 PC의 PowerShell에서 실행하세요.

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

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

로컬에서만 쓰려면:

pda install --local

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

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

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

여러 PC 연결하기

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

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

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

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

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

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

CLI

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

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

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

어떻게 동작하나요?

1. Codex가 선택한 장치의 제한된 MCP 도구를 호출합니다.

2. 원격 요청은 Tailscale의 비공개 HTTPS :9443 연결로만 전달됩니다.

3. 장치 내부 정책 엔진이 위험도와 정확한 인자를 독립적으로 검사합니다.

4. 승인이 필요한 작업은 사용자가 허용한 뒤에만 한 번 실행됩니다.

5. 결과와 승인 기록은 민감 내용을 제거해 해당 장치에 로컬 저장됩니다.

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

위험도 기반 승인

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

제공 도구

데이터 경계

• 에이전트: 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 설정 안내, 상세한 신뢰 경계는 위협 모델을 참고하세요.

모바일과 지원 범위

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

개발

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를 참고하세요. 보안 취약점은 공개 이슈 대신 GitHub Security Advisory로 알려 주세요.

라이선스

Apache License 2.0 © kyj2294