2026년 9월 6일 기준으로 OpenHands Agent Canvas는 데스크톱 앱을 macOS, Windows, Linux용 초기 미리 보기로 제공하고 있습니다. 공식 설치 문서를 기준으로 보면, OpenHands Agent Canvas 설치는 개인 시험이면 데스크톱 미리 보기나 npx, 파일 경계를 정해야 하면 Docker, 상시 실행과 팀 공유가 필요하면 원격 백엔드가 맞습니다. 데스크톱 앱은 시작 절차를 줄일 뿐, 자동으로 샌드박스를 만들지는 않습니다.
마지막 업데이트: 2026년 9월 6일. 데스크톱 미리 보기 상태와 설치 방식은 공식 설치 문서와 Agent Canvas의 구조 설명을 대조해 확인했습니다.
이 글은 Node.js와 uv 환경에 익숙하지 않아도 첫 작업을 성공시키고 싶은 개인 개발자를 위한 안내입니다. Agent가 읽고 쓰는 범위를 제한하려는 Docker 사용자와, 팀이 계속 사용할 백엔드를 준비하는 플랫폼 엔지니어도 대상입니다.
먼저 고르는 기준은 실행 위치입니다
Agent Canvas를 설치할 때 화면이 어디에 뜨는지만 보면 안 됩니다. Canvas는 조작 화면이고, 백엔드는 작업을 받아 실행하며, 실제 프로젝트 파일과 명령을 처리하는 환경은 따로 구분해야 합니다. 이 구분이 없으면 데스크톱 앱을 설치한 뒤 Agent가 사용자의 권한을 그대로 물려받는 상황을 놓치기 쉽습니다.
| 사용 목적 | Canvas 위치 | Agent 실행 위치 | 접근 가능한 대상 | 중단 뒤 상태 | 권장 선택 |
|---|---|---|---|---|---|
| 첫 화면과 짧은 작업 확인 | 개인 컴퓨터 | 개인 컴퓨터 또는 연결된 기본 백엔드 | 연 폴더와 사용자 권한 범위 | 터미널이나 컴퓨터 상태에 영향 | 데스크톱 미리 보기 또는 npx |
| 로컬 저장소 수정 | 개인 컴퓨터 | 개인 컴퓨터 또는 Docker | 직접 연 작업 공간 또는 마운트한 디렉터리 | 실행 방식에 따라 작업 중단 | 민감도가 낮으면 로컬, 아니면 Docker |
| 반복 가능한 개발 환경 | 개인 컴퓨터 | Docker | 명시한 마운트 경로와 컨테이너 내부 | 볼륨 설정에 따라 파일 보존 | Docker |
| 절전과 종료에 영향을 받지 않는 작업 | 개인 컴퓨터 | 독립 VM 또는 원격 서버 | 원격 백엔드가 허용한 작업 공간 | 원격 프로세스 정책에 따라 유지 | 원격 백엔드 |
| 팀 공유와 도구가 다른 작업 | 각자의 Canvas | 팀용 백엔드와 실행 환경 | 계정과 실행 풀에서 정한 범위 | 복구 정책과 저장소 정책에 따름 | 원격 백엔드와 실행 환경 분리 |
첫 설치는 데스크톱 미리 보기보다 검증 절차가 중요합니다
첫 단계: 데스크톱 앱과 npx의 차이를 확인합니다
Agent Canvas Desktop App은 Node.js와 패키지 설정을 직접 다루는 부담을 줄이는 데 의미가 있습니다. 그러나 공식 문서에서 데스크톱 앱은 아직 초기 미리 보기로 구분되어 있으므로, 안정적인 장기 운영이나 강한 격리를 기대해서는 안 됩니다. Node.js 설치가 필요한 방식과 앱 방식의 구분은 Node.js 공식 설치 안내와 OpenHands 설치 문서에서 현재 절차를 확인해야 합니다.
npx는 별도 프로젝트에 패키지를 고정하는 절차를 줄여 빠른 시험에 적합합니다. npm 설치는 프로젝트 안에 의존성을 기록하고 같은 실행 절차를 반복하기 쉽지만, 업데이트 시점과 패키지 상태를 직접 관리해야 합니다. 세 방식의 차이는 성능보다 다음 세 가지에 있습니다.
- Node.js와 패키지 관리자를 직접 준비해야 하는가
- 터미널을 닫거나 컴퓨터가 절전 상태가 되었을 때 백엔드가 계속 실행되는가
- 다음 실행 때 같은 버전과 설정을 재현할 수 있는가
둘째 단계: 최소 작업으로 성공 여부를 확인합니다
설치가 끝났다고 바로 실제 저장소를 열지 마십시오. 다음 순서로 확인하면 화면만 뜨고 Agent가 실행되지 않는 문제를 구분할 수 있습니다.
- 공식 설치 문서에서 운영 체제에 맞는 데스크톱 미리 보기, npx, npm 가운데 하나를 고릅니다.
- 공식 문서에 적힌 현재 명령과 필요한 Node.js 또는 uv 조건을 그대로 적용합니다.
- Canvas 화면이 열리는지 확인한 뒤, 연결된 백엔드의 상태를 확인합니다.
- 민감하지 않은 빈 작업 폴더를 열고 파일 목록을 읽는 최소 작업을 요청합니다.
- 작은 텍스트 파일을 만들고 내용을 다시 읽게 하여 읽기와 쓰기를 각각 확인합니다.
- Canvas를 닫거나 터미널을 종료한 뒤 작업 상태와 생성 파일의 보존 여부를 다시 확인합니다.
이 검증에서 작업 폴더 밖의 파일을 읽을 수 있거나, 중단 뒤에도 어떤 프로세스가 남아 있는지 알 수 없다면 실제 프로젝트를 연결하지 않는 편이 낫습니다.
데스크톱 버전과 Docker의 차이는 앱 모양이 아닙니다. 데스크톱은 실행 진입점을 단순하게 만들고, Docker는 Agent가 볼 수 있는 파일과 프로세스 범위를 설정하는 수단입니다. 둘을 같은 보안 기능으로 비교하면 안 됩니다.
로컬 프로젝트를 열 때는 파일 경계를 먼저 정합니다
OpenHands를 로컬에 설치하는 것이 안전한지는 설치 방식만으로 결정되지 않습니다. 로컬 프로세스가 현재 사용자 권한으로 실행되면 Agent가 작업 폴더 밖의 파일이나 사용 가능한 명령에 접근할 가능성을 별도로 검토해야 합니다. 특히 개인 키, 환경 변수 파일, 클라우드 인증 정보가 같은 사용자 영역에 있다면 단순한 화면 편의성만으로 로컬 실행을 선택해서는 안 됩니다.
직접 작업 공간을 여는 방식은 설정이 빠르고 파일 감시 도구와의 호환성이 좋습니다. 대신 접근 범위를 운영 체제 권한과 실행 프로세스에 의존합니다. Docker는 필요한 프로젝트 디렉터리만 마운트하고 나머지는 컨테이너 안에 남길 수 있습니다. 다만 컨테이너가 완전한 임차인 분리를 뜻하지는 않습니다. Docker 보안 문서처럼 권한, 소켓 연결, 이미지 출처, 호스트와의 공유 설정을 함께 검토해야 합니다.
조건에 따라 다음처럼 결정하면 됩니다.
- 프로젝트가 공개 저장소이고 실패해도 다시 받을 수 있으면 로컬 실행을 선택합니다.
- 비밀 파일이나 개인 키가 같은 계정에 있고 Agent가 수정할 파일이 제한적이면 Docker로 돌아갑니다.
- 호스트 Docker 소켓을 컨테이너에 넘겨야 하는 도구라면 격리 효과가 줄어드므로 별도 실행 환경을 검토합니다.
- 운영 체제 자체의 도구와 물리 장치가 꼭 필요하면 컨테이너보다 전용 호스트가 더 적합할 수 있습니다.
Docker는 반복 실행과 복구 조건을 고정하는 선택입니다
Docker를 쓸 때는 이미지 실행보다 저장 위치와 마운트 경계를 먼저 설계해야 합니다. Docker 볼륨 문서에 설명된 것처럼 컨테이너의 생명 주기와 별도로 보존해야 하는 설정과 작업 결과는 볼륨 또는 명시적인 호스트 경로에 저장해야 합니다.
| 확인 항목 | 직접 실행 | Docker 실행 | 원격 백엔드 |
|---|---|---|---|
| Agent가 실행되는 곳 | 현재 컴퓨터 | 컨테이너 | VM 또는 원격 서버 |
| 프로젝트 접근 | 연 폴더와 사용자 권한 | 마운트한 경로 중심 | 원격 저장소와 백엔드 정책 |
| 설정 보존 | 사용자 환경과 프로젝트에 의존 | 볼륨 설정에 의존 | 서버 디스크와 배포 설정에 의존 |
| 터미널 종료 영향 | 실행 방식에 따라 중단 | 컨테이너 정책에 따름 | 원격 프로세스 정책에 따름 |
| 주요 점검 대상 | 계정 권한과 비밀 파일 | 마운트, 권한, 소켓 | 인증, TLS, 네트워크, 복구 |
Docker 기반 Agent Canvas를 구성할 때는 다음 순서를 지키십시오.
- 공식 Docker 백엔드 안내에서 현재 이미지와 실행 조건을 확인합니다.
- 프로젝트를 읽고 쓸 호스트 경로를 하나 정하고, 필요한 경우 읽기 전용 경로를 별도로 나눕니다.
- 설정, 작업 결과, 캐시를 컨테이너 임시 영역과 분리할지 결정합니다.
- Canvas가 연결할 백엔드 주소와 인증 정보를 로컬 문서나 비밀 저장소에 기록합니다.
- 컨테이너 안에서 프로젝트 목록, 파일 생성, 파일 삭제 권한을 각각 시험합니다.
- 컨테이너를 중지하고 다시 시작한 뒤 설정과 작업 결과가 남는지 확인합니다.
- 호스트 Docker 소켓이나 불필요한 장치 권한이 연결되어 있지 않은지 점검합니다.
이 과정에서 중지 뒤 설정이 사라지면 볼륨 구성이 빠진 것입니다. 프로젝트가 보이지 않으면 마운트 경로나 컨테이너 내부 경로가 맞지 않는 것입니다. 두 문제를 성능 문제로 오해하지 마십시오.
원격 백엔드는 지속 실행과 팀 공유를 위해 선택합니다
컴퓨터 절전, 터미널 종료, 불안정한 네트워크가 작업을 끊는다면 Canvas만 다른 컴퓨터에 설치하는 것으로 해결되지 않습니다. Agent가 실제로 실행되는 백엔드를 독립 VM이나 원격 서버로 옮겨야 합니다. 공식 VM 자체 운영 안내는 이 구조를 검토할 때 필요한 배포 경계를 설명합니다.
원격 백엔드를 선택할 조건은 분명합니다.
- 작업이 개인 컴퓨터의 절전이나 종료 뒤에도 계속되어야 하면 원격 백엔드를 선택합니다.
- 여러 사람이 같은 작업 상태를 확인해야 하면 공유 Canvas보다 공유 백엔드의 저장과 권한 정책을 먼저 정합니다.
- 팀원이 서로 다른 운영 체제를 사용하면 Canvas는 공유하되 실행 환경을 작업 유형별로 분리합니다.
- Linux에서 가능한 일반 작업과 반드시 macOS 도구 체인이 필요한 작업은 같은 실행 풀에 넣지 않습니다.
- 인터넷에 백엔드를 공개해야 하면 인증, TLS, 허용 네트워크 범위, 관리 포트를 함께 제한합니다.
데스크톱 앱이 팀이 자체 운영하는 백엔드에 연결할 수 있는지는 Canvas와 백엔드 연결 설정을 따로 확인해야 합니다. 공식 연결 문서에 맞는 주소와 인증 방식을 사용하면 데스크톱은 조작 화면으로 남고, 실제 Agent는 팀이 관리하는 원격 실행 환경에서 동작할 수 있습니다. 이때 공유 화면과 공유 실행 환경은 같은 개념이 아닙니다.
최신 변경 여부는 Agent Canvas 1.16.0 공개 문서와 현재 설치 문서를 함께 대조하십시오. 버전, 지원 운영 체제, 포트, 연결 방식이 바뀌면 예전에 성공한 설치 명령도 그대로 재사용하지 않는 것이 좋습니다.
상황별 선택 점수와 다음 행동
설치 편의성만 보면 데스크톱 미리 보기가 가장 높은 점수를 받을 수 있습니다. 하지만 파일 경계와 지속 실행까지 포함하면 평가가 달라집니다.
- 빠른 첫 화면과 짧은 시험이 목적이면 데스크톱 미리 보기 또는 npx를 선택합니다.
- 로컬 프로젝트를 수정하지만 파일 범위가 넓지 않고 복구가 쉬우면 직접 실행을 선택합니다.
- 파일 범위를 명시하고 같은 구성을 반복해야 하면 Docker를 선택합니다.
- 작업 복구, 팀 접근, 장시간 실행이 필요하면 원격 백엔드를 선택합니다.
- macOS 전용 도구 체인이 필요하면 실행 환경이 실제 macOS인지 먼저 확인하고, 단순히 원격 Canvas를 연결하는 방식으로 대체하지 않습니다.
현재 사용 중인 방식이 터미널 종료 때 작업을 잃고, 호스트 전체 파일을 볼 수 있으며, 팀원이 같은 설정을 재현하지 못한다면 다음 단계는 데스크톱 재설치가 아닙니다. 개인 시험은 도움 센터의 원격 개발 안내에서 최소 설치 절차를 확인하고, 팀 운영은 원격 백엔드 배포와 복구 정책을 먼저 설계해야 합니다. 회사 단위로 환경을 검토한다면 SSHMac의 회사 소개에서 제공 범위도 함께 확인할 수 있습니다.
현재 방식이 개인 컴퓨터에만 의존하면 절전과 네트워크 변화에 취약하고, Docker만 사용하면 호스트 권한과 마운트 설정을 직접 관리해야 하며, 공개된 임시 서버는 인증과 TLS를 빠뜨리기 쉽습니다. 반대로 SSHMac의 원격 Mac 환경을 임시 개발 작업이나 Apple 도구 체인 확인에 연결하면 로컬 장비를 계속 켜 둘 필요를 줄이고, 실행 위치를 별도로 관리할 수 있습니다. 장기적으로 고정된 고부하 작업이나 물리 장치가 필요한 경우에는 직접 장비를 운영하는 편이 맞지만, 짧은 검증과 팀용 테스트 환경이라면 원격 Mac을 선택지로 비교할 가치가 있습니다.