OpenHands 맥 자체 운영: 로컬과 클라우드 맥

설치는 끝났지만 실제 저장소의 빌드와 검증 단계에서 멈춥니다.
개인 저빈도 작업은 로컬 맥으로 시작하고, 여러 명이 계속 쓰거나 원격 접속과 권한 격리가 필요하면 클라우드 맥으로 분리하는 편이 안전합니다.

이 글을 읽어야 하는 사람

OpenHands를 낮은 비용으로 시험해 보려 하지만 자신의 맥을 계속 점유해도 되는지 판단하기 어려운 독립 개발자에게 적합합니다. 여러 개발자에게 같은 에이전트 환경을 제공하려는 플랫폼 엔지니어, iOS와 macOS 프로젝트를 실제로 수정하고 검증해야 하는 팀도 대상입니다.

설치 성공과 프로젝트 검증 성공은 다릅니다

OpenHands는 공식 안내에 따라 로컬 설치나 Docker 방식으로 실행할 수 있습니다. Docker 방식에서는 실행 컨테이너와 에이전트 런타임이 연결되고, 작업 폴더를 샌드박스 안에 마운트할 수 있습니다. 다만 설치 명령이 성공했다는 사실만으로 실제 저장소의 검증까지 끝난 것은 아닙니다. 공식 로컬 설치 안내와 런타임 구조 문서를 먼저 확인해야 합니다.

OpenHands는 맥에 직접 배포할 수 있나요?
가능합니다. 로컬 맥에서 OpenHands를 실행하고 Docker Runtime을 사용해 에이전트 작업을 분리할 수 있습니다. 그러나 에이전트가 수정한 코드가 Swift 소스 변경에 그치는지, Xcode 빌드와 시뮬레이터 실행까지 필요한지는 별도로 확인해야 합니다.

처음부터 다음 세 가지를 분리해 기록하면 판단이 쉬워집니다.

• 에이전트가 저장소를 읽고 수정했는가
• 테스트 명령이 실제로 실행되었는가
• 최종 산출물이 Xcode와 애플 서명 환경에서 검증되었는가

세 번째 항목이 필요하다면 일반적인 리눅스 기반 컨테이너만으로는 충분하지 않습니다.

첫 번째 문제: 개발용 맥이 계속 점유됩니다

저빈도 작업에서는 로컬 배포가 합리적입니다. 하루에 한두 번 저장소를 열고, 작업이 끝난 뒤 컨테이너를 정리하며, 개발자가 직접 화면을 확인한다면 별도 서버를 유지할 이유가 작습니다. 공식 환경 변수에는 런타임을 일정 시간 유지하거나 유휴 상태에서 닫는 설정도 제공됩니다. 환경 변수 참고 문서에서 런타임 유지와 종료 동작을 확인할 수 있습니다.

문제는 장시간 작업입니다. 에이전트가 의존성을 설치하거나 테스트를 반복하는 동안 같은 맥에서 다음 문제가 나타날 수 있습니다.

1. 개발자가 사용하는 터미널과 포트가 충돌합니다.
2. Docker가 사용하는 저장 공간과 캐시가 계속 남습니다.
3. 재부팅, 절전, 네트워크 변경으로 작업이 중단됩니다.
4. 개인용 인증 정보와 프로젝트 작업 공간이 같은 호스트에 놓입니다.

따라서 로컬에서 계속 운영하려면 먼저 실제 저장소를 대상으로 중단 복구를 시험해야 합니다. 화면을 닫은 뒤 다시 접속할 수 있는지, 컨테이너가 종료된 뒤 변경 사항이 보존되는지, 작업 로그를 다시 확인할 수 있는지 검증하십시오.

두 번째 문제: Docker 격리는 완전한 보안 경계가 아닙니다

OpenHands의 Docker Runtime은 임의 코드를 컨테이너 안에서 실행하기 위한 격리 계층입니다. 하지만 호스트 폴더를 쓰기 가능 상태로 마운트하면 에이전트가 그 폴더의 파일을 수정하거나 삭제할 수 있습니다. 공식 문서도 마운트된 파일과 디렉터리에 대한 별도 주의를 요구합니다.

특히 다음 네 가지를 따로 관리해야 합니다.

• 작업 폴더는 필요한 경로만 rw로 열고 나머지는 ro로 제한합니다.
• Docker 소켓을 연결하면 컨테이너 관리 권한이 넓어질 수 있으므로 접근 주체를 제한합니다.
• 기본 네트워크 바인딩이 외부 인터페이스를 향하지 않는지 확인합니다.
• API 키, 저장소 토큰, 키체인 접근 정보는 런타임 환경에 무심코 전달하지 않습니다.

