본문 바로가기
이지티켓

agent-desktop, 코딩 에이전트에게 데스크톱 앱 조작을 맡길 때 알아 둘 것

이지티켓
발행일:
Contents

클로드 코드에게 맥 앱을 만들어 달라고 하면 코드는 금방 나와요. 그런데 설정 화면의 버튼이 정말 눌리는지는 결국 사람이 앱을 열어 하나씩 눌러 봐야 알죠. agent-desktop은 Vercel Labs가 2026년 10월 31일 공개한 무료 오픈소스 CLI로, 클로드 코드·코덱스 같은 코딩 에이전트가 맥·윈도우·리눅스의 데스크톱 앱을 운영체제 접근성 트리로 읽고 직접 조작하게 해 줘요. 라이선스는 Apache-2.0이고, 그 버튼 누르기를 에이전트에게 넘기는 도구인 셈이에요.

공개 글에서 Vercel의 Chris Tate는 이 도구를 “agent-browser, for your whole computer”라고 소개했어요. 브라우저 안에서 하던 일을 컴퓨터 전체로 넓혔다는 뜻이죠. 2026년 11월 2일 기준 GitHub 별은 6,833개예요.

화면 대신 구조를 읽는 도구

AI가 컴퓨터를 쓰는 방식은 크게 두 갈래예요. 화면을 찍어 보고 어디를 누를지 좌표로 짐작하는 방식, 그리고 앱이 운영체제에 알려 주는 구조를 읽는 방식이죠. agent-desktop은 뒤쪽이에요. 접근성 트리는 원래 화면 낭독기 같은 보조 기술을 위해 앱이 내놓는 “이 창에는 이런 버튼과 입력칸이 있다”는 목록이거든요.

명령 하나를 부르면 앱의 그 목록을 JSON으로 돌려주고, 누를 수 있는 요소마다 ref라는 꼬리표를 붙여요. 에이전트는 그 꼬리표를 골라 누르고, 다시 목록을 읽어 결과를 확인해요. 픽셀 매칭은 하지 않아요.

GitHub vercel-labs/agent-desktop 저장소 첫 화면. 소개 문구와 별 6.8k, Apache-2.0 라이선스 표시
저장소 첫 화면. 소개 문구에 픽셀로 짐작하지 않는다는 말이 먼저 나와요.

중요한 점은 이 도구 안에 AI 모델이 없다는 거예요. 공식 문서도 “에이전트가 부르는 도구이지 에이전트가 아니다”라고 적어 두었어요. 그래서 클로드 코드든 코덱스든 쓰던 에이전트에 붙이면 되고, 특정 모델에 묶이지 않아요. 프로젝트는 개발자 Lahfir가 2026년 2월에 시작했고 나중에 Vercel Labs 아래로 옮겨졌어요. 리눅스 지원을 더한 1.0이 10월 28일, 최신판 1.0.2가 10월 30일에 나왔어요.

기본은 헤드리스 모드라서 에이전트가 앱을 누르는 동안 내 마우스 포인터가 움직이거나 창 포커스를 빼앗기지 않아요. 사람은 다른 일을 하고 에이전트는 뒤에서 앱을 만지는 그림이에요. 실제 마우스·키보드 입력이 필요하면 --headed 플래그를 따로 줘야 해요.

언제 쓰면 좋고, 언제 안 맞을까

잘 맞는 상황은 세 가지로 좁혀져요.

직접 만든 데스크톱 앱을 확인할 때. 바이브코딩으로 맥 앱이나 일렉트론 앱을 만들었다면 가장 쓸모가 커요. 에이전트가 코드를 고친 다음 앱을 열고, 버튼을 누르고, 바뀐 값을 읽어 오는 데까지 혼자 할 수 있거든요. 사람은 결과만 보면 돼요.

