AI 에이전트

2026 OpenHands 샌드박스는 어떻게 배포해야 AI 코딩 작업과 macOS 호스트를 격리할 수 있을까요?

AI 코딩 작업이 프로젝트 밖의 파일까지 건드릴까 걱정되나요?

OpenHands 샌드박스 배포는 공식 컨테이너 실행 경로를 우선 선택하고, 필요한 작업 폴더만 연결하는 방식이 적절합니다. 컨테이너를 완전한 보안 경계로 여기거나 Docker 소켓과 호스트 자격 증명을 기본으로 열어 두면 안 됩니다.

이 글은 Mac에서 OpenHands를 처음 배포하는 개발자, 여러 저장소의 경계를 나누려는 팀, macOS 네이티브 앱 빌드 환경을 설계하는 기술 책임자를 위한 안내입니다.

OpenHands 샌드박스 배포는 실행 경계 선택부터 시작합니다

먼저 Agent 서비스가 어디에서 실행되고, 코드 작업을 수행하는 런타임이 어디에 만들어지는지 구분해야 합니다. OpenHands는 로컬 실행과 샌드박스 런타임을 사용하는 경로가 있으며, 둘은 호스트 파일에 닿는 방식이 다릅니다. 공식 실행 모드 안내를 확인하고 현재 설치 문서가 안내하는 경로를 선택하세요.

작업 상황 우선 검토할 실행 경로 확인할 경계
코드 변경과 테스트 실행 공식 Docker 샌드박스 경로 연결한 작업 폴더의 쓰기 권한
출처를 신뢰하기 어려운 저장소의 스크립트 실행 격리된 런타임과 별도 작업 폴더 호스트 경로, 네트워크, 자격 증명
Xcode 등 macOS 전용 도구를 사용한 빌드 별도 macOS 실행 환경과 역할 분리 Agent가 빌드 환경에서 접근할 수 있는 파일

현재 OpenHands 로컬 설치 안내와 Docker 샌드박스 안내를 기준으로 설정을 검토하세요. 문서에 현재 경로와 구버전 경로가 함께 보일 수 있습니다. 예를 들어 V0로 표시된 이전 Docker Runtime 설명을 최신 공통 설정으로 그대로 적용하지 말고, 해당 경로가 현재 설치 방식에 해당하는지 확인해야 합니다. 고정 명령이나 이미지 태그는 문서가 바뀔 수 있으므로 공식 설치 안내의 현재 값을 사용하세요.

조건에 따라 실행 경로를 고르는 기준은 다음과 같습니다.

  • 프로젝트 코드 수정과 테스트가 목적이면 공식 Docker 샌드박스 실행 경로를 우선합니다.
  • 작업에 필요하지 않은 호스트 파일을 Agent가 읽거나 바꾸지 않아야 한다면, 별도 작업 폴더만 연결합니다.
  • 컨테이너 내부에서 Docker 명령을 실행해야 한다는 요구가 확인되지 않았다면 Docker 소켓을 연결하지 않습니다.
  • Xcode 등 macOS 전용 도구가 필요하면 컨테이너가 이를 제공한다고 가정하지 않습니다. Agent의 코드 작업과 macOS 빌드 단계를 따로 설계합니다.

작업 폴더와 호스트 파일의 경계를 제한합니다

컨테이너에서 Mac의 파일을 볼 수 있는 범위는 설정된 마운트와 권한에 좌우됩니다. 프로젝트 폴더를 연결하면 Agent는 컨테이너 안에서 그 경로를 통해 파일을 다룰 수 있습니다. 따라서 컨테이너 밖의 파일은 무조건 안전하다고 단정하지 말고, 실제로 어떤 경로를 연결했는지 확인해야 합니다.

작업 전용 폴더를 따로 준비하고 필요한 저장소만 그 안에 두세요. 참고 문서나 변경하면 안 되는 입력 파일은 지원되는 설정에서 읽기 전용으로 연결합니다. 읽기 전용 설정은 연결한 경로의 변경을 제한하는 데 유용하지만, 작업 폴더를 쓰기 가능하게 연결하면 Agent가 그 안의 파일을 수정하거나 삭제할 수 있습니다. Docker 바인드 마운트 문서에서 읽기 전용 옵션과 호스트 경로 연결 방식을 확인하세요.

