노트북이 절전 모드에 들어갈 때마다 OpenHands의 긴 작업이 중단된다면, 개인 개발 컴퓨터가 아니라 독립적이고 다시 만들 수 있는 원격 VM에 Agent Canvas를 배포하는 것이 가장 빠른 해결책입니다. 먼저 SSH 터널이나 사설망에서 기능을 검증하고, 그다음 세션 API 키, TLS, 프로세스 보존 실행, 샌드박스를 추가하십시오. Xcode나 맥 전용 도구 체인이 필요한 경우에만 원격 맥을 별도 백엔드로 연결하면 됩니다.
이 글은 다음 독자를 대상으로 합니다.
- 노트북 절전이나 네트워크 변경으로 OpenHands 작업이 끊기는 개인 개발자
- 팀이 공유할 Agent Server를 운영하려는 플랫폼·DevOps 엔지니어
- Xcode, 시뮬레이터, 코드 서명까지 원격으로 처리하려는 개발 책임자
마지막 업데이트: 2026년 8월 14일. 실행 명령, 포트 구성, API Key 동작, 원격 백엔드 구조는 OpenHands 공식 자체 호스팅 안내, 공식 저장소 README, Agent Canvas 릴리스 기록을 기준으로 확인했습니다.
배포 목표와 실행 경계
원격 VM을 고르는 이유는 단순히 컴퓨터를 인터넷에 옮기기 위해서가 아닙니다. Agent Canvas는 프런트엔드 화면만 제공하는 도구가 아니라 Agent Server와 자동화 백엔드에 연결해 실제 파일을 읽고, 쓰고, 명령을 실행하는 제어 화면입니다. 공식 구조에서는 하나의 Agent Server가 한 호스트와 포트에서 실행되고, 하나의 Agent Canvas가 여러 백엔드 사이를 전환할 수 있습니다.
따라서 원격 호스트의 역할을 먼저 정해야 합니다.
-
제어 서비스만 실행하는 호스트
화면과 Agent Server를 운영하지만 실제 빌드는 별도 실행 환경으로 보냅니다. -
코드 작업과 빌드를 함께 맡는 호스트
저장소를 읽고 테스트와 빌드까지 같은 VM에서 처리합니다. 운영은 단순하지만 파일과 자격 증명이 한곳에 모입니다. -
외부 샌드박스에 연결하는 호스트
Agent Canvas는 원격 VM에 두고, 실제 에이전트 실행은 Docker 샌드박스나 별도 Agent Server에서 담당합니다.
일반적인 백엔드 개발, 웹 테스트, 코드 분석이라면 Linux VM이 우선입니다. 반대로 Xcode, 애플 플랫폼 시뮬레이터, 코드 서명처럼 macOS 도구 체인이 필요한 저장소는 Linux VM에서 해결하려 하지 말고 원격 맥을 추가해야 합니다. 공식 저장소도 Agent Server 실행 위치로 노트북, 전용 맥, 클라우드 VM을 모두 제시하지만, 각 환경의 파일과 네트워크 접근 범위는 별도로 관리해야 한다고 설명합니다.
첫 단계: 사설망에서 최소 서비스 확인
처음부터 도메인과 공개 HTTPS를 구성하면 문제가 생겼을 때 원인이 늘어납니다. 첫 목표는 “화면이 열리고, 백엔드가 연결되며, 실제 저장소에서 한 번의 작업이 끝나는가”로 제한하십시오.
공식 자체 호스팅 안내는 Ubuntu에서 curl, git, Node.js 22.x, uv를 준비하는 흐름을 제시합니다. 현재 공식 README의 실행 조건에는 Node.js 22.12.x 이상과 uv가 적혀 있으므로, 설치 전 Node.js 22 공식 문서와 저장소의 요구 버전을 다시 확인해야 합니다. uv 설치 방식은 uv 공식 설치 안내와 대조하십시오.
sudo apt-get update
sudo apt-get install -y curl git
curl -LsSf https://astral.sh/uv/install.sh | sh
첫 실행은 외부 공개가 아니라 SSH 터널로 제한하는 편이 좋습니다.
ssh -N -L 8000:127.0.0.1:8000 사용자명@원격VM주소
그다음 원격 VM에서 Agent Canvas를 실행합니다.
npx @openhands/agent-canvas
로컬 브라우저에서는 http://127.0.0.1:8000으로 접근합니다. 공식 배포 구조에서 명령 하나가 정적 프런트엔드, Agent Server, 자동화 백엔드를 시작하고 내부 수신 대기 지점으로 연결합니다. 내부 구성에는 정적 서버 3001, Agent Server 18000, 자동화 백엔드 18001이 표시되지만, 이 숫자를 외부 공개 포트로 오해하면 안 됩니다. 외부 사용자는 내부 서비스가 아니라 역방향 프록시를 통해 접속해야 합니다.
첫 작업의 검증 증거는 다음 네 가지로 잡으십시오.
- 브라우저에서 화면이 열립니다.
- 선택한 Agent Server가 연결됨 상태로 표시됩니다.
- 원격 VM의 저장소 경로를 읽습니다.
- 명령 실행 결과와 실시간 이벤트가 마지막까지 돌아옵니다.
저장소가 읽히지 않는다면 모델 설정부터 바꾸지 말고 작업 디렉터리, 사용자 권한, Git 체크아웃 위치를 먼저 확인하십시오.
구성 선택: 호스트 실행과 Docker 샌드박스
Agent Canvas를 호스트에서 직접 실행하면 설치가 빠릅니다. 대신 에이전트가 해당 호스트의 파일 시스템, 환경 변수, 네트워크에 접근할 수 있다는 점을 감수해야 합니다. 공식 README도 샌드박스 없이 실행하는 방식에 대해 호스트 전체 접근 위험을 명시합니다.
Docker 샌드박스는 접근할 프로젝트 경로를 명시할 수 있다는 점이 다릅니다. 공식 예시에서는 PROJECTS_PATH 아래의 프로젝트를 /projects로 연결하고, Agent Canvas 상태 디렉터리를 별도 볼륨으로 보존합니다. Docker의 권한과 격리 한계는 Docker 공식 보안 문서도 함께 확인해야 합니다. 샌드박스가 모든 위험을 제거하는 것은 아니지만 “어떤 디렉터리를 에이전트에게 보여줄 것인가”를 운영 설정으로 고정하기 쉬워집니다.
| 운영 방식 | 격리 수준 | 관리 난이도 | 적합한 작업 | 판단 |
|---|---|---|---|---|
| 호스트 직접 실행 | 낮음 | 낮음 | 신뢰할 수 있는 개인 테스트 | 단기 검증용 |
| Docker 샌드박스 | 중간 | 중간 | 팀 공유, 저장소별 제한 실행 | 기본 선택 |
| 별도 Agent Server | 환경별 상이 | 높음 | 민감 저장소, 역할별 분리 | 규모가 커질 때 |
| 원격 맥 백엔드 | macOS 환경 제공 | 중간 이상 | Xcode, 시뮬레이터, 서명 | 필요한 경우만 |
Docker를 선택해도 비밀 환경 변수, SSH 키, 클라우드 자격 증명을 컨테이너에 무심코 마운트하면 격리 효과가 줄어듭니다. 프로젝트 디렉터리와 캐시 디렉터리를 분리하고, 운영용 저장소의 배포 키를 개발용 Agent Server에 넣지 않는 방식으로 경계를 유지하십시오.
두 번째 단계: API Key와 파일 권한 고정
최초의 원격 실행이 끝났다면 공개 접속 전에 인증과 권한을 정리해야 합니다. 공식 안내는 LOCAL_BACKEND_API_KEY를 생성하고 공개 모드로 실행하는 방식을 제시합니다. openssl rand -base64 32로 생성하는 키는 공식 설명상 256비트 무작위 키이며, 셸의 export를 이용하면 일반적인 프로세스 목록에 키가 직접 명령 인자로 노출되는 것을 피할 수 있습니다.
export LOCAL_BACKEND_API_KEY=$(openssl rand -base64 32)
npx @openhands/agent-canvas --public
여기서 키를 다음 위치에 넣으면 안 됩니다.
- 공개 Git 저장소의 설정 파일
- 브라우저에 내려가는 정적 자바스크립트 파일
- 복사해 공유하는 셸 기록
- 오류 로그와 작업 결과 로그
- 팀 위키의 접근 제한 없는 페이지
공개 모드에서는 사용자가 화면에 키를 입력해야 하며, API 요청에는 X-Session-API-Key 헤더가 필요합니다. 그러나 API Key만으로 모든 보안 문제가 해결되는 것은 아닙니다. Agent Server가 실행되는 호스트의 방화벽, 프로젝트 디렉터리 권한, Git 자격 증명, 환경 변수 범위를 함께 제한해야 합니다.
다음 테스트를 통과하지 못하면 공개 단계로 넘어가지 마십시오.
- 프로젝트 루트 밖의 파일을 읽으려는 요청이 차단됩니다.
- 잘못된 API Key 요청이 거부됩니다.
- 작업 계정이 배포용 비밀 파일을 읽지 못합니다.
- 저장소에 없는 위험 명령이 실행되지 않도록 별도 확인 절차가 작동합니다.
- 로그에 API Key와 개인 접근 토큰이 남지 않습니다.
보안 설정과 계정 처리 기준은 SSHMac 도움 센터에서 사용하는 원격 환경 운영 문서와 함께 관리하면 팀 인수인계가 쉬워집니다. 개인정보나 접근 기록을 다루는 조직이라면 개인정보 처리방침도 검토 대상에 포함하십시오.
세 번째 단계: TLS와 보존 실행
SSH 터널은 첫 검증에는 알맞지만, 여러 사용자가 브라우저로 접속하거나 외부 자동화를 연결하기에는 부족합니다. 공개 접속으로 전환할 때는 도메인, TLS 역방향 프록시, 방화벽을 함께 구성해야 합니다.
공식 VM 안내의 기본 구성은 다음과 같습니다.
- SSH 22번: 자신의 IP나 VPN 대역만 허용
- HTTP 80번: 인증서 발급이 필요할 때만 허용
- HTTPS 443번: 가능하면 허용 IP를 제한
- 내부 수신 대기 포트: 외부에서 직접 접근하지 않음
nginx는 TLS를 종료한 뒤 127.0.0.1:8000의 수신 지점으로 요청을 넘깁니다. /api와 /sockets 경로를 Agent Server로 전달하므로, 일반 HTTP 요청만 통과시키는 설정은 실시간 이벤트를 끊을 수 있습니다. 웹소켓 프록시 헤더 구성은 nginx 공식 웹소켓 문서와 함께 확인하십시오.
서비스 보존 실행은 두 단계로 나누면 됩니다.
빠른 테스트
tmux new-session -d -s canvas \
'npx @openhands/agent-canvas --public'
장기 운영
공식 안내는 systemd 서비스에 Restart=on-failure와 네트워크 이후 시작 조건을 넣는 구성을 권장합니다. 서비스 파일에 키를 직접 기록할 때는 파일 권한을 제한하고, 가능하면 별도 환경 파일이나 비밀 관리 체계를 사용하십시오. 예시 구성에는 장애 뒤 5초 후 재시작하는 RestartSec=5가 포함되어 있습니다. 재시작 동작의 세부 조건은 systemd 서비스 공식 문서에서 확인할 수 있습니다.
[Unit]
Description=Agent Canvas
After=network.target
[Service]
Environment=LOCAL_BACKEND_API_KEY=저장한키
ExecStart=npx @openhands/agent-canvas --public
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now agent-canvas
운영 전에는 SSH를 끊고, Agent Canvas 작업을 계속 실행한 다음, 서비스를 재시작하고, VM을 재부팅하십시오. 화면이 다시 열리는 것만으로는 부족합니다. 기존 작업 기록, 웹소켓 이벤트, 저장소 변경 상태가 올바른 백엔드에서 이어지는지 확인해야 합니다.
원격 백엔드 전환과 저장소 동기화
로컬 프런트엔드를 계속 사용하고 싶다면 원격 VM을 추가 백엔드로 등록할 수 있습니다. 로컬 Agent Canvas의 백엔드 관리 화면에서 원격 주소와 세션 API 키를 입력하는 흐름을 사용합니다. SSH 터널을 사용할 때는 로컬 주소를, 공개 HTTPS를 사용할 때는 도메인 주소를 사용합니다.
이때 가장 자주 생기는 오해는 백엔드 전환이 파일 동기화를 뜻하지 않는다는 점입니다. 로컬 컴퓨터의 커밋하지 않은 변경 사항이 원격 VM으로 자동 이동하지는 않습니다. 다음 중 하나를 명시적으로 선택해야 합니다.
- Git 브랜치와 커밋을 원격에서 다시 체크아웃합니다.
- 안전한 파일 전송 절차로 작업 디렉터리를 복사합니다.
- 원격 VM에서 별도의 작업 브랜치를 생성합니다.
- 로컬과 원격의 작업 경로를 화면에 표시해 혼동을 줄입니다.
원격 백엔드를 등록한 뒤에는 저장소 경로, Agent 설정, 모델 연결, 작업 기록이 모두 같은 환경을 가리키는지 확인하십시오. 특히 로컬에서는 존재하지만 원격 VM에는 없는 .env 파일이나 도구 체인이 작업 결과를 바꾸는 경우가 많습니다.
원격 맥을 추가하는 조건
OpenHands Agent Canvas를 원격 VM에 배포했다고 해서 모든 빌드를 Linux에서 처리해야 하는 것은 아닙니다. 다만 원격 맥은 “더 빠른 서버”가 아니라 macOS 도구 체인을 제공하는 별도 실행 노드로 판단해야 합니다.
Linux VM에 남겨도 되는 작업은 다음과 같습니다.
- 일반 코드 분석과 리팩터링
- 웹 서버와 API 테스트
- 대부분의 백엔드 빌드
- 의존성 점검과 문서 생성
- Git 변경 사항 검토
원격 맥으로 보내야 하는 작업은 다음과 같습니다.
- Xcode 프로젝트 빌드
- 애플 플랫폼 시뮬레이터 실행
- 코드 서명과 인증서 연동
- macOS 전용 프레임워크 확인
- 맥에서만 재현되는 패키지 또는 파일 시스템 문제
Agent Canvas는 여러 Agent Server를 연결하고 화면에서 전환할 수 있으므로, Linux VM과 원격 맥을 역할별로 나누는 방식이 가능합니다. 단, 원격 맥에 서명 키와 배포 인증서를 넣는 순간 보안 등급이 달라집니다. 팀 전체가 사용하는 공용 백엔드에 개인 서명 자격 증명을 그대로 넣지 말고, 저장소와 작업자를 분리하십시오.
자주 확인하는 배포 질문
클라우드 서버 설치 조건
클라우드 VM에 설치할 수 있습니다. 다만 개인 개발 컴퓨터를 그대로 공개하기보다 다시 만들 수 있는 독립 VM을 사용해야 합니다. 에이전트가 실행 호스트의 파일, 환경 변수, 네트워크에 접근할 수 있으므로 방화벽과 세션 API 키를 먼저 설정하고, 실제 저장소로 최소 작업을 끝낸 뒤 공개 접속으로 넘어가십시오.
SSH 연결 종료 뒤 작업 유지
첫 테스트는 SSH 터널과 tmux로 충분하지만, 장기 운영은 systemd 같은 서비스 관리자를 사용하는 편이 안전합니다. 자동 재시작 조건과 호스트 재부팅 뒤 자동 시작을 설정하십시오. 웹소켓 실시간 이벤트가 다시 연결되는지까지 확인해야 단순히 프로세스가 남아 있는 상태와 실제 복구를 구분할 수 있습니다.
외부에 열 포트
사설망에서만 운영할 때는 외부에 SSH만 제한적으로 열고 Agent Canvas의 내부 포트는 127.0.0.1에 남겨 두십시오. 공개 접속이 필요하면 TLS를 종료하는 443과 인증서 발급에 쓰는 80을 검토합니다. 8000, 18000, 18001, 3001은 외부에 직접 공개하지 않는 편이 안전합니다.
원격 맥이 필요한 작업
Xcode, 애플 플랫폼 시뮬레이터, 코드 서명, 맥 전용 빌드 도구가 실제 작업에 포함될 때 원격 맥을 추가하십시오. 일반적인 코드 분석, 웹 서비스 테스트, 대부분의 Linux 기반 빌드는 Linux VM으로 처리하는 편이 운영이 단순합니다. 원격 맥은 도구 체인 의존성이 확인된 저장소에만 별도 백엔드로 연결하십시오.
공개 접속 보안
공개 모드와 독립적인 세션 API 키를 함께 사용하고, 방화벽에서 내부 서비스 포트를 차단한 뒤 HTTPS 역방향 프록시를 배치해야 합니다. 키를 공개 저장소, 정적 프런트엔드, 명령 기록에 넣지 마십시오. 이후 권한 없는 요청, 프로젝트 밖의 파일 읽기, 위험 명령 실행을 시험해 실제 접근 경계가 지켜지는지 확인해야 합니다.
출시 전 점검 목록
다음 항목을 모두 확인한 뒤 장기 운영으로 전환하십시오.
- [ ] 개인 개발 컴퓨터가 아닌 독립 VM 또는 별도 장비를 선택했습니다.
- [ ] Agent Canvas의 작업 디렉터리와 보존할 상태 디렉터리를 구분했습니다.
- [ ] 첫 실행을 SSH 터널이나 VPN 내부에서 완료했습니다.
- [ ] Node.js와
uv버전을 공식 문서와 저장소 기준으로 확인했습니다. - [ ]
LOCAL_BACKEND_API_KEY를 새로 생성하고 공개 저장소에 넣지 않았습니다. - [ ] 22번 포트는 제한된 IP 또는 VPN 대역에서만 접근됩니다.
- [ ] 8000, 18000, 18001, 3001 포트는 외부에 직접 공개되지 않습니다.
- [ ] 공개 접속 시 nginx 또는 동등한 TLS 역방향 프록시를 사용합니다.
- [ ]
/sockets같은 실시간 연결이 프록시를 통과합니다. - [ ] SSH 연결 종료 뒤에도 작업이 계속됩니다.
- [ ] 서비스 재시작과 VM 재부팅 뒤 자동 복구됩니다.
- [ ] 프로젝트 밖 파일, 비밀 환경 변수, 배포 키 접근을 테스트했습니다.
- [ ] 로컬 백엔드와 원격 백엔드의 저장소 경로를 구분했습니다.
- [ ] Xcode나 맥 전용 도구가 필요한 저장소만 원격 맥으로 라우팅합니다.
- [ ] 실제 저장소에서 시작, 실행, 실패, 재시작, 빌드까지 한 번의 폐쇄형 테스트를 완료했습니다.
현재 개인 노트북에 계속 의존하면 절전과 네트워크 변경으로 장기 작업이 끊기고, 개인 자격 증명과 프로젝트 파일이 한 장치에 모이며, 팀 공유를 위해 별도 권한 체계를 다시 만들어야 합니다. Linux VM만으로 버티면 Xcode와 코드 서명 단계에서 빌드가 멈춥니다. 이 조건이라면 기본 실행은 독립 VM에 두고, macOS 도구 체인이 필요한 저장소에만 SSHMac의 지속 실행 원격 맥 환경을 추가하는 편이 운영 비용과 실패 지점을 함께 줄이는 방향입니다.
먼저 최소 VM 배포를 완료한 뒤, 저장소의 빌드 도구와 보안 요구를 기준으로 Linux VM만으로 충분한지 확인하십시오. Xcode, 시뮬레이터, 서명까지 필요하다면 SSHMac의 원격 환경 점검 기준을 적용해 지속 실행 가능한 원격 맥 노드를 별도로 검토하는 것이 안전합니다.