aeyes-local-agent

AeyeStudio AI 채팅이 내 PC의 파일·엑셀·클립보드·앱·셸·화면·마우스·키보드·로컬 DB를 쓸 수 있게 하는 로컬 MCP 에이전트입니다. AeyeStudio 서버가 PC에 접속하지 않습니다 — 크롬의 AeyeStudio 탭이 127.0.0.1의 에이전트에 붙어 요청을 중계합니다.

두 가지 방법으로 실행합니다. 같은 설정 폴더를 쓰므로 둘 중 하나만 실행하세요(동시에 띄우면 두 번째가 거부됩니다).

• 데스크톱 앱(권장): GitHub Releases에서 macOS .dmg / Windows .exe 설치.

• 터미널: npx aeyes-local-agent

데스크톱 앱

설치 후 실행하면 메뉴 막대(macOS)·알림 영역(Windows)에 아이콘이 생깁니다. 처음에는 페어링 코드 창이 뜹니다.

트레이 메뉴:

• 새 기기 연결… — 6자리 코드(5분·1회용). AeyeStudio 설정 > 내 PC 연결에 입력합니다. [코드 복사] 가능.

• 연결된 브라우저 — 연결별 해제, 모두 해제.

• 허용 폴더 — 폴더 열기·목록에서 제거(마지막 하나는 제거 불가)·폴더 추가(루트·홈 자체·홈 상위·설정 폴더를 포함하는 폴더는 불가).

• 항상 허용 — 기록된 범위 보기·하나씩 제거·모두 초기화.

• 이 세션 동안 허용 취소 — 마우스·키보드 세션 허용을 즉시 취소.

• 감사 로그 열기, 로그인 시 자동 실행, 업데이트 확인, 종료. macOS 는 화면 기록·손쉬운 사용 권한 안내.

PC 확인이 필요한 요청은 항상 위에 뜨는 확인 창으로 묻습니다. 창은 포커스를 빼앗지 않고, 버튼은 1초 뒤에 눌리며, 120초 동안 답이 없으면 거부합니다. 버튼: [허용] · [항상 허용 (범위: …)](범위를 좁힐 수 있을 때만) · 이 세션 동안 허용 · [거부]. Esc 는 언제든 [거부]입니다. 창을 띄우지 못하면 거부로 처리합니다.

설치 경고: 서명 인증서 없이 만든 빌드는 macOS 에서 "확인되지 않은 개발자" 경고가 뜹니다(Finder 에서 앱을 Control-클릭 > 열기). Windows 는 SmartScreen 에서 [추가 정보] > [실행]. 이런 빌드는 macOS 자동 업데이트가 적용되지 않습니다.

Related MCP server: Windows Local MCP

터미널 실행

npx aeyes-local-agent

터미널에 표시되는 6자리 코드를 AeyeStudio 설정 > 내 PC 연결에 입력하면 연결됩니다. 실행 중 명령: p 새 코드, u 모든 연결 해제, g 항상 허용 목록 보기, r 항상 허용·세션 허용 모두 지우기, q 종료.

PC 확인 프롬프트에는 매번 새로 뽑은 2자리 코드(10~99)가 보입니다. 코드가 47 이면:

프롬프트가 뜨기 전에 쳐 둔 입력과 뜬 직후 0.3초 안에 들어온 줄은 답으로 보지 않고 버립니다(자동 입력이 미리 쳐 둔 글이 확인을 통과하지 못하게). 그럴 때는 코드를 다시 입력하세요.

옵션: --allow-dir <경로>(허용 폴더 추가), --port <47821-47830>, --config-dir <경로>. 파일시스템 루트, 홈 폴더 자체나 그 상위, 설정 폴더를 포함하는 폴더는 --allow-dir로 줄 수 없습니다(종료 코드 1).

동작 주의사항

• aeyes-local-agent unpair --all, db add, db remove 는 에이전트(터미널·데스크톱 앱) 실행 중에는 거부됩니다(종료 코드 1).

• 같은 설정 폴더로 에이전트를 두 번 띄울 수 없습니다("이미 에이전트가 실행 중입니다(pid N)").