연결 대상 권장 권한 배포 전 점검
이번 작업의 프로젝트 폴더 변경 작업이 있을 때만 쓰기 허용 경로가 해당 프로젝트만 가리키는지 확인
참고 자료와 입력 파일 가능하면 읽기 전용 결과물을 이 경로에 저장할 필요가 있는지 확인
비밀 키, 개인 설정, 무관한 저장소 연결하지 않음 환경 변수 파일과 홈 디렉터리가 포함되지 않았는지 확인

폴더 선택은 프로젝트의 상위 디렉터리가 아니라 작업에 필요한 저장소 경로를 기준으로 하세요. 현재 프로젝트만 마운트할 의도였더라도 상위 폴더를 연결하면 다른 저장소나 설정 파일까지 노출될 수 있습니다. 특히 호스트의 홈 디렉터리를 통째로 연결하는 구성은 피하고, 테스트 후에도 Agent가 계획하지 않은 경로에 접근하지 않았는지 확인합니다.

macOS Docker 샌드박스 배포에서는 서비스와 권한을 점검합니다

OpenHands 서비스 컨테이너와 코드 실행에 사용하는 샌드박스 런타임은 역할이 다를 수 있습니다. 설치 문서에 따라 서비스를 시작한 뒤, 작업 폴더가 어떤 경로로 런타임에 전달되는지 확인하세요. 단순히 서비스가 켜졌다는 사실만으로 작업 코드가 의도한 컨테이너에서 실행된다고 판단하면 안 됩니다.

서비스 관리 화면은 필요한 네트워크 인터페이스에서만 접근하도록 설정합니다. 로컬에서만 사용할 구성이라면 포트 게시 주소가 외부 인터페이스까지 열리지 않는지 살펴보세요. Docker의 포트 게시와 호스트 주소 설정 안내는 포트가 어느 호스트 주소에 노출되는지 확인할 때 참고할 수 있습니다. 로컬 개발용 설정을 그대로 공용 네트워크에 노출하지 마세요.

또한 macOS 자체의 앱 샌드박스와 Docker 컨테이너는 같은 보안 기능이 아닙니다. Apple은 macOS App Sandbox를 앱과 허가된 기능의 접근을 제한하는 방식으로 설명합니다. 이 문서를 근거로 OpenHands 컨테이너가 Mac 호스트에 접근할 수 없다고 결론 내릴 수는 없습니다. 실제 경계는 컨테이너 런타임과 마운트, 네트워크, 부여한 권한을 기준으로 판단해야 합니다.

Docker 소켓의 역할과 접근 권한을 구분합니다

Docker 소켓은 Docker 데몬에 요청을 보내 컨테이너를 관리하도록 연결하는 통로입니다. 컨테이너 안에서 별도 컨테이너를 만들어야 하는 작업에는 필요할 수 있지만, OpenHands의 코드 수정이나 테스트 실행만으로 항상 필요한 것은 아닙니다. 소켓 접근은 단순한 파일 공유가 아니므로, 필요성을 확인하지 않은 채 연결하지 않는 편이 안전합니다.

Docker는 데몬 접근을 보호해야 하는 대상으로 다룹니다. Docker 데몬 접근 보호 안내를 살펴보고, 소켓이 연결된 설정인지 공식 설치 문서와 실제 실행 설정에서 확인하세요. 컨테이너에 Docker 소켓이 전달되면 Agent의 작업 권한이 단순한 프로젝트 폴더 쓰기보다 넓어질 수 있으므로, 필요한 기능과 감수할 권한을 먼저 검토해야 합니다.

자격 증명과 첫 실행을 순서대로 확인합니다

모델 서비스 자격 증명, 저장소 접근 자격 증명, 작업 폴더 권한은 서로 다른 통제 항목입니다. 컨테이너를 사용해도 Agent가 전달받은 키를 잘못 사용하거나 네트워크를 통해 외부 서비스에 요청하는 위험까지 자동으로 없어지지는 않습니다. 비공개 저장소나 외부 API가 필요한 작업에는 작업에 필요한 범위만 허용한 별도 자격 증명을 사용하세요.

