VPS에 OpenHands 설치 및 보안 설정 가이드

OpenHands란 무엇이며, 가장 먼저 이해해야 할 위험 요소

OpenHands(구 OpenDevin)는 자율형 소프트웨어 엔지니어링 에이전트입니다. 평문으로 작업을 지시하면 에이전트가 계획을 수립하고, 코드를 작성하며, 명령어를 실행하고, 출력 결과를 읽은 뒤 작업이 완료될 때까지 반복합니다. 이 도구는 Docker를 사용하여 자체 서버에서 실행하며, 언어 모델과 연결합니다. VPS에서 실행하면 사용자가 자리를 비운 사이에도 코딩 작업을 수행하는 에이전트가 됩니다.

전체 설정을 구성할 때 반드시 고려해야 할 사실이 하나 있습니다. OpenHands는 단순히 코드를 제안하는 데 그치지 않고 직접 실행까지 수행합니다. 이를 위해 컨트롤러 컨테이너는 호스트의 Docker 소켓을 /var/run/docker.sock 경로에 마운트하여 각 작업마다 샌드박스 컨테이너를 생성합니다. Docker 소켓과 통신할 수 있는 모든 주체는 호스트의 전체 파일 시스템을 마운트하는 새로운 컨테이너를 시작할 수 있으며, 이는 곧 소켓 접근 권한이 해당 머신의 root 권한과 동일함을 의미합니다. 따라서 OpenHands가 설치된 서버는 신뢰할 수 없는 코드를 실행하는 서버로 간주해야 합니다. 실제로 이 도구는 정확히 그런 방식으로 동작하기 때문입니다. 아래에 기술된 모든 보안 강화 조치는 이러한 전제에서 비롯됩니다.

필요한 사항

Ubuntu 24.04가 실행 중인 VPS, 최신 Docker Engine, 최소 4 GB의 RAM, 그리고 언어 모델(OpenAI, Anthropic, Google)의 API 키가 필요합니다. 또는 동일한 VPS에서 Ollama로 서비스 중인 로컬 모델을 사용할 수도 있습니다. OpenHands는 수십 가지 모델 백엔드를 지원하므로 원하는 것을 선택하면 됩니다. 컨테이너를 설정해 본 적이 없다면, VPS에서 Docker 사용하기 기초를 통해 이 가이드에서 전제로 하는 기본 지식을 확인할 수 있습니다.

Docker를 이용한 설치

OpenHands는 두 개의 이미지로 제공됩니다. 하나는 사용자가 실행하는 애플리케이션 이미지이고, 다른 하나는 각 작업의 샌드박스를 실행하기 위해 애플리케이션이 가져오는 에이전트 서버 이미지입니다. 프로젝트 문서에 명시된 최신 태그를 사용하여 다음과 같이 실행하십시오.

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

다음 두 가지 사항을 유의하면 시간을 절약할 수 있습니다. 애플리케이션 이미지와 에이전트 서버 이미지의 버전 번호는 의도적으로 다르게 설정되어 있으므로, 두 버전을 억지로 맞추려 하지 마십시오. 문서에서 애플리케이션 버전과 함께 제공하는 에이전트 서버 태그를 사용해야 합니다. 또한 -p 3000:3000가 아닌 -p 127.0.0.1:3000:3000를 사용한다는 점에 주목하십시오. 이 작은 차이가 웹 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 세션을 통해 전달되며, 공용 인터넷에서 새로 수신 대기하는 포트는 없습니다. 모든 에이전트가 포트를 필요로 하는 것은 아닙니다. 같은 VPS에서 실행되는 Claude Code 세션은 터미널을 통해 서로 통신하므로, 외부로 노출하는 것은 SSH뿐입니다. 이러한 루프백 및 터널링 습관은 호스팅하는 모든 에이전트 대시보드에 적용하는 것이 좋습니다. open-kritt의 스캔 UI에 터널을 통해 접속하는 방식도 포트 5173을 사용할 뿐 동일하게 작동합니다. 더 영구적인 설정을 원한다면 VPN 뒤에 배치하십시오. 어떤 방식을 선택하든 서버 앞단에 기본 거부(default-deny) 방화벽을 설정하여 실수로 노출되는 일이 없도록 해야 합니다. 또한 IPv4만 차단하는 방화벽은 IPv6에서도 동일한 포트를 열어두게 된다는 점을 명심하십시오. 이는 많은 사용자가 간과하는 IPv6 방화벽의 허점입니다.