API가 없는 데스크톱 앱에서 같은 일을 반복할 때. 설정 몇 개를 매번 바꾸거나, 같은 메뉴를 여러 번 거쳐야 하는 작업이 여기에 들어가요. 다만 리뷰를 쓴 Flavio Copes에 따르면 set-value 명령은 화면 속 컨트롤 값만 바꾸고 저장된 파일까지 바꾸진 않아요. 저장까지 시켜야 한다는 뜻이죠.

내가 일하는 동안 뒤에서 돌려 둘 때. 헤드리스 기본값 덕분에 화면을 비켜 줄 필요가 없어요. Chris Tate의 소개 글은 에이전트마다 자기 커서를 써서 여러 개가 함께 일할 수 있다는 점도 내세웠어요.

반대로 안 맞는 경우도 분명해요. 웹 페이지 자동화는 처음부터 다루지 않아요. 공식 문서가 그 일은 자매 도구 agent-browser에 맡기라고 적어 두었어요. 접근성 트리를 내놓지 않는 화면도 못 봐요. 캔버스로 직접 그리는 게임이나 그림 도구 같은 앱이 대표적이에요. 픽셀을 보지 않으니 구조를 알려 주지 않는 화면은 아예 보이지 않는 셈이에요.

agent-browser.dev/desktop 문서의 agent-desktop 소개 화면과 할 수 있는 일, 못 하는 일 목록
공식 문서는 첫 화면에서 모델이 들어 있지 않다는 점, 웹 페이지는 다루지 않는다는 점부터 밝혀요.

크로미움·일렉트론 앱은 중간 지대예요. 앱의 창이나 메뉴 같은 네이티브 부분은 agent-desktop이 읽고, 안에 들어 있는 웹 화면은 DevTools 포트를 열어 agent-browser와 이어 쓰라고 문서가 안내해요.

agent-desktop 시작하는 법, AI에게 맡길 부분

준비물은 Node.js 패키지 관리자(npm, Bun, Yarn, pnpm 중 하나)와 운영체제 권한이에요. GPU나 API 키는 필요 없어요. README에 적힌 설치 명령은 이 두 줄이 전부예요.

npm install -g agent-desktop
agent-desktop version

-g 없이 설치했다면 npx agent-desktop으로 부르면 돼요. Homebrew와 Scoop 공식 패키지는 2026년 11월 2일 기준 아직 심사 중이에요.

agent-desktop README의 설치 절. npm install -g agent-desktop 명령과 운영체제별 권한 안내
README 설치 절. npm 두 줄과 운영체제별 권한 안내가 전부예요.

권한은 운영체제마다 달라요. 맥은 시스템 설정의 손쉬운 사용 권한이 필요하고, 스크린샷까지 쓰려면 화면 기록 권한도 줘야 해요. agent-desktop permissions --guide를 실행하면 안내가 나와요. 윈도우는 터미널과 같은 수준의 앱이라면 따로 허락할 게 없어요. 리눅스는 그래픽 세션과 at-spi2-core가 있어야 해요.

에이전트에게 이 도구를 알려 주는 길은 세 가지예요. 스킬로 설치하거나, 내장 안내 문서를 불러오게 하거나, 프로젝트의 AGENTS.md에 한 줄을 넣는 거죠. 가장 손이 덜 가는 건 스킬 설치예요.

npx skills add https://github.com/vercel-labs/agent-desktop --skill agent-desktop

그다음 클로드 코드나 코덱스에게 하는 요청은 길 필요가 없어요. 첫째는 확인 요청이에요. 내가 만든 앱을 agent-desktop으로 실행하고, 설정 화면 버튼들이 눌리는지 snapshot으로 확인한 뒤 안 되는 버튼만 알려 달라고 하면 되죠. 둘째는 습관 들이기예요. README가 권하는 영어 한 줄(agent-desktop으로 데스크톱 앱을 보고 다루라는 문장)을 AGENTS.md에 넣게 하고, 앞으로 UI를 고칠 때마다 agent-desktop으로 결과까지 확인하라고 덧붙이는 식이에요.

