VPS에 OpenHands 설치 및 보안 설정 방법

OpenHands의 정의 및 우선적으로 이해해야 할 위험 요소

OpenHands(구 OpenDevin)는 자율 소프트웨어 엔지니어링 에이전트입니다. 사용자가 일상 언어로 작업을 지시하면, 에이전트는 작업 계획을 수립하고, 코드를 작성하며, 명령어를 실행하고, 출력값을 읽으며, 작업이 완료될 때까지 반복합니다. Docker를 사용하여 개인 서버에서 실행하거나, 언어 모델을 연결하여 사용할 수 있습니다. VPS에서 실행하면 사용자가 부재 중일 때도 작동하는 코딩 에이전트가 됩니다.

설정 시 반드시 고려해야 할 사실이 있습니다. OpenHands는 단순히 코드를 제안하는 것이 아니라 직접 실행합니다. 이를 위해 controller 컨테이너는 각 작업에 대한 sandbox 컨테이너를 생성할 수 있도록 호스트의 Docker socket을 /var/run/docker.sock에 마운트합니다. Docker socket에 접근할 수 있는 모든 프로세스는 호스트의 전체 파일 시스템을 마운트하는 새 컨테이너를 시작할 수 있습니다. 즉, socket 접근 권한은 실질적으로 해당 머신의 root 권한과 같습니다. 따라서 OpenHands가 설치된 환경은 신뢰할 수 없는 코드가 실행되는 서버로 간주해야 합니다. 아래의 모든 보안 강화 조치는 이 사실을 바탕으로 합니다.

요구 사항

최신 Docker Engine이 설치된 Ubuntu 24.04 VPS, 최소 4 GB RAM, 그리고 언어 모델용 API key(OpenAI, Anthropic, Google 중 하나) 또는 동일 VPS 내 Ollama를 통한 로컬 모델이 필요합니다. OpenHands는 수십 개의 모델 백엔드를 지원하므로 선택은 자유입니다. 컨테이너 설정 경험이 없다면, 이 가이드에서 전제하는 VPS에서 Docker를 사용하는 기본 사항을 참고하십시오.

Docker를 이용한 설치

OpenHands는 두 개의 이미지로 제공됩니다. 실행용 애플리케이션 이미지와 각 작업의 sandbox를 실행하기 위해 pull 받는 agent-server 이미지입니다. 프로젝트 문서의 최신 태그를 사용하여 다음과 같이 실행하십시오.

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 127.0.0.1:3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands \
  docker.openhands.dev/openhands/openhands:1.8

혼란을 방지하기 위한 두 가지 세부 사항이 있습니다. 애플리케이션 이미지와 agent-server 이미지는 의도적으로 버전 번호가 다르게 지정되어 있으므로, 두 버전을 일치시키려 하지 마십시오. 문서에서 애플리케이션 버전과 쌍을 이루도록 명시한 agent-server 태그를 사용하십시오. 또한 -p 3000:3000가 아닌 -p 127.0.0.1:3000:3000를 사용해야 함에 유의하십시오. 이 차이는 Web UI를 본인만 접근 가능하게 할지, 아니면 인터넷 전체에 공개할지를 결정하며, 이에 대한 내용은 다음 섹션에서 다룹니다.

Web UI를 공용 인터넷으로부터 격리

OpenHands는 3000번 포트에서 인터페이스를 제공합니다. 이 인터페이스는 코드를 실행하는 에이전트를 제어하므로, 이를 인터넷에 공개하면 누구나 명령어를 실행할 수 있는 원격 경로를 갖게 됩니다. 위 실행 명령처럼 loopback에 바인딩하고, SSH 터널을 통해 노트북에서 접속하십시오.

ssh -L 3000:127.0.0.1:3000 you@your-vps

그 다음 로컬 머신에서 http://127.0.0.1:3000를 엽니다. 트래픽은 기존 SSH 세션을 통해 전달되며, 공용 인터넷에는 새로운 리스닝 포트가 생기지 않습니다. 더 영구적인 설정을 원한다면 VPN 뒤에 배치하십시오. 어떤 방식이든, 실수로 노출되는 일이 없도록 방화벽을 설정해야 합니다. 이때 IPv4만 방어하는 방화벽은 IPv6에서 동일한 포트를 열어둘 수 있으며, 이는 많은 사용자가 겪는 IPv6 방화벽 격차 문제입니다.

