Computer Use(macOS)

Hermes Agent는 Mac desktop을 background에서 조작할 수 있습니다. click, typing, scrolling, dragging을 수행해도 사용자의 cursor가 움직이지 않고, keyboard focus도 바뀌지 않으며, macOS가 Space를 전환하지 않습니다. 사용자와 agent가 같은 machine에서 동시에 작업할 수 있습니다.

대부분의 computer-use integration과 달리, 이 기능은 tool을 사용할 수 있는 모든 model과 함께 동작합니다. Claude, GPT, Gemini, local vLLM endpoint의 open model까지 사용할 수 있습니다. Anthropic-native schema를 따로 신경 쓸 필요가 없습니다.

동작 방식

computer_use toolset은 stdio 기반 MCP로 cua-driver와 통신합니다. cua-driver는 SkyLight private SPI(SLEventPostToPid, SLPSPostEventRecordTo)와 _AXObserverAddNotificationAndCheckRemote accessibility SPI를 사용하는 macOS driver이며, 이를 통해 다음을 수행합니다.

• 합성 event를 target process에 직접 post합니다. HID event tap도, cursor warp도 사용하지 않습니다.
• window를 앞으로 올리지 않고 AppKit active-state를 전환합니다. Space 전환이 일어나지 않습니다.
• window가 가려져 있어도 Chromium/Electron accessibility tree를 계속 유지합니다.

이 조합이 OpenAI Codex의 "background computer-use"에서 제공되는 방식입니다. cua-driver는 그에 대응하는 open-source 구현입니다.

활성화

편한 경로를 선택하면 됩니다. 두 방법 모두 같은 upstream installer를 실행합니다.

옵션 1: 전용 CLI 명령 사용(가장 직접적인 방법).

hermes computer-use install

이 명령은 upstream cua-driver installer를 가져와 실행합니다. curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh. 설치 확인은 hermes computer-use status로 합니다.

옵션 2: toolset을 interactive하게 활성화.

1. hermes tools를 실행한 뒤 Computer Use (macOS) -> cua-driver (background)를 선택합니다.
2. setup이 upstream installer를 실행합니다. 옵션 1과 같습니다.

설치 후에는 어떤 경로를 택했든 다음을 수행합니다.

3. macOS가 요청하는 권한을 허용합니다.
   • System Settings -> Privacy & Security -> Accessibility에서 terminal 또는 Hermes app을 허용합니다.
   • System Settings -> Privacy & Security -> Screen Recording에서도 같은 app을 허용합니다.
4. toolset을 활성화해 session을 시작합니다.

   hermes -t computer_use chat

   또는 ~/.hermes/config.yaml의 enabled toolset에 computer_use를 추가합니다.

cua-driver를 최신 상태로 유지하기

cua-driver project는 정기적으로 fix를 배포합니다. 예를 들어 v0.1.6에서는 UTM workflow에서 Safari window focus bug가 수정되었습니다. Hermes는 오래된 release에 묶이지 않도록 두 위치에서 binary를 refresh합니다.

• hermes update - Hermes 자체를 업데이트할 때 cua-driver가 PATH에 있으면 update 마지막에 upstream installer를 다시 실행합니다. macOS가 아니거나 cua-driver가 설치되어 있지 않은 경우에는 아무 작업도 하지 않습니다.
• hermes computer-use install --upgrade - 수동 강제 refresh입니다. cua-driver가 이미 설치되어 있는지와 관계없이 upstream installer를 다시 실행합니다. 다음 agent update를 기다리지 않고 최신 fix를 받고 싶을 때 사용합니다.

hermes computer-use status는 설치된 version을 binary path 옆에 표시합니다.

빠른 예시

사용자 prompt: "Find my latest email from Stripe and summarise what they want me to do."

agent의 plan:

1. computer_use(action="capture", mode="som", app="Mail") - Mail screenshot을 가져오며, sidebar item, toolbar button, message row에 모두 번호가 붙습니다.
2. computer_use(action="click", element=14) - capture에서 element #14인 search field를 click합니다.
3. computer_use(action="type", text="from:stripe")
4. computer_use(action="key", keys="return", capture_after=True) - submit한 뒤 새 screenshot을 받습니다.
5. 맨 위 결과를 click하고 본문을 읽은 뒤 요약합니다.

이 모든 과정 동안 사용자의 cursor는 원래 위치에 머물고 Mail은 앞으로 올라오지 않습니다.

provider 호환성