명령의 세부 옵션은 외울 필요가 없어요. 문서마다 붙은 “Copy for LLM” 버튼으로 페이지를 통째로 복사해 에이전트에게 붙여 넣으면 되거든요.

비슷한 도구와 무엇이 다른가

컴퓨터를 조작하게 해 주는 선택지는 이미 몇 개 있어요. 같은 회사의 브라우저용 도구, 맥 전용 오픈소스, 그리고 코덱스에 들어간 기능을 나란히 놓으면 이래요.

agent-desktopagent-browserPeekaboo코덱스 컴퓨터 사용
다루는 대상데스크톱 앱웹 페이지맥 앱맥 앱
읽는 방식접근성 트리만같은 ref 방식(브라우저)스크린샷 + 접근성 정보자기 커서로 보고 클릭
운영체제맥·윈도우·리눅스브라우저macOS 15 이상맥
형태CLI·C 라이브러리CLICLI·메뉴바 앱·MCP 서버코덱스 제품 안 기능
라이선스Apache-2.0Apache-2.0MIT상용 제품

갈림길은 두 군데예요. 하나는 운영체제예요. 윈도우나 리눅스 앱까지 다뤄야 하면 이 표에서 고를 수 있는 건 agent-desktop뿐이에요. 다른 하나는 쓰는 에이전트예요. 코덱스만 쓴다면 2026년 4월 맥에 들어간 내장 컴퓨터 사용으로 충분할 수 있고, 클로드 코드처럼 다른 에이전트도 함께 쓴다면 모델에 묶이지 않는 agent-desktop 쪽이 덜 번거로워요.

Peekaboo는 스크린샷을 함께 쓰기 때문에 접근성 트리가 빈약한 맥 앱에서도 화면을 볼 수 있다는 차이가 있어요. 대신 화면 기록 권한이 기본으로 따라오죠.

agent-browser 45.1k, agent-desktop 6.8k, Peekaboo 5.4k의 GitHub 별 수 막대그래프
자매 도구 agent-browser, 맥 전용 Peekaboo와 견준 GitHub 별 수예요.

관심도로 보면 agent-desktop은 공개 며칠 만에 Peekaboo를 넘어섰지만, 같은 방식을 먼저 낸 agent-browser의 6분의 1 수준이에요. 브라우저 쪽 수요가 아직 훨씬 크다는 뜻이고, 웹 작업만 한다면 굳이 데스크톱 도구로 넘어올 이유는 없어요.

아직 1.0, 조심할 것들

문서에서 가장 눈에 띄는 건 오히려 솔직함이에요. 할 수 없는 일과 개인정보 주의를 첫 화면 가까이에 적어 두었거든요.

agent-desktop 문서의 네 명령 루프 코드 예시와 에이전트에서 플랫폼 어댑터로 이어지는 구조도
계산기 앱을 예로 든 네 명령 반복. 지도 만들기, 펼치기, 누르기, 확인하기 순서예요.

문서의 예시는 계산기에서 숫자 7을 누르고 화면에 7이 떴는지 읽어 오는 네 단계예요. 문서는 “누르기가 성공해도 화면이 바뀌었다는 증거는 아니다”라며 마지막에 꼭 다시 읽으라고 해요. 에이전트에게 맡길 때도 “눌렀다”에서 멈추지 말고 “확인했다”까지 요구해야 한다는 얘기예요.

개인정보. 스냅샷, 클립보드, 스크린샷, 명령 출력에는 내 데스크톱에 떠 있던 내용이 그대로 담길 수 있어요. README는 이런 출력을 공개 로그나 업로드에 남기지 말라고 경고해요. 선택 기능인 JEV 도우미는 화면 설명을 설정한 모델 제공자에게 보내기도 해요. 메신저와 은행 앱이 떠 있는 일상용 컴퓨터보다는 테스트용 가상 머신(VM)에 먼저 깔겠다는 리뷰어의 판단이 합리적이에요.