Docker 소켓 접근을 별도로 보호하는 방법은 Docker 공식 소켓 보호 문서에서 확인할 수 있습니다. OpenHands의 보안 설정만으로 호스트 자격 증명과 네트워크 접근까지 자동으로 안전해지는 것은 아닙니다.

독립된 클라우드 맥을 사용하면 문제가 사라지는 것이 아니라 영향 범위를 줄이기 쉬워집니다. 개인 개발 맥과 에이전트 전용 환경을 분리하고, 저장소와 토큰을 프로젝트별로 나누며, 접속 계정을 제한할 수 있기 때문입니다.

세 번째 문제: 여러 에이전트는 환경 충돌을 만듭니다

OpenHands에서 여러 에이전트를 실행하려면 어떤 환경이 필요한가요?
에이전트 수를 먼저 세기보다 작업 단위를 분리해야 합니다. 각 작업에 독립된 작업 폴더, 포트 범위, 의존성 캐시, 로그 위치가 필요합니다. OpenHands는 런타임 포트와 애플리케이션 포트를 관리하는 기능을 제공하지만, 프로젝트가 같은 경로와 서비스를 공유하면 충돌 가능성은 남습니다.

다음과 같은 상황이면 단일 개발 맥을 공유하지 않는 편이 좋습니다.

• 두 프로젝트가 서로 다른 패키지 버전을 요구합니다.
• 여러 작업이 같은 로컬 데이터베이스나 개발 서버를 사용합니다.
• 에이전트가 장시간 실행되며 개발자가 동시에 빌드합니다.
• 팀원이 원격으로 작업을 시작하고 결과를 나중에 확인합니다.

개인 사용자는 로컬 맥 하나로 시작할 수 있습니다. 소규모 팀은 에이전트 전용 로컬 맥을 두는 방식이 중간 선택입니다. 자동화 플랫폼이나 지속적인 작업 큐가 필요하면 원격 런타임과 클라우드 맥을 분리해 확장하는 구조가 더 적합합니다.

네 번째 문제: 애플 도구 체인이 빠집니다

Swift 파일을 고치는 작업과 애플 앱을 완성하는 작업은 다릅니다. iOS와 macOS 프로젝트의 실제 검증에는 Xcode 빌드, 시뮬레이터 실행, 테스트 대상 선택, 서명 자산 확인이 포함될 수 있습니다. Apple 문서는 Xcode가 시뮬레이터나 연결된 기기에서 앱을 실행할 수 있다고 설명하며, 서명 인증서가 없거나 유효하지 않으면 빌드 오류가 발생할 수 있다고 안내합니다. Xcode 실행 문서와 빌드 설정 및 서명 문서를 함께 확인해야 합니다.

OpenHands는 iOS와 macOS 프로젝트를 어떻게 처리하나요?
OpenHands는 소스 탐색, 파일 수정, 스크립트 실행을 자동화할 수 있지만, 애플 도구 체인의 존재와 권한을 대신 보장하지는 않습니다. Docker 컨테이너 안에서 Swift 코드를 수정한 뒤, 실제 Xcode 프로젝트의 빌드와 서명은 사용 가능한 macOS 환경에서 다시 확인해야 합니다.

배포 전에는 다음 순서로 검증하십시오.

1. 저장소를 별도 작업 폴더에 복제합니다.
2. OpenHands가 읽기 전용 상태에서 구조와 테스트 명령을 파악하는지 확인합니다.
3. 쓰기 권한을 필요한 폴더에만 부여합니다.
4. 에이전트가 수정한 뒤 일반 테스트와 정적 검사를 실행합니다.
5. macOS 호스트에서 Xcode 프로젝트를 열고 실제 빌드를 실행합니다.
6. 시뮬레이터 또는 테스트 기기에서 핵심 흐름을 확인합니다.
7. 서명과 배포 단계가 필요한 경우 인증서와 프로파일을 별도 계정으로 검증합니다.

이 과정에서 5단계부터 실패한다면 OpenHands 문제가 아니라 애플 검증 환경이 분리되지 않은 문제일 수 있습니다.

다섯 번째 문제: 의존성을 매번 다시 설치합니다