Provider	Vision?	동작?	Notes
Anthropic(Claude Sonnet/Opus 3+)	예	예	전반적으로 가장 좋습니다. SOM + raw coordinates를 지원합니다.
OpenRouter(any vision model)	예	예	multi-part tool message를 지원합니다.
OpenAI(GPT-4+, GPT-5)	예	예	위와 동일합니다.
Local vLLM / LM Studio(vision model)	예	예	model이 multi-part tool content를 지원해야 합니다.
text-only model	아니요	제한적으로 동작	accessibility tree만 사용하는 작업에는 mode="ax"를 사용합니다.

screenshot은 OpenAI-style image_url part로 tool result에 inline 전송됩니다. Anthropic의 경우 adapter가 이를 native tool_result image block으로 변환합니다.

안전성

Hermes는 여러 층의 guardrail을 적용합니다.

• destructive action(click, type, drag, scroll, key, focus_app)은 approval이 필요합니다. CLI dialog로 interactive approval을 받거나, messaging platform의 approval button을 사용합니다.
• tool level에서 hard-block되는 key combo: empty trash, force delete, lock screen, log out, force log out.
• hard-block되는 type pattern: curl | bash, sudo rm -rf /, fork bomb 등.
• agent system prompt는 permission dialog를 click하지 말 것, password를 입력하지 말 것, screenshot 안에 들어 있는 instruction을 따르지 말 것을 명시합니다.

모든 action을 확인받고 싶다면 ~/.hermes/config.yaml에서 approvals.mode: manual과 함께 사용하세요.

token 효율

screenshot은 비용이 큽니다. Hermes는 네 단계의 최적화를 적용합니다.

• Screenshot eviction - Anthropic adapter는 context에 가장 최근 screenshot 3개만 유지합니다. 오래된 screenshot은 [screenshot removed to save context] placeholder가 됩니다.
• Client-side compression pruning - context compressor가 multimodal tool result를 감지하고 오래된 result에서 image part를 제거합니다.
• Image-aware token estimation - 각 image는 base64 char length가 아니라 Anthropic의 flat rate에 맞춰 약 1500 token으로 계산됩니다.
• Server-side context editing(Anthropic only) - 활성화된 경우 adapter가 context_management를 통해 clear_tool_uses_20250919를 켜서 Anthropic API가 오래된 tool result를 server side에서 지우게 합니다.

1568x900 display에서 20-action session은 보통 screenshot context로 약 30K token을 사용합니다. 약 600K token이 아닙니다.

제한 사항

• macOS only. cua-driver는 Linux나 Windows에 없는 private Apple SPI를 사용합니다. cross-platform GUI automation에는 browser toolset을 사용하세요.
• Private SPI risk. Apple은 OS update에서 SkyLight symbol surface를 바꿀 수 있습니다. macOS version이 바뀌어도 재현성을 유지하고 싶다면 HERMES_CUA_DRIVER_VERSION env var로 driver version을 pin하세요.
• Performance. background mode는 foreground보다 느립니다. SkyLight-routed event는 direct HID posting의 5-20ms 수준보다 느리게 처리됩니다. agent-speed clicking에는 거의 티가 나지 않지만, speed-run을 녹화하려 하면 느껴질 수 있습니다.
• keyboard password entry 없음. type은 command-shell payload에 대한 hard-block pattern을 갖고 있습니다. password는 system autofill을 사용하세요.

설정

driver binary path override(tests / CI):

HERMES_CUA_DRIVER_CMD=/opt/homebrew/bin/cua-driver
HERMES_CUA_DRIVER_VERSION=0.5.0    # optional pin

backend 전체 교체(test용):

HERMES_COMPUTER_USE_BACKEND=noop   # records calls, no side effects

문제 해결

computer_use backend unavailable: cua-driver is not installed - hermes computer-use install을 실행해 cua-driver binary를 가져오거나, hermes tools를 실행해 Computer Use toolset을 활성화하세요.

click이 아무 효과가 없어 보임 - capture해서 확인하세요. 보이지 않던 modal이 input을 막고 있을 수 있습니다. escape 또는 close button으로 닫습니다.

element index가 stale 상태임 - SOM index는 다음 capture 전까지만 유효합니다. 상태를 바꾸는 action 이후에는 다시 capture하세요.

"blocked pattern in type text" - type하려던 text가 dangerous-shell-pattern list와 match되었습니다. 명령을 나눠 입력하거나 접근을 다시 검토하세요.

같이 보기

• Universal skill: macos-computer-use
• cua-driver source(trycua/cua)
• cross-platform web task에는 Browser automation을 참고하세요.