윈도우 보안 경고. 같은 리뷰에 따르면 윈도우용 실행 파일은 서명이 없어 SmartScreen이나 백신이 막을 수 있어요.

덜 끝난 명령. README에 이름이 올라간 명령은 60개인데 그중 key-down, key-up, mouse-down, mouse-up 네 개는 아직 실행을 거부해요. 키를 누른 채로 끄는 동작 같은 세밀한 입력은 당분간 기대하기 어려워요. 창이 여러 개 열린 앱에서는 --window-id를 주지 않으면 대상을 못 정했다는 오류가 나고, 맥의 시스템 UI 쪽 지원은 계획 단계예요.

README에 적힌 명령 이름 60개와 실제 작동하는 명령 56개를 견준 막대그래프
README에 이름이 올라간 명령 60개 가운데 지금 작동하는 것은 56개예요.

검증된 후기가 적다. 2026년 11월 2일 기준 스크린샷 방식 도구와 견준 독립 테스트는 나오지 않았고, 공개된 깊이 있는 리뷰도 리눅스에서만 시험한 것이에요. README에 있던 데모 영상마저 최근 커밋에서 빠져서, 실제로 얼마나 잘 누르는지는 눈으로 볼 자료가 없어요. 이번에도 저장소와 문서를 읽어 본 것까지이고 설치해서 돌려 보진 않았어요.

유지보수는 활발한 편이에요. 1.0.2가 나온 다음 날에도 커밋이 이어졌고, 릴리스 목록은 9월의 0.9부터 5쪽에 이르러요. 다만 이 속도는 명령 이름이나 동작이 자주 바뀔 수 있다는 뜻이기도 해서, 에이전트에게는 외워 둔 옵션 대신 늘 최신 안내 문서를 불러오게 하는 쪽이 안전해요.

내가 만든 데스크톱 앱을 에이전트가 끝까지 확인하게 하고 싶다면, 남는 VM 하나에 npm 한 줄과 스킬 하나로 붙여 보는 게 지금 가장 부담 적은 첫걸음이에요.

자주 묻는 질문

agent-desktop은 무료인가요?

네. Apache-2.0 오픈소스라 무료로 쓰고 고칠 수 있어요. 안에 AI 모델이 없으니 도구 자체에 드는 사용료도 없어요. 실제 판단은 붙여 쓰는 클로드 코드나 코덱스가 하니, 그쪽 요금은 원래대로 들어요.

클로드 코드에 MCP 서버로 연결하나요?

2026년 11월 2일 기준 공식 문서는 MCP 서버를 따로 안내하지 않아요. 스킬 설치, 내장 안내 문서 불러오기, AGENTS.md에 한 줄 넣기, 이 세 가지 방법을 써요. 예전 개인 저장소 시절 소개 글에 나온 MCP 모드는 지금 문서에 없어요.

맥에서 손쉬운 사용 권한을 줘도 괜찮을까요?

이 권한이 있어야 다른 앱의 구조를 읽고 누를 수 있어요. 그만큼 터미널에서 돌아가는 에이전트가 화면의 앱을 만질 수 있게 된다는 뜻이라, 개인 자료가 많은 컴퓨터라면 테스트용 계정이나 가상 머신에서 먼저 쓰는 편이 마음 편해요.

참고한 자료 8
  1. GitHub - vercel-labs/agent-desktop (README)
  2. Releases · vercel-labs/agent-desktop
  3. agent-desktop 공식 문서 (agent-browser.dev/desktop)
  4. Chris Tate on X: Introducing agent-desktop
  5. Flavio Copes: A deep dive into agent-desktop
  6. GitHub - vercel-labs/agent-browser
  7. GitHub - openclaw/peekaboo
  8. Help Net Security: Codex can now operate between apps

이 글은 AI가 자료 조사와 초안 작성을 돕고, 운영자가 직접 써 보고 확인해 고친 뒤 발행했어요. 틀린 내용을 발견하면 알려 주세요.