SuperHQ

SuperHQ란 무엇인가요?

SuperHQ는 AI 코딩 에이전트를 격리된 “실제 샌드박스” 내부에서 실행하여 에이전트가 로컬 머신에 직접 접근하지 않고 제어된 환경에서 작업할 수 있게 합니다. Claude Code, OpenAI Codex 및 맞춤 에이전트를 각각 별도의 microVM에서 오케스트레이션합니다.

핵심 목적은 에이전트 주도 코드 변경을 안전하게 실행하는 것입니다: 프로젝트가 샌드박스에 마운트되며(/workspace), 변경 사항은 승인할 때까지 오버레이에 캡처되고, 로컬 파일에 영향을 주기 전에 통합 diff 리뷰를 검사할 수 있습니다.

주요 기능

• 에이전트별 microVM 격리: Claude Code, Codex 및 맞춤 에이전트 각각이 자체 microVM에서 실행되어 작업 공간이 격리됩니다.
• Debian VM을 통한 완전한 Linux 사용자 공간: 샌드박스는 apt와 같은 패키지 도구, npm, pip를 포함한 Debian VM으로 설명되며, 에이전트가 종속성을 설치하고 실행하는 데 필요한 환경을 제공합니다.
• /workspace에 마운트된 프로젝트 작업 공간: 프로젝트가 샌드박스에 마운트되며, 에이전트 편집은 이 마운트 경로를 대상으로 합니다.
• 승인 게이트가 있는 오버레이 변경: VM에서 만든 변경은 리뷰 패널에서 승인할 때까지 오버레이에 유지됩니다.
• 로컬 적용 전 통합 diff 리뷰: 에이전트가 변경한 통합 diff를 확인하고 유지하거나 폐기할 수 있습니다.
• 옵트인 포트 포워딩: 개발 서버, 데이터베이스, API 등에 유용하며, 활성화할 때만 샌드박스에서 호스트로 포트를 포워딩합니다.
• 체크포인트 및 되감기: VM 상태를 중지하고 체크포인트한 후 나중에 재개할 수 있으며, 체크포인트를 포크하여 새로운 브랜치를 생성할 수 있습니다.

SuperHQ 사용 방법

1. SuperHQ 설치: 제공된 Homebrew 명령어(brew tap superhq-ai/tap 및 brew install --cask superhq)를 사용하여 macOS에 설치합니다.
2. 프로젝트를 위한 새 작업 공간 생성: UI에서 작업 공간 생성 및 키보드 단축키를 통한 빠른 전환을 확인합니다.
3. 에이전트 시작: 샌드박스 내 코딩 작업을 위해 인터페이스에서 Claude Code, OpenAI Codex 및 맞춤 에이전트 지원 목록을 선택합니다.
4. 리뷰 패널에서 변경 검토: 통합 diff를 검사하고 로컬 파일에 적용되기 전에 변경을 승인하거나 폐기합니다.
5. 필요에 따라 샌드박스 제어 기능 사용: VM에서 실행 중인 서비스에 접근할 때만 포트 포워딩을 활성화하고, 일시 중지/재개 또는 깨끗한 브랜치 포크를 위해 체크포인트를 사용합니다.

사용 사례

• 로컬 repo를 위한 안전한 에이전트 주도 리팩토링: 격리된 Debian VM에서 에이전트를 실행하여 코드를 수정하고, 통합 diff를 리뷰한 후 로컬 프로젝트에 원하는 부분만 승인합니다.
• 머신 오염 없이 종속성 중심 작업: 호스트에 직접 패키지를 설치하지 않고 샌드박스의 Debian 사용자 공간(apt, npm, pip)을 사용하여 에이전트가 도구를 설치하고 실행합니다.
• 임시 개발 서버를 통한 디버깅: 동작을 검사하면서 샌드박스 내부에서 실행 중인 서비스(예: 개발 서버 또는 API)에 접근하기 위해 옵트인 포트 포워딩을 활성화합니다.
• 체크포인트를 통한 반복 실험: 작업 공간 상태를 체크포인트한 후 접근 방식을 시도하고, 되감기하거나 체크포인트를 포크하여 다른 방향의 새 브랜치를 생성합니다.
• 맞춤 에이전트를 통한 맞춤 워크플로우 실행: Claude Code 또는 Codex를 넘어선 에이전트 설정 시 “맞춤 에이전트” 옵션을 사용하며, 여전히 에이전트별 microVM 샌드박스 내에서 실행합니다.

자주 묻는 질문

• SuperHQ가 격리하는 것은 무엇인가요? 각 에이전트 실행(Claude Code, Codex 또는 맞춤 에이전트)은 자체 microVM 샌드박스에서 실행됩니다.

• 에이전트 실행 중 프로젝트는 어디에 있나요? 프로젝트는 샌드박스에 /workspace에 마운트됩니다.

• 로컬 파일에 변경이 어떻게 적용되나요? 에이전트 편집은 리뷰 패널에서 승인할 때까지 오버레이에 유지됩니다. 로컬 파일에 영향을 주기 전에 변경을 유지하거나 폐기할 수 있도록 통합 diff가 표시됩니다.

• 샌드박스가 호스트에 서비스를 노출할 수 있나요? 네, 하지만 포트 포워딩은 옵트인으로, 샌드박스에서 호스트로 포트를 노출하기로 선택할 때만 활성화됩니다.

• 체크포인트는 어떻게 작동하나요? 작업 공간을 중지하고 전체 VM 상태를 체크포인트한 후 몇 초 만에 재개할 수 있으며, 체크포인트를 포크하여 새 브랜치를 시작할 수 있습니다.

대안

• 로컬 에이전트 워크플로(에이전트를 직접 로컬 머신에서 실행): 더 간단하지만, 설명된 microVM 격리, 승인 게이팅, 샌드박스 오버레이 모델이 일반적으로 부족합니다.
• 컨테이너화된 개발 환경(예: Docker 기반 에이전트 설정): 컨테이너는 종속성과 도구를 격리할 수 있지만, 특정 오버레이-승인 흐름과 microVM 체크포인트/되감기 동작이 다를 수 있습니다.
• 원격 샌드박스 또는 호스팅 코드 실행 플랫폼: 격리를 제공할 수 있지만, 워크플로와 코드 변경 검토/적용 위치가 SuperHQ의 /workspace 로컬 프로젝트 마운트와 통합 diff 승인과 다를 수 있습니다.
• 샌드박싱 없는 IDE 통합 AI 코딩 어시스턴트: 에디터 내 코딩 지원에 중점을 둡니다; 에이전트별 VM 격리, 로컬 파일 적용 전 diff 검토, 샌드박스 런타임과 연계된 옵트인 포트 포워딩을 제공하지 않을 수 있습니다.