• 터미널 입력이 없는 환경에서는 PC 확인이 필요한 호출이 모두 즉시 거부됩니다. 확인이 10개 넘게 밀려 있으면 새 확인은 즉시 거부됩니다.

도구

"항상 허용"을 고르면 표시된 범위는 다시 묻지 않습니다. 범위는 좁게 잡습니다.

• shell_exec: 명령 첫 단어 단위(예: shell_exec:git). 단 ; & | $ ` ( ) { } < > 문자나 줄바꿈이 들어간 명령, 글롭 문자(* ? [ ])가 들어간 명령, = 대입이 있는 명령, 경로로 시작하는 명령, sudo·env·xargs·bash·powershell·node·python·open 같은 래퍼·인터프리터 명령은 항상 허용할 수 없고 매번 묻습니다. 설정 폴더를 가리키는 명령(설정 폴더 경로·~ 상대 경로·폴더 이름, aeyes-agent(대소문자 무시), config.json 이 들어간 명령 — 따옴표·\ 로 쪼갠 이름 포함)도 이미 항상 허용된 명령이라도 매번 묻습니다. 이 검사는 명령 글자만 봅니다. 경로를 적지 않고 읽는 명령(아래 "보안" 참고)은 잡지 못합니다.

• open_path: 웹 주소(http/https)만 open_path:url 로 항상 허용할 수 있습니다. 파일·폴더 열기는 매번 묻고, 실행 파일·실행기 형식(.app, .exe, .bat, .sh, .command, .lnk 등)은 열지 않습니다.

• open_app: 인자 없이 실행할 때만 앱 이름 단위로 항상 허용할 수 있습니다.

• 마우스·키보드와 db_query 쓰기는 항상 허용할 수 없습니다.

화면·마우스·키보드 도구

• 선택 구성요소(@nut-tree-fork/nut-js, screenshot-desktop)를 쓰며, 설치·로드에 실패한 PC 에서는 이 도구들만 나타나지 않습니다(터미널에 안내가 나옵니다).

• 이 세션 동안 허용: 마우스·키보드 확인 창에서 고르면 같은 브라우저 연결에서 60분 동안(또는 에이전트 종료·트레이 "이 세션 동안 허용 취소"·터미널 r 까지) 다시 묻지 않습니다. 설정 파일에는 저장되지 않습니다.

• PC 확인 창이 떠 있는 동안에는 마우스·키보드 도구가 busy 로 거부되고, 마우스·키보드 동작 중에 온 확인은 동작이 끝나고 1초가 더 지난 뒤에 뜹니다(자동 입력이 확인 창을 누르지 못하게).

• keyboard_type 은 한 번에 최대 500자입니다. 마우스·키보드 동작이 30초 안에 끝나지 않으면 timeout 으로 실패하고, 그 동작이 실제로 끝날 때까지(최대 60초) 새 PC 확인은 띄우지 않고 즉시 거부합니다(감사 로그에 denied).

• 좌표는 논리 픽셀입니다. keyboard_press 키: a-z, 0-9, f1-f12, enter, escape, tab, space, backspace, delete, 방향키, home, end, pageup, pagedown, shift, control, alt, meta(macOS Cmd·Windows Win).

macOS 권한

시스템 설정 > 개인정보 보호 및 보안에서 켜야 합니다(데스크톱 앱은 "AeyeStudio Agent", 터미널 실행은 사용 중인 터미널 앱).

• 화면 기록 — screenshot. 없으면 창 없이 배경만 찍힐 수 있습니다.

• 손쉬운 사용 — 마우스·키보드 도구. 없으면 동작하지 않습니다.

권한을 켠 뒤에는 앱(또는 터미널)을 다시 시작하세요. 데스크톱 앱은 첫 실행 때 안내하고, 트레이 메뉴에서 다시 볼 수 있습니다.

로컬 DB 조회(db_query)

PostgreSQL·MySQL 을 지원합니다. 에이전트를 종료한 상태에서 등록합니다.

npx aeyes-local-agent db add shop --kind postgres        # 읽기 전용(기본)
npx aeyes-local-agent db add erp --kind mysql --read-write
npx aeyes-local-agent db list
npx aeyes-local-agent db remove shop

• 연결 문자열(postgres://사용자:비밀번호@호스트:5432/DB, mysql://사용자:비밀번호@호스트:3306/DB)은 명령 인자로 받지 않고 실행 후 입력받습니다(화면에 보이지 않음). 설정 파일(권한 0600, 폴더 0700)에만 저장되고 도구 설명·결과·오류·목록·감사 로그에 나오지 않습니다.

• 모든 도구 결과(예: shell_exec 출력)에서 등록된 연결 문자열과 그 비밀번호는 *** 로 가려집니다. 다만 연결 문자열은 아직 운영체제 키체인이 아니라 설정 파일에 있으므로, 설정 폴더를 읽는 명령은 확인 창에서 거부하세요.

• 데스크톱 앱 사용자도 이 명령으로 등록합니다(앱을 종료한 뒤 실행, 다시 앱 실행).

• 읽기 전용 DB: SELECT·WITH·VALUES·TABLE·SHOW·EXPLAIN·DESCRIBE 같은 읽기만 실행합니다. 데이터 변경 CTE, SELECT … INTO, EXPLAIN ANALYZE, nextval·pg_terminate_backend·load_file 같은 부작용 함수, 여러 문장, MySQL 실행 주석(/*! */)은 거부합니다. 읽기는 DB 의 읽기 전용 트랜잭션 안에서 실행합니다.

• 읽기·쓰기 DB: 쓰기 쿼리는 매번 PC 에서 확인합니다(항상 허용 없음).

• 결과는 최대 1000행(기본 200)·약 60KB, 타임아웃 기본 30초(최대 120초), 연결 10초.

• MySQL 은 타임아웃이 나면 에이전트가 기다리기를 멈추고 연결을 닫지만, 서버 쪽 쓰기(특히 COMMIT 도중)는 멈추지 않고 끝까지 반영될 수 있습니다. 쓰기 결과가 timeout 이면 DB 에서 실제 반영 여부를 확인하세요.

• 가장 안전한 방법은 읽기 전용 DB 계정을 만들어 등록하는 것입니다.

보안

• 127.0.0.1에만 열리고, Host가 127.0.0.1/localhost가 아니면 거부합니다(DNS 리바인딩 방어).

• https://studio.aeyes.dev, https://seller-ai-studio.vercel.app에서 온 요청만 받습니다.

• 페어링 토큰은 해시로만 저장합니다. 코드는 5분·1회용, 5회 실패 시 10분 잠금.

• 파일 도구는 허용 폴더(기본 ~/Documents/AeyeStudio, Windows 는 OneDrive 문서 폴더가 있으면 그 아래) 밖을 거부합니다. 심볼릭 링크는 실제 경로 기준으로 검사하고, 끊어진 링크는 거부합니다. 설정 폴더는 허용 폴더 안에 있어도 접근할 수 없습니다.

• 확인 프롬프트·확인 창은 원격에서 온 글의 제어 문자를 보이는 형태로 바꿔 표시합니다(요약 500자까지, 길면 앞뒤를 함께 표시).

• 설정·감사 로그 위치: macOS/Linux ~/.aeyes-agent/, Windows %APPDATA%\aeyes-agent\.

• 모든 도구 호출은 설정 폴더의 audit.log에 남습니다(파일 내용·클립보드·입력한 글·DB 결과 제외, SQL 은 앞 120자).

• 알려진 한계 — shell_exec 항상 허용과 설정 폴더: 설정 폴더(페어링 해시·DB 연결 문자열)를 가리키는 명령을 걸러 내는 검사는 명령 글자를 비교할 뿐입니다. grep -r password ~ 나 find ~ -name … 처럼 경로를 직접 적지 않고 홈 폴더를 재귀로 읽는 명령, 환경에 따라 달라지는 경로는 글자 비교로 잡을 수 없습니다. 그러니 grep·cat·find 같은 범용 읽기 명령은 항상 허용하지 말고, 범위가 좁고 결과를 예측할 수 있는 명령만 항상 허용하세요. 확인 창에서는 명령 전체를 읽고, 홈 폴더나 설정 폴더를 건드릴 수 있으면 거부하세요.

• 알려진 한계 — shell_exec 항상 허용과 확인 창: shell_exec를 특정 명령으로 "항상 허용" 해 두면, 그 명령으로 실행된 프로세스가 스스로 입력을 합성해(예: macOS osascript/System Events, Windows SendInput) 화면 위의 확인 창 버튼을 클릭할 수 있습니다. 확인 창 자체는 이런 종류의 공격까지 막지는 못합니다. 그러니 shell_exec는 항상 허용 범위를 최대한 좁은 명령으로만 잡으세요(예: 특정 조회 스크립트 하나) — 범용 셸이나 인터프리터를 항상 허용하지 마세요.

저장소 구조

aeyes-local-agent/
├── .github/workflows/ci.yml       # CI(core·desktop 테스트, 실제 DB 통합 테스트)
├── .github/workflows/release.yml  # v* 태그 → 데스크톱 앱 빌드·GitHub Release 초안·npm 배포
├── packages/core/                 # aeyes-local-agent (npm 패키지)
│   ├── src/
│   │   ├── cli.ts, dbCli.ts, secretInput.ts   # 진입점·db 명령
│   │   ├── server.ts, mcp.ts                  # HTTP 서버·요청별 MCP 서버
│   │   ├── terminal.ts                        # 터미널 확인 프롬프트
│   │   ├── config.ts, paths.ts, pidFile.ts, audit.ts
│   │   ├── native.ts                          # 화면·입력 드라이버(선택 의존성)
│   │   ├── db/                                # SQL 판별·pg/mysql 드라이버
│   │   ├── policy/                            # 확인 게이트·항상/세션 허용
│   │   ├── security/                          # 페어링·Origin·속도 제한
│   │   └── tools/                             # 21개 도구
│   └── test/
├── packages/desktop/              # Electron 트레이 앱(aeyes-agent-desktop)
│   ├── src/main.ts                # Electron 셸(나머지 모듈은 단위 테스트)
│   ├── static/                    # 확인 창 렌더러·preload
│   ├── builder/config.cjs         # electron-builder 설정
│   └── test/
├── package.json
├── pnpm-workspace.yaml
└── README.md

릴리스(관리자)

1. packages/core/package.json, packages/core/src/version.ts, packages/desktop/package.json 버전을 같은 값으로 올리고 커밋.

2. git tag v<버전> && git push origin v<버전> → release 워크플로가 macOS(dmg+zip, universal)·Windows(NSIS x64)를 빌드해 GitHub Release 를 초안(draft) 으로 만들고, NPM_TOKEN 시크릿이 있으면 npm-release 환경 승인 뒤 core 를 npm 에 배포합니다(provenance 포함).

3. 관리자가 GitHub Releases 에서 초안의 파일·노트를 확인한 뒤 직접 게시(Publish release) 합니다. 게시하기 전에는 다운로드 링크와 데스크톱 앱 자동 업데이트에 나타나지 않습니다. npm 배포 잡은 npm-release 환경 뒤에 있어 승인 전에는 배포되지 않습니다. 저장소 Settings > Environments 에서 npm-release 환경을 만들고 Required reviewers(관리자)를 지정해야 합니다 — 환경을 만들지 않으면 GitHub 가 보호 규칙 없이 자동으로 만들어 태그만 밀어도 바로 배포됩니다. NPM_TOKEN 은 이 환경의 시크릿(또는 저장소 시크릿)으로 두고, 토큰은 배포 단계에만 전달됩니다. 워크플로 권한은 기본 읽기 전용이고, Release 를 만드는 잡만 contents: write 를 받습니다. 체크아웃은 자격 증명을 남기지 않고(persist-credentials: false), softprops/action-gh-release 는 커밋 SHA 로 고정되어 있습니다.

4. 서명 시크릿(없으면 미서명 빌드 + 경고): MAC_CSC_LINK, MAC_CSC_KEY_PASSWORD(Developer ID 인증서 p12 base64·암호), APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID(공증), WIN_CSC_LINK, WIN_CSC_KEY_PASSWORD(Windows 코드 서명).

5. 데스크톱 앱은 electron-updater 로 GitHub Releases 의 (게시된) 새 버전을 6시간마다 확인합니다.