모델 API 키 및 저장소 자격 증명 격리

OpenHands는 모델 사용을 위한 API key와 저장소 클론/푸시를 위한 토큰이 필요합니다. 두 정보 모두 비용을 발생시키거나 사용자 권한으로 동작할 수 있으므로 비밀번호와 동일하게 취급하십시오. 이 정보들은 적절한 계정만 읽을 수 있는 환경 변수 파일에 보관해야 합니다. 쉘 히스토리나 프로세스 목록에 남는 실행 명령어에 직접 입력하거나, git 저장소 내부 파일에 저장하지 마십시오.

폐기 가능한 환경에서 실행

controller가 Docker socket을 보유해야 하므로, OpenHands를 호스트로부터 완전히 격리하는 것은 불가능합니다. 가장 현실적인 완화 방법은 배치(placement)를 통한 격리입니다. 데이터베이스나 웹사이트가 실행 중인 서버가 아닌, 중요한 데이터가 없는 전용 VPS에서 OpenHands를 실행하십시오. 시작 전 스냅샷을 생성하고, 에이전트가 작성한 코드가 일주일 동안 실행된 서버를 그대로 믿기보다는 스냅샷에서 복구하여 사용하십시오. 저렴하고 일회용으로 사용할 수 있는 단일 목적 VPS가 가장 적합한 환경입니다.

서버 보안 강화

나머지는 표준적인 서버 관리 절차입니다. OpenHands의 작업 부하는 일반적인 경우보다 위험하므로 보안이 더욱 중요합니다. 비특권 사용자로 서비스 실행하기를 참고하여 root 대신 권한이 제한된 관리자 계정을 생성하십시오. SSH는 키 기반 인증만 허용하도록 설정하십시오. 그 다음 아래 체크리스트를 실행하고 이를 기록해 두십시오.

단순 실행을 넘어 구성 요소를 이해하려면 VPS에서 자체 AI 에이전트 구축하기를, 코딩 부담이 적은 플랫폼을 원한다면 Dify 셀프 호스팅을 참고하십시오.

FAQ

OpenHands를 서버에서 실행하는 것이 안전합니까?

주의를 기울인다면 가능하지만, 일반적인 웹 앱보다 위험합니다. 코드를 직접 작성하고 실행하며, controller가 호스트의 Docker socket(실질적 root 권한)을 보유하기 때문입니다. 중요한 데이터가 없는 전용 VPS에서 실행하고, Web UI는 SSH 터널이나 VPN을 통해 loopback으로 유지하며, 키를 격리하고 서버를 보안 강화하십시오. 중요한 서비스와 함께 실행하지 마십시오.

OpenHands에 왜 Docker socket이 필요합니까?

OpenHands는 각 작업을 새로운 sandbox 컨테이너에서 실행합니다. 이를 위해 controller에 /var/run/docker.sock를 마운트하여 호스트 Docker 데몬에 컨테이너 생성을 요청합니다. 이로 인해 controller 컨테이너가 호스트의 Docker를 제어할 수 있게 되며, 이는 강력하지만 위험하므로 호스트 자체를 신뢰할 수 없는 코드가 실행되는 환경으로 간주해야 합니다.

유료 API 대신 로컬 모델을 사용할 수 있습니까?

네, 가능합니다. OpenHands는 Ollama 또는 vLLM을 통해 제공되는 로컬 모델을 지원합니다. 따라서 토큰당 비용 발생 없이, 데이터가 서버 외부로 나가지 않도록 완전한 셀프 호스팅 방식으로 실행할 수 있습니다. 성능이 검증된 코딩 모델을 구동할 수 있는 충분한 메모리를 가진 머신이 필요합니다.

메인 서버에서 OpenHands를 실행해도 됩니까?

아니요. OpenHands는 에이전트가 작성한 코드를 실행하고 Docker socket을 보유하므로, 언제든 재구축할 수 있는 별도의 단일 목적 VPS에서 실행하십시오. 데이터베이스, 웹사이트 또는 기타 서비스와 함께 실행하면, 에이전트의 실수나 버그로 인해 접근 권한이 없는 영역까지 침해될 수 있습니다.