GitHub 토큰을 쓰는 경우 API 자격 증명을 안전하게 관리하는 안내를 참고해 저장과 권한 범위를 정하세요. 작업이 끝나면 임시 토큰을 폐기하고, 계속 사용할 자격 증명은 필요에 따라 교체합니다. 토큰의 만료와 폐기 방법도 미리 확인해 두면 작업 후 정리가 분명해집니다.

첫 실행은 민감한 데이터가 없는 작은 프로젝트로 진행하고 다음 항목을 확인하세요.

  • [ ] 최신 공식 안내에서 현재 지원하는 설치 및 실행 경로를 선택했습니다.
  • [ ] 작업에 필요한 프로젝트 폴더만 연결했고, 상위 폴더와 홈 디렉터리는 제외했습니다.
  • [ ] 참고 자료는 필요한 경우 읽기 전용으로 설정했습니다.
  • [ ] 서비스 화면의 네트워크 노출 범위를 확인했습니다.
  • [ ] Docker 소켓 연결 여부와 필요한 이유를 확인했습니다.
  • [ ] 모델과 저장소 자격 증명을 분리하고, 작업 후 철회 방법을 정했습니다.
  • [ ] 결과 파일이 예상한 작업 폴더에만 생겼는지 살폈습니다.
  • [ ] 런타임 종료 후 컨테이너와 임시 자격 증명이 남아 있는지 확인했습니다.

확인 과정에서 예상하지 못한 경로가 보이거나 컨테이너 실행이 실패하면 권한을 더 열어 해결하기보다, 작업 폴더 전달 방식과 현재 설치 문서의 설정을 다시 대조하세요. 한 번의 테스트 결과만으로 전체 컨테이너 경계가 검증됐다고 볼 수는 없습니다. 특히 비공개 저장소의 작업을 시작하기 전에 마운트와 네트워크, 자격 증명이 실제 작업에 필요한 수준인지 재검토하는 편이 좋습니다.

작업 종료와 macOS 네이티브 빌드 환경을 분리합니다

작업이 끝나면 필요한 코드 변경만 저장소에 반영하고, 임시 컨테이너와 자격 증명을 정리합니다. 다음 작업에서 같은 환경을 사용할 계획이더라도 이전 작업의 토큰이나 과도한 마운트 권한을 기본값으로 남겨 두지 마세요. 프로젝트가 달라지면 작업 폴더와 자격 증명도 다시 구분해야 합니다.

OpenHands의 Docker 샌드박스는 macOS 네이티브 빌드 환경을 대신하지 않습니다. Xcode와 같은 도구가 필요한 작업은 Agent의 코드 실행 경로와 분리해 macOS 실행 환경에서 수행하도록 계획하세요. 이때도 빌드 환경에 전체 호스트 접근 권한을 줄 필요가 있는지 검토해야 합니다.

임시 개발 환경을 준비하려고 개인 Mac에 컨테이너 설정과 정리 절차를 계속 남겨 두면, 호스트 파일 노출과 자격 증명 관리 부담이 생길 수 있습니다. 반대로 컨테이너만으로 macOS 전용 빌드를 처리할 수는 없습니다. 네이티브 빌드가 필요한 단기 작업이라면 KuzCloud의 Mac 이용 안내와 한국 지역 이용 정보를 확인해 별도 macOS 환경과 OpenHands 컨테이너의 역할을 나누는 방안을 검토할 수 있습니다. 이는 컨테이너의 보안 보증을 대신하는 선택이 아니라, 호스트와 빌드 작업을 분리해 운용하기 위한 환경 선택입니다.

전용 원격 맥에서 인공지능 코딩 작업을 분리해 시작하세요

KuzCloud의 전용 맥 미니를 별도 실행 환경으로 마련해 개인 맥 호스트와 코딩 작업을 분리해 운영하세요.

애플 실리콘의 실제 하드웨어와 최고 관리자 권한으로 필요한 개발 도구와 맥용 빌드 환경을 구성할 수 있습니다.