모델 키와 저장소 자격 증명 격리

OpenHands는 모델을 사용하기 위한 API 키가 필요하며, 저장소를 복제하고 푸시하기 위한 토큰이 필요한 경우가 많습니다. 두 정보 모두 비용을 발생시키거나 사용자 권한으로 동작할 수 있으므로 비밀번호처럼 취급해야 합니다. 해당 정보는 적절한 계정만 읽을 수 있는 환경 파일에 보관하십시오. 셸 기록이나 프로세스 목록에 남게 되는 실행 명령줄에 직접 입력해서는 안 되며, git 저장소 내부의 파일에 포함해서도 안 됩니다. 원본을 자체 호스팅하는 비밀번호 관리자에 보관하는 경우 해당 서버도 강화해야 합니다. 금고의 취약점은 암호화된 항목 자체보다는 관리자 토큰이나 백업 파일에 있기 때문이며, 이는 Vaultwarden 강화 가이드에서 다루는 내용과 같습니다.

폐기 가능한 서버에서 실행하기

컨트롤러가 Docker 소켓을 점유해야 하므로, OpenHands를 호스트로부터 완전히 격리하는 것은 불가능합니다. 가장 확실한 완화책은 배치 격리입니다. 데이터베이스나 웹사이트가 실행 중인 서버가 아닌, 다른 중요한 데이터가 없는 전용 VPS에서 OpenHands를 실행하십시오. 시작하기 전에 스냅샷을 생성하고, 에이전트가 작성한 코드를 일주일간 실행한 서버를 신뢰하기보다는 스냅샷을 통해 서버를 재구축하는 것이 좋습니다. 저렴하고 일회용인 단일 목적의 VPS가 가장 적합한 환경입니다. 배치 방식이 OpenHands에서 제공하는 유일한 제어 수단이므로, 에이전트가 중단하고 사용자에게 확인을 요청하기 전까지 수행할 작업 범위를 제어하고 싶다면 Claude Code의 권한 모드를 통해 아무도 지켜보지 않는 서버에서 두 번째 제어 수단이 어떻게 작동하는지 확인하십시오.

주변 환경 강화하기

나머지는 표준적인 서버 위생 관리이며, 일반적인 작업보다 위험도가 높으므로 더욱 중요합니다. 권한 없는 사용자로 서비스 실행하기를 참고하여 root 계정 대신 권한이 제한된 관리자 계정을 생성하십시오. SSH는 키 기반 인증만 사용하도록 설정합니다. 그런 다음 아래 체크리스트를 실행하고 다시 확인할 수 있는 곳에 보관하십시오.

단순히 실행하는 것을 넘어 구성 요소를 이해하려면 VPS에서 직접 AI 에이전트 구축하기를 참조하십시오. 로우코드 플랫폼을 선호한다면 Dify 셀프 호스팅이 더 쉬운 시작점이 될 것입니다.

FAQ

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

주의를 기울이면 안전할 수 있지만, 일반적인 웹 애플리케이션보다 위험합니다. OpenHands는 코드를 작성하고 실행하며, 컨트롤러가 호스트의 Docker 소켓을 점유하기 때문입니다. 이는 사실상 해당 머신의 root 권한을 갖는 것과 같습니다. 다른 중요한 데이터가 없는 전용 일회용 VPS에서 실행하고, Web UI는 SSH 터널이나 VPN을 통해 loopback으로 연결하며, 키를 격리하고 서버를 강화하십시오. 중요한 서비스와 함께 실행하지 마십시오.

OpenHands는 왜 Docker 소켓이 필요한가요?

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

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

네. OpenHands는 Ollama나 vLLM으로 제공되는 로컬 모델을 지원하므로, 토큰당 비용 없이 데이터를 서버 외부로 유출하지 않고 완전히 자체 호스팅할 수 있습니다. 유능한 코딩 모델을 구동할 만큼 충분한 메모리를 갖춘 머신이 필요하며, 이는 Ollama 가이드에서 다루는 사이징 기준과 동일합니다.

메인 서버에서 OpenHands를 실행해도 될까요?

아니요. 에이전트가 작성한 코드를 실행하고 Docker 소켓을 점유하므로, 언제든 재구축할 수 있는 별도의 단일 목적 VPS에서 실행하십시오. 데이터베이스, 웹사이트 또는 다른 서비스와 함께 배치하면 에이전트의 실수나 버그가 의도치 않은 영역까지 영향을 미칠 수 있습니다.