첫 실행이 성공해도 반복 작업의 유지 비용이 낮다는 뜻은 아닙니다. OpenHands는 사용자 지정 런타임 이미지와 이미지 태그를 사용할 수 있으며, 소스와 의존성 상태에 따라 기존 이미지를 재사용하는 구조를 문서화하고 있습니다. 동일한 기반 이미지와 잠금 파일을 유지하면 전체 의존성을 매번 처음부터 설치하는 상황을 줄일 수 있습니다.

로컬 환경의 장점은 캐시를 빠르게 재사용할 수 있다는 점입니다. 반면 여러 사람이 같은 맥을 사용하면 캐시가 누구의 작업을 위해 만들어졌는지 불분명해집니다. 클라우드 환경에서는 기준 이미지를 고정하고 작업마다 깨끗한 런타임을 만들기 쉬워 재현성이 높아집니다.

운영할 때는 다음 원칙이 유효합니다.

• 프로젝트별 기반 이미지를 무작정 늘리지 않습니다.
• 의존성 잠금 파일과 런타임 태그를 함께 기록합니다.
• 이미지 변경 후에는 새 저장소에서 처음부터 재현합니다.
• 캐시를 지웠을 때도 팀원이 같은 결과를 얻는지 확인합니다.

로컬과 클라우드 맥을 고르는 기준

아래 표에서 한 항목만 보고 결정하지 마십시오. 애플 도구 체인과 원격 접속이 동시에 필요하면 다른 조건보다 우선순위가 높습니다.

로컬과 클라우드 맥 중 어느 쪽이 더 좋은가요?
저빈도 개인 작업이면 로컬이 더 단순합니다. 팀원이 동시에 사용하거나 밤새 실행해야 한다면 클라우드 맥이 관리하기 쉽습니다. 단, 클라우드 맥도 Xcode 버전, 시뮬레이터 이미지, 서명 방식, 원격 화면과 저장소 접근 정책을 먼저 확인해야 합니다.

점수로 보는 빠른 선택

각 항목에서 해당하면 점수를 더하십시오.

• 하루에도 여러 번 원격으로 작업을 시작해야 한다: 클라우드 맥 +2
• 동시에 두 명 이상이 작업한다: 클라우드 맥 +2
• 개인 맥의 절전이나 재부팅이 작업 중단으로 이어진다: 클라우드 맥 +2
• Xcode와 시뮬레이터 검증이 필수다: 사용 가능한 macOS 환경 +3
• 하루에 한 번 이하로 짧게 시험한다: 로컬 맥 +2
• 별도 계정과 장비를 관리할 사람이 없다: 로컬 맥 +1

클라우드 맥 점수가 높고 Xcode 검증 점수도 높다면 독립 환경을 먼저 짧게 시험하십시오. 로컬 맥 점수가 높다면 실제 저장소 하나를 끝까지 처리한 뒤 계속 사용해도 됩니다.

실제 선택은 짧은 검증 뒤에 하십시오

처음부터 장기 환경을 정하지 말고 실제 저장소 하나를 선택하십시오. OpenHands가 요구사항을 읽고, 테스트를 실행하고, 변경 사항을 남기며, macOS에서 Xcode 검증까지 이어지는지 확인해야 합니다.

그 뒤 다음 결과를 기록하십시오.

• 작업 중 개발 맥을 사용할 수 있었는가
• 마운트한 폴더 외부에 접근할 이유가 생겼는가
• 두 번째 작업이 첫 번째 작업과 충돌했는가
• 이미지 재구축 없이 같은 환경을 재현했는가
• 원격 접속이 끊겨도 작업 결과를 회수했는가
• Xcode 빌드와 서명 검증을 같은 운영 흐름에 넣을 수 있었는가

이 기록은 단순한 설치 성공 화면보다 장기 운영 판단에 훨씬 유용합니다. 원격 접속 정책이나 결제 흐름을 확인해야 한다면 SSHMac 도움 센터와 결제 안내를 함께 확인할 수 있습니다.

현재 로컬 맥 방식은 시작이 쉽지만, 개인 개발 환경의 점유와 절전 중단, 작업별 권한 분리 부족이 약점입니다. 반대로 클라우드 맥은 별도 환경을 유지해야 하고 접속 정책과 애플 도구 체인의 제공 범위를 확인해야 하지만, 지속 실행과 원격 협업에는 더 적합합니다. 실제 저장소를 짧게 시험한 뒤 이런 차이가 분명해졌다면, SSHMac의 클라우드 맥을 임시 검증 환경으로 사용해 보고 장기적으로 로컬, 전용 장비, 혼합 운영 중 하나를 선택하는 편이 이론적인 사양만 보고 장비를 고르는 것보다 안전합니다.