SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor · 업데이트됨 2026-11-11

VPS에서 OpenBot AI coworker 직접 호스팅하기

OpenBot `v0.2.0`을 VPS에 직접 호스팅하는 방법과 supervisor 구성을 설명합니다. bot마다 컨테이너, Chromium, workspace를 분리할 때 필요한 RAM과 gateway의 정책 검증 및 작업 기록 방식을 확인합니다.

OpenBot AI 코워커를 직접 호스팅할 때 얻는 것

OpenBot AI 코워커를 직접 호스팅하려면 사용자가 제어하는 하드웨어에서 게이트웨이 서버 하나를 실행하고, 각 봇에게 전용 컨테이너를 할당하는 슈퍼바이저를 구성해야 합니다. 봇별 컨테이너는 COMPUTER_SUPERVISOR_URL가 설정된 경우에만 존재합니다. 이 설정이 없으면 모든 봇이 AGENT_COMPUTER_URL에 있는 하나의 컴퓨터를 공유하게 됩니다. 슈퍼바이저를 사용하면 각 봇 컨테이너는 자체 Chromium 브라우저와 작업 공간 볼륨을 가지며, 세션 간에 유지되는 브라우저 프로필을 사용합니다. 봇이 컴퓨터, 파일, MCP(Model Context Protocol) 서버 또는 UI 구성 요소에서 수행하는 모든 작업은 게이트웨이를 거칩니다. 게이트웨이는 작업 실행 전에 정책을 확인하고 실행 후에는 기록을 남깁니다. 게이트웨이가 감싸고 있는 에이전트 루프가 아직 생소하다면, AI 에이전트 기초 학습의 단계별 경로를 따라 봇에게 브라우저와 로그인 정보를 넘겨주기 전에 직접 작은 루프를 작성해 보시기 바랍니다.

OpenBot은 CopilotKit이 MIT 라이선스로 github.com/CopilotKit/openbot에 공개했습니다. 첫 번째 태그된 릴리스인 v0.0.1은 2026년 8월 17일에 게시되었으며, 2026년 10월 12일에 v0.2.0가 뒤를 이었습니다. 2026년 11월 10일 기준으로 최신 버전은 2026년 11월 9일에 게시된 v1.0.0이며, 이는 v0.3.0 이후 3일 만에 나온 버전입니다. main의 README에는 더 이상 베타 알림이 표시되지 않습니다. 이 프로젝트를 초기 단계의 거친 부분이 있는 진지한 설계로 간주하십시오. 아래의 배포 가이드는 v0.2.0을 고정하며, 모든 단계는 해당 릴리스를 기준으로 설명합니다. v0.3.0에서 승인 방식, 브라우저 공유, Helm 차트 기본값이 변경되었으므로, 더 최신 태그로 시작하기 전에 v0.3.0 및 v1.0.0 릴리스 노트를 읽어보시기 바랍니다. 현재 main은 각 사용자에게 컨테이너를 제공하며, Isolated로 표시된 봇에게도 별도의 컨테이너를 할당합니다.

이 아키텍처에서 흥미로운 부분은 비용이 많이 드는 부분이기도 합니다. 모든 에이전트에 브라우저를 할당하는 것은 많은 사람이 간과하는 메모리 비용이므로, 설치 전에 리소스 규모를 먼저 산정해야 합니다.

게이트웨이가 모든 동작을 결정하는 방식

포트 3001의 API 서버는 봇의 컴퓨터로 향하는 통제된 경로입니다. 이 컴퓨터는 토큰으로 보호되는 하위 수준의 서비스 엔드포인트도 노출합니다. 프로젝트는 해당 엔드포인트를 비공개로 유지하고 게이트웨이를 우회하는 용도로 절대 사용하지 말 것을 권고합니다. 따라서 해당 엔드포인트에 접근할 수 없는 동안에만 게이트웨이가 유일한 경로로 유지됩니다. 브라우저 동작이 실행되기 전, 게이트웨이는 페이지 스냅샷에서 대상을 확인하고, 컨텍스트에 대해 CEL(Common Expression Language) 정책 규칙을 평가하며, 결정 사항이 담긴 감사 행을 기록한 뒤에야 컨테이너를 호출합니다. 그 이후 실행에 실패하면 두 번째 행을 기록합니다. 문서는 경계를 명확히 명시합니다. 컴퓨터는 정책을 결정하지 않으며, 서버 게이트웨이가 동작의 경계입니다. 이러한 분리는 OpenBot 외부에서도 통용되는 개념입니다. 루프, 도구 정의, 권한 검사, 세션 상태가 함께 모델을 감싸는 하네스를 구성하며, 이 게이트웨이는 그중 권한을 담당하는 절반입니다.

정책 평가는 차단(fail closed)되며, 거부 규칙이 허용 규칙보다 먼저 평가됩니다. 규칙 구문보다 실패 방향이 더 중요합니다. 누락되었거나 비어 있는 정책은 아무것도 허용하지 않으며, 잘못된 규칙은 거부 규칙이든 허용 규칙이든 상관없이 차단되는 방향으로 실패합니다. 따라서 정책에 실수가 발생해도 봇이 계정에 무단으로 접근하는 대신 봇이 멈추는 결과가 나타납니다. OpenBot이 제공하는 정책은 별개의 문제입니다. 시작 시 기본값은 deny: []와 allow: ["true"]이며, 이는 AGENT_COMPUTER_POLICY나 저장된 관리자 정책으로 대체되기 전까지 모든 동작을 허용합니다. 따라서 봇이 실제 환경에 접근하기 전에 직접 정책을 작성하십시오. 해당 계층은 봇이 수행하는 동작을 통제할 뿐 봇이 읽는 내용을 통제하지는 않습니다. 따라서 에이전트를 겨냥한 지시 사항이 포함된 페이지는 별개의 문제로 남으며, 이는 직접 운영하는 SearXNG 인스턴스의 결과를 에이전트에 전달할 때 직면하는 프롬프트 인젝션 공격 표면과 동일합니다.

감사 기록은 PostgreSQL에 저장되므로 재시작 후에도 유지됩니다. 제어권 이양은 computer.help_requested, computer.control_taken, computer.control_released로 기록됩니다. 이를 통해 봇이 사람의 개입을 요청하는 과정과 사람이 제어권을 다시 넘겨주는 과정을 확인할 수 있습니다. 비밀 정보는 값이 아닌 문자 수로 기록됩니다. 파일 읽기, 쓰기, 목록 조회는 Activity 탭에 나타나며, 저장된 파일은 내용이 아닌 경로와 크기로 표시됩니다. 해당 뷰는 브라우저에 유지되며 감사 기록과는 다릅니다. 브라우저 없이 동일한 제어 경계를 원한다면 승인을 통해 AI 에이전트 동작을 통제하는 방법에서 더 좁은 범위의 사례를 다룹니다.

봇 하나당 필요한 RAM 및 디스크 용량

이 프로젝트는 arm64 환경에서 봇 하나에 대한 측정치를 공개합니다. 이 수치는 배포 문서에 기재된 산정 기준이며, 특정 아키텍처에서 봇 하나를 기준으로 하므로 용량 계획보다는 시작점으로 참고하십시오.

차트OpenBot published resource figures, one Bot on arm64 (October 2026)
이 차트의 데이터
[
  {
    "label": "Measured, one Bot",
    "memory_gb": 0.55,
    "disk_gb": 1.4,
    "vcpu": 0.06
  },
  {
    "label": "Documented minimum",
    "memory_gb": 2,
    "disk_gb": 4,
    "vcpu": 1
  },
  {
    "label": "Documented recommended",
    "memory_gb": 4,
    "disk_gb": 8,
    "vcpu": 2
  }
]

봇 하나당 최대 메모리 사용량은 0.55 GB로 측정되었으며, 문서상 최소 사양은 2 GB, 권장 사양은 4 GB입니다. 측정치와 최소 사양 사이의 차이는 부하 발생 시 Chromium이 확장될 수 있는 여유 공간입니다. 브라우저의 메모리 사용량은 대기 상태가 아니라 열려 있는 페이지에 따라 변하기 때문입니다. 문서에 따르면 동시에 열리는 추가 페이지당 약 100에서 200 MB의 메모리가 추가로 필요합니다. 유휴 상태의 CPU 점유율은 측정 범위 최상단에서 코어의 0.06 수준으로 거의 0에 가깝기 때문에, CPU 사양은 고려 대상이 아닙니다. 이미지 크기는 1.4 GB이며 권장 볼륨은 8 GB입니다. 이 차이는 봇이 파일을 저장하는 /workspace를 위한 여유 공간입니다. 이미지에는 Chromium 계열 브라우저만 포함되어 있습니다. Playwright의 Firefox와 WebKit은 제외되었습니다.

이 수치들만으로는 여러 봇을 동시에 운영할 때의 비용을 알 수 없으며, 프로젝트 측에서도 이에 대한 수치를 공개하지 않습니다. 문서상의 최소 사양은 부하 상태에서 직접 관찰한 수치가 아니라 프로젝트 측에서 제시하기에 적절하다고 판단한 수치입니다. 이것이 바로 PhotoPrism과 Immich 선택하기에서 공식 발표된 RAM 사양 대신 실제 측정된 최소 RAM 사양을 기준으로 삼는 이유입니다. 직접 측정하십시오. 봇 하나를 실행하고 페이지를 연 상태에서 실제 작업을 수행하게 한 뒤, 작업 중인 컨테이너를 모니터링하십시오.

docker stats --no-stream
free -m

봇 컨테이너의 MEM USAGE 열 값을 봇당 수치로 잡고, 여기에 게이트웨이와 PostgreSQL 사용량을 더한 뒤, 동시에 운영할 봇의 수만큼 봇당 수치를 곱하십시오. 유휴 상태의 봇은 기본값인 30분의 유휴 시간 제한이 지나기 전까지 브라우저를 유지하므로, 유휴 브라우저도 곱셈 계산에 포함해야 합니다. 이 계산 방식은 코딩 에이전트 VPS를 위한 RAM 및 CPU 산정에서 사용된 것과 동일하며, 브라우저 관련 내용은 VPS에서 에이전트를 위한 헤드리스 브라우저 실행에서 다룹니다.

Chromium과 관련된 한 가지 세부 사항이 소규모 플랜에 영향을 줍니다. OpenBot은 --disable-dev-shm-usage 옵션으로 Chromium을 실행하므로, 브라우저는 /dev/shm 대신 /tmp에 데이터를 기록합니다. 이는 /dev/shm이 작은 호스트에서 발생하는 충돌을 방지하지만, 루트 파일 시스템에 부담을 줍니다. 권장 디스크 용량이 이미지 크기보다 큰 이유가 바로 여기에 있습니다.

VPS에서 OpenBot을 직접 호스팅하는 방법

Docker, Bun 1.3 이상 버전, CopilotKit Intelligence 프로젝트 및 라이선스, 그리고 API 키나 지원되는 제공업체 로그인 정보와 같은 모델 접근 권한이 필요합니다. v0.2.0 README는 앱과 API 서버를 위해 Bun 1.3 이상을 요구하지만, 현재 main는 이를 1.4 이상으로 상향 조정했으므로 클론하는 태그의 README를 확인하십시오. v0.0.15 이후부터는 제공업체의 자체 로그인 정보를 API 키 대신 사용할 수 있습니다. 개발 문서에서는 서버에 lsof, openssl, curl이 설치되어 있어야 하며, Intelligence 프로비저닝을 위해 Node의 npx도 필요하다고 명시합니다. main은 초기 프로젝트에서 예고 없이 변경될 수 있으므로 main 대신 태그가 지정된 릴리스를 클론하십시오. 이미 v0.1.x 설치를 운영 중이라면 이동하기 전에 v0.2.0 릴리스 노트를 읽어보십시오. 업그레이드 과정에서 저장된 Composio 연결을 새 테이블로 복사하므로, 이후 v0.1.2로 롤백하면 업그레이드 후에 연결된 계정이 보이지 않게 됩니다.

git clone --branch v0.2.0 https://github.com/CopilotKit/openbot.git
cd openbot
cp .env.example .env
bun install

Intelligence 프로젝트를 프로비저닝합니다. 처음 두 명령어로 로그인하고 프로젝트를 선택합니다. 이후 도우미 스크립트가 해당 프로젝트의 런타임 키를 프로비저닝하고, openbot Learning 컨테이너를 생성하거나 재사용하며, 두 설정을 환경 파일에 기록합니다.

npx --yes copilotkit@latest login
npx --yes copilotkit@latest project select
bun scripts/setup-learning.ts

저장된 자격 증명을 암호화할 키를 생성하고, 그 결과값을 .env 파일에 KEY_ENCRYPTION_KEY로 저장합니다. 같은 파일에 OPENAI_API_KEY을 추가하십시오. 개념 증명(PoC)용 Bot은 OpenAI를 사용합니다. LangGraph Bot의 경우 BOT_PROVIDER를 anthropic 또는 google으로 설정하고 일치하는 키를 추가할 수 있습니다. 키 대신 모델 로그인을 사용하려면 v0.2.0 .env.example에 CLAUDE_CODE_OAUTH_TOKEN, claude setup-token에서 얻은 토큰, 그리고 로그인한 ChatGPT 플랜이 기록하는 파일인 CHATGPT_AUTH_FILE을 입력합니다. API 서버는 내장 에이전트를 위해 이 값들을 읽으며, compose는 이를 선택한 Bot 하네스로 전달합니다.

openssl rand -base64 32

.env가 열려 있는 동안 컴퓨터 설정을 확인하십시오. .env.example은 COMPUTER_SUPERVISOR_URL와 SUPERVISOR_TOKEN를 비워두고, AGENT_COMPUTER_URL이 포트 4100의 공유 컴퓨터 하나를 가리키도록 합니다. compose 파일에는 슈퍼바이저가 포함되어 있으며, scripts/start.sh은 서버에 COMPUTER_SUPERVISOR_URL과 SUPERVISOR_TOKEN를 제공하여 봇별 컴퓨터를 기본적으로 활성화합니다. 서버를 직접 실행하는 경우 두 값을 모두 설정하십시오. 슈퍼바이저 URL이 없으면 모든 봇이 하나의 브라우저와 그 로그인 정보를 공유하게 됩니다.

그런 다음 시작합니다.

bash scripts/start.sh

scripts/start.sh은 Docker 서비스를 가동하고, 데이터베이스 마이그레이션을 실행하며, 서버와 루틴 워커 및 앱을 시작하고 상태를 확인합니다. 완료되면 앱은 포트 3010에서, API는 포트 3001에서 응답합니다. 스크립트는 포트 충돌을 보고하며 이미 실행 중인 일치하는 서비스는 건드리지 않으므로, 두 번 실행해도 안전합니다.

외부에 노출하기 전에 서버 자체에서 확인하십시오.

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3010
ss -ltnp | grep -E ':(3010|3001|4100|4500|5432)'

첫 번째 명령에서 200이 출력되면 앱이 서비스 중임을 의미합니다. 두 번째 명령은 해당 포트가 어떤 주소에 바인딩되어 있는지 보여주며, VPS에서는 이 정보가 중요합니다. 127.0.0.1:3001라고 적힌 줄은 서버 내부에서만 접근 가능함을 의미합니다. 0.0.0.0:3001이라고 적힌 줄은 서버로 라우팅할 수 있는 누구나 접근할 수 있음을 의미합니다.

단일 컨테이너 이미지

배포 문서에는 앱, API, Chromium을 포함하고 포트 3001에서 제공하는 단일 이미지도 포함되어 있다. 이 이미지는 버전 태그와 함께 ghcr.io/copilotkit/openbot으로 게시되거나, 복제한 저장소에서 직접 빌드할 수 있다.

docker build -t openbot .
docker run -p 127.0.0.1:3001:3001 --env-file .env \
  -e EMBEDDED_POSTGRES=on -v openbot-data:/var/lib/postgresql openbot

EMBEDDED_POSTGRES=on은 컨테이너 내부에서 PostgreSQL을 실행하고 시작할 때 migration을 적용한다. named volume을 사용하면 재배포 후에도 audit history가 유지된다. 이 volume이 없으면 다시 빌드할 때마다 해당 history가 삭제된다. volume은 데이터 디렉터리 자체가 아니라 상위 디렉터리인 /var/lib/postgresql에 mount해야 한다. 문서에서는 데이터 디렉터리를 mount하면 cluster가 초기화되지 않은 상태로 남을 수 있다고 경고한다. 그러면 앱이 502로 응답한다. 대신 DATABASE_URL을 managed database로 지정하는 경우에는 해당 데이터베이스에서 vector extension을 활성화해야 한다. RDS, Cloud SQL, Azure Database 같은 managed service는 이 extension을 지원하지만, 어느 서비스도 이를 대신 활성화해 주지 않는다. migration은 이를 실행하는 role이 extension을 소유하고 있다고도 가정한다. 따라서 다른 role로 extension을 생성했다면 must be owner of extension vector에서 중단된다.

데이터베이스가 외부에 있다면 release 단계에서 migration을 실행한다.

docker run --rm --env-file .env --entrypoint sh openbot \
  -c "cd /app/server && bun scripts/migrate.ts"

scripts/migrate.ts를 사용해야 하며 drizzle-kit migrate는 사용하지 않는다. drizzle-kit CLI는 production dependency가 아니므로 production image에 포함되지 않는다. --entrypoint sh은 유지해야 한다. 이 설정이 없으면 migration이 실행되기 전에 API가 시작된다.

이 이미지는 의도적으로 browser port를 publish하지 않는다. 또한 supervisor도 제외한다. supervisor에는 Docker socket이 필요하지만 serverless platform에서는 이를 제공하지 않기 때문이다. supervisor가 없으면 모든 bot이 하나의 browser와 하나의 login 집합을 공유한다. 따라서 bot별 container를 실행할 때 얻을 수 있었던 격리가 사라진다. 이 단일 컨테이너 경로에서는 bot마다 자체 container를 제공하지 않는다. bot별로 별도의 login이 필요한 경우에는 감수할 트레이드오프를 받아들일 수 있는 host에서 COMPUTER_SUPERVISOR_URL 및 SUPERVISOR_TOKEN을 설정해 compose stack을 실행한다. Docker socket과 통신할 수 있는 process는 privileged container를 시작할 수 있다. 따라서 실제로는 host에서 root 권한을 가진다. 이것이 OpenBot을 별도 시스템에 두어야 하는 좋은 이유다. coding agent에 일회용 VM 제공과 같은 원칙이다.

OPENBOT_SINGLE_USER가 노트북 설정인 이유

.env.example는 OPENBOT_SINGLE_USER=true와 함께 제공됩니다. 이 설정은 모든 요청을 하나의 고정된 관리자로 간주하며 로그인 과정을 완전히 생략합니다. 노트북에서는 포트에 접근할 수 있는 클라이언트가 사용자 본인뿐이므로 편리합니다. 하지만 VPS에서는 포트 3010에 접근하는 누구나 해당 관리자가 됩니다. 이는 암호화된 자격 증명을 저장하고 이미 계정에 로그인된 브라우저를 구동하는 시스템에서 매우 위험합니다.

이제 서버는 이 설정의 일부를 보호합니다. OPENBOT_SINGLE_USER=true이 설정된 상태에서 OPENBOT_PUBLIC_URL, OPENBOT_APP_URL 또는 TRUSTED_ORIGINS 항목이 공개적으로 라우팅되면, 서버는 시작을 거부하고 해당 주소를 명시합니다. 사설 주소인 경우에는 경고와 함께 시작됩니다. 이 검사는 Docker가 게시하는 인터페이스가 아니라 설정 파일의 URL을 읽어 수행되므로, 포트가 인터넷에 열려 있더라도 기본값인 localhost는 통과합니다. 바인딩은 여전히 사용자의 책임입니다.

이를 안전하게 운영하는 방법은 두 가지입니다. OPENBOT_SINGLE_USER=true을 유지하고 모든 포트를 127.0.0.1에 바인딩한 뒤, SSH 터널이나 사설 네트워크 인터페이스를 통해서만 앱에 접근하십시오.

ssh -N -L 3010:127.0.0.1:3010 -L 3001:127.0.0.1:3001 you@your-vps

그러면 브라우저에서 http://localhost:3010를 통해 앱에 접속할 수 있습니다. Chrome과 Firefox는 해당 주소를 보안 컨텍스트로 취급하며 Secure 로그인 쿠키를 유지합니다. 예외적으로 Safari는 localhost를 보안 컨텍스트로 인식하지만, 2026년 11월 10일 기준으로 일반 http://localhost을 통해 설정된 Secure 쿠키 저장을 여전히 거부합니다. 이는 해결되지 않은 WebKit 버그이므로, 터널은 Chrome이나 Firefox에서 열거나 앞에 TLS를 적용하십시오. 라이브 화면 자체는 보안 컨텍스트가 필요하지 않습니다. 배포 문서에 따르면 앱은 일반 http://에서 제한되는 브라우저 API에 의존하지 않기 때문입니다. 다른 방법은 싱글 유저 모드를 끄고 실제 ID 공급자(Identity Provider)를 설정하는 것입니다. Google, Microsoft Entra, Okta, SAML 및 OIDC가 지원됩니다. Google, Entra, Okta는 환경 변수로 설정하며, SAML 및 OIDC 공급자는 배포가 실행된 후 관리자(Admin)의 ID 공급자(Identity providers) 메뉴에서 등록합니다. 모든 공급자는 32자 이상의 BETTER_AUTH_SECRET, OAuth 콜백을 위한 공개 API 기본 URL로 설정된 BETTER_AUTH_URL, 그리고 INITIAL_ADMIN_EMAILS이 필요합니다. TRUSTED_ORIGINS은 필수 목록에는 없지만, API가 허용하는 앱 오리진과 등록된 OIDC 공급자의 검색 문서에 있는 모든 호스트를 포함합니다. OPENBOT_APP_URL는 기본적으로 첫 번째 항목을 사용하므로, 이를 공개 앱 오리진으로 설정하십시오. 공급자 자격 증명은 완전히 입력해야 합니다. 설정이 불완전하면 오픈 액세스로 돌아가는 대신 시작 자체가 중단됩니다. 팀원 각자가 브라우저가 아닌 자신만의 에이전트를 원해서 계정을 추가하는 경우라면, OneCLI는 처음부터 그런 구조로 설계되었습니다. 사용자당 하나의 샌드박스 에이전트를 사용하고 모델 키는 단일 게이트웨이에서 관리합니다.

앱이 공개 도메인으로 접근 가능하다면 앞에 TLS(Transport Layer Security)를 적용하십시오. localhost가 아닌 환경에서 일반 http://으로 제공되는 페이지는 보안 컨텍스트가 아니므로, Secure로 표시된 쿠키가 저장되지 않아 OpenBot의 버그처럼 보이는 로그인 실패 현상이 발생합니다.

하위 레벨 포트 방화벽 설정

OpenBot의 자체 보안 공지에 따르면 하위 레벨 서비스 엔드포인트는 토큰으로 보호되며, 이를 비공개로 유지하고 게이트웨이를 우회하는 용도로 사용해서는 안 됩니다. 토큰은 두 번째 보호 수단입니다. 첫 번째 보호 수단은 포트에 아예 접근할 수 없도록 만드는 것입니다.

에이전트 컴퓨터는 4100번 포트에서 대기하며 COMPUTER_TOKEN을 요구합니다. 봇 엔드포인트는 4200번과 4201번 포트에서, 에이전트 하니스는 4202번 포트에서 대기합니다. 슈퍼바이저는 호스트의 4500번 포트와 컨테이너 내부의 4300번 포트에서 대기하며, compose 파일은 이를 127.0.0.1:4500에 바인딩합니다. PostgreSQL은 5432번 포트에서 대기합니다. 이들 중 어느 것도 공용 인터페이스에 노출되어서는 안 되며, 단일 사용자 배포 환경이라면 애플리케이션과 API 역시 마찬가지입니다.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw enable
sudo ufw status verbose

방화벽만으로 충분하다고 가정하는 사용자들이 빠지기 쉬운 함정이 있습니다. -p 3001:3001을 사용하여 컨테이너 포트를 게시하면 Docker가 DNAT 규칙을 설치합니다. 이로 인해 트래픽은 FORWARD 경로에서 처리되며, ufw의 기본 거부 정책이 적용되는 INPUT 체인을 전혀 거치지 않게 됩니다. ufw status이 여전히 Status: active를 출력하더라도 포트는 외부에서 열려 있는 상태가 됩니다. 게시된 포트를 -p 127.0.0.1:3001:3001와 같이 루프백 주소에 바인딩하거나, compose 파일에서 호스트 주소를 설정하십시오. 확인은 ufw status이 아닌 ss -ltnp으로 수행해야 합니다. 이 함정은 OpenBot에만 국한된 것이 아니므로, 90년대 비디오 가게 스타일로 재구성된 Jellyfin 라이브러리를 서비스하는 것을 포함하여 서버에 게시한 모든 컨테이너에 대해 동일한 점검을 수행하십시오.

OpenBot은 자체 호스팅 지능형 서비스를 통해 오프라인으로 실행할 수 있습니다

배포를 계획하기 전에 다음 사항을 확인하십시오. OpenBot은 지속 가능한 스레드와 대화 메모리를 호스팅 서비스나 자체 인프라에 저장하는 CopilotKit Intelligence 프로젝트에 의존합니다. 고정된 v0.2.0 서버는 시작 시 INTELLIGENCE_API_URL, INTELLIGENCE_GATEWAY_WS_URL 및 INTELLIGENCE_API_KEY을 검증합니다. 이 세 가지를 하나의 세트로 확인하며, 하나라도 누락되면 시작을 거부합니다. COPILOTKIT_LICENSE_TOKEN는 선택 사항이며, 자체 라이선스를 사용하는 자체 호스팅 지능형 서비스에서만 사용합니다. 2026년 11월 10일 기준으로 무료 호스팅 지능형 서비스는 조직당 매월 1,000회의 상호작용을 포함하지만, v0.1.0 이후부터는 유료 지능형 서비스 플랜을 사용하거나 OPENBOT_SELF_HOST_BANNER=false을 설정하지 않으면 OpenBot에 자체 호스팅 배너가 표시됩니다. 지능형 서비스 자체도 자체 호스팅이 가능하므로 퀵스타트 가이드보다 더 많은 작업이 필요하지만 완전히 로컬 환경에 배포할 수 있습니다. 오프라인 프로덕션 배포에는 Annual 플랜이 필요하며, 자체 호스팅 종량제 방식은 과금을 위해 사용량을 보고하도록 연결되어야 합니다. 무료 Developer Edition은 30일마다 갱신되는 라이선스로 로컬 비프로덕션 평가를 지원하며, 설치 및 갱신 시 인터넷 연결이 필요합니다. 로컬 Intelligence CLI는 키를 CPK_INTELLIGENCE_API_KEY로 기록하지만, 고정된 v0.2.0 릴리스는 INTELLIGENCE_API_KEY만 읽으므로 이 릴리스를 위해 값을 복사해야 합니다. 현재 main는 CLI 키를 직접 허용하며 우선순위를 부여합니다.

모델은 두 번째 의존성입니다. 기본적으로 포함된 것은 없습니다. BOT_PROVIDER은 LangGraph Bot을 위해 openai, anthropic 또는 google를 허용하며, OPENAI_BASE_URL은 OpenAI 경로를 호환되는 모든 엔드포인트로 지정합니다. 토큰을 자체 하드웨어에 유지하려는 경우 LLM 자체 호스팅을 위해 VPS에서 Ollama 실행하기가 이 단계에 해당합니다. 브라우저 제어는 모델에 많은 요구를 하므로, 실제 작업에 적용하기 전에 로컬 모델을 먼저 테스트하십시오.

단일 복제본을 넘어선 확장

게이트웨이는 페이지 스냅샷을 기준으로 요소 참조를 확인합니다. 해당 스냅샷은 이제 PostgreSQL에 저장되므로, 두 번째 복제본이 첫 번째 복제본이 생성한 스냅샷을 사용하여 작업을 수행할 수 있습니다. 공식 Helm 차트는 기본적으로 2개의 API 복제본을 실행하며, 복제본이 생존하는 데 필요한 모든 데이터를 PostgreSQL에 보관합니다. 또한 내장 컴퓨터 기능을 비활성화하며, 복제본이 2개 이상인 환경에서는 이를 설치하지 못하도록 제한합니다. API 파드 내부의 브라우저는 특정 봇의 로그인 정보를 보유하게 되는데, API를 확장하면 이 정보가 중복될 수 있습니다. 단일 이미지는 주의 깊게 살펴봐야 합니다. 각 복제본이 자체 브라우저를 가지고 있어 봇의 로그인 정보가 해당 요청을 처리한 인스턴스에만 남기 때문입니다. 단일 VPS 환경에서는 모든 봇의 브라우저가 여전히 동일한 호스트에서 실행되므로, 서버 사양을 높이는 방식으로 확장해야 합니다. 봇 간의 격리는 여전히 봇별 컨테이너를 통해 이루어지며, 이는 자체 호스팅 에이전트 샌드박스가 한 에이전트의 오류가 다른 에이전트에 영향을 미치지 않도록 격리하는 방식과 동일합니다.

실패 유형 및 확인 사항

.env을 입력한 직후 시작이 종료됩니다. 서버는 서비스를 시작하기 전에 설정을 검증합니다. Intelligence 블록의 일부가 누락되었거나, KEY_ENCRYPTION_KEY가 없거나, OAuth 제공자에 클라이언트 ID는 있지만 비밀값이 없거나, 공개 URL과 함께 단일 사용자 모드가 설정된 경우 서비스가 조용히 성능이 저하되는 대신 시작 단계에서 중단됩니다. 첫 번째 오류 메시지를 읽고 해당 필드를 수정한 뒤 다시 시작하십시오.

관리형 데이터베이스에서 마이그레이션이 실패합니다. 두 가지 원인이 있을 가능성이 높습니다. vector 확장이 활성화되지 않았고 마이그레이션을 수행하는 역할이 이를 생성할 수 없는 경우, 마이그레이션 도중 PostgreSQL이 알 수 없는 열 유형을 만나게 됩니다. 또는 다른 역할로 확장이 생성되어 must be owner of extension vector 오류와 함께 마이그레이션이 중단될 수 있습니다. 마이그레이션을 실행하는 역할로 확장을 생성한 다음 마이그레이션 단계를 다시 실행하십시오.

애플리케이션은 로드되지만 로그인이 유지되지 않습니다. 공개 주소에서 일반 http://를 통해 서비스를 제공하고 있으며, 이는 보안 컨텍스트가 아니므로 Secure 쿠키가 폐기됩니다. 앞에 TLS를 배치하거나 SSH 터널을 사용하여 브라우저가 localhost을 인식하도록 하십시오. 터널을 사용하는 경우 Chrome이나 Firefox를 사용하십시오. Safari는 일반 http://localhost를 통해 설정된 Secure 쿠키를 여전히 삭제하기 때문입니다.

봇이 분리되어야 할 로그인을 공유합니다. 슈퍼바이저를 사용하지 않으면 봇별 컴퓨터가 존재하지 않으며 모든 봇이 AGENT_COMPUTER_URL에서 공유 브라우저를 사용하게 됩니다. COMPUTER_SUPERVISOR_URL이 설정되어 있는지, 그리고 슈퍼바이저가 Docker 소켓에 접근할 수 있는지 확인하십시오.

봇이 멈추고 도움을 요청합니다. 이는 설계된 대로 작동하는 것입니다. 감사 추적에 computer.help_requested가 기록되며, 사용자가 라이브 화면에서 제어권을 가져오면 양쪽 모두에 인계 사실이 기록됩니다.

FAQ

VPS 배포 시 OPENBOT_SINGLE_USER를 켜두어도 안전합니까?

인터넷에서 게이트웨이에 접근할 수 없는 경우에만 안전합니다. OPENBOT_SINGLE_USER=true은 모든 요청을 로그인 절차 없이 고정된 관리자로 간주하므로, 포트에 접근할 수 있는 사람은 누구나 해당 배포 환경과 저장된 자격 증명, 로그인된 브라우저를 완전히 제어할 수 있습니다. 이 모드에서는 설정된 공개 URL이나 신뢰할 수 있는 오리진이 공개적으로 라우팅될 때 서버가 시작을 거부하지만, 이 검사는 포트가 어떻게 공개되었는지는 파악하지 못합니다. 모든 포트를 127.0.0.1에 바인딩하고 SSH 터널이나 사설 네트워크 인터페이스를 통해서만 앱에 접근하는 경우에는 허용됩니다. 공용 인터페이스에서는 이 설정을 끄고 Google, Microsoft Entra, Okta 또는 OIDC를 BETTER_AUTH_SECRET, BETTER_AUTH_URL, INITIAL_ADMIN_EMAILS과 함께 구성하십시오. 또한 TRUSTED_ORIGINS을 공개 앱 오리진으로 설정하십시오.

OpenBot 봇 하나당 RAM이 얼마나 필요합니까?

arm64 환경에서 단일 봇에 대해 공개된 프로젝트 수치에 따르면 최대 메모리 사용량은 0.55 GB이며, 문서화된 최소 사양은 2 GB, 권장 사양은 4 GB입니다. 각 봇은 독립적인 Chromium을 유지하므로 여러 봇을 동시에 실행할 때의 수치는 공개되어 있지 않습니다. 실제 작업에서 봇 하나를 실행한 뒤 docker stats에서 해당 컨테이너의 메모리 사용량을 확인하고, 게이트웨이와 데이터베이스 사용량을 더한 다음 동시에 실행할 봇의 수만큼 곱하십시오.

OpenBot을 자체 호스팅하려면 CopilotKit 계정이 필요합니까?

네. OpenBot은 지속적인 스레드와 메모리를 위해 CopilotKit Intelligence 프로젝트에 의존하며, 고정된 v0.2.0 서버는 Intelligence API URL, 게이트웨이 WebSocket URL, API 키가 모두 설정되지 않으면 시작을 거부합니다. 2026년 11월 10일 기준으로 무료 호스팅 플랜을 이용할 수 있으며, 연간 구독을 통한 자체 호스팅 Intelligence와 로컬 모델을 사용하여 오프라인 프로덕션 배포를 지원합니다. OpenBot에는 기본 제공되는 모델이 없으므로 직접 모델 접근 권한, 모델 API 키 또는 지원되는 제공업체 로그인 정보를 준비해야 합니다.

왜 봇들이 브라우저를 공유하지 않고 각각 하나씩 사용합니까?

브라우저 프로필이 곧 신원(identity)이기 때문입니다. 브라우저를 공유하면 쿠키와 세션도 공유되므로, 한 봇이 특정 계정에 로그인하면 모든 봇이 해당 계정에 로그인된 상태가 됩니다. 봇별 컨테이너를 사용하면 각 작업자에게 고유한 프로필과 로그인 정보를 부여할 수 있지만, 이는 COMPUTER_SUPERVISOR_URL이 서버를 관리자(supervisor)로 지정했을 때만 가능합니다. 그렇지 않으면 모든 봇이 하나의 브라우저를 공유하게 됩니다. 이로 인한 비용은 메모리 사용량이며, 봇당 Chromium 하나를 실행하는 것이 전체 크기 산정에서 가장 큰 비중을 차지합니다.

방화벽에서 어떤 OpenBot 포트를 열어야 합니까?

하위 레벨 포트는 모두 열지 마십시오. 4100번의 에이전트 컴퓨터, 4200번과 4201번의 봇 엔드포인트, 4202번의 에이전트 하네스, 4500번의 관리자(supervisor), 5432번의 PostgreSQL은 모두 비공개로 유지해야 합니다. 프로젝트는 토큰으로 이들을 보호하며, 애초에 외부에서 접근할 수 없도록 유지할 것을 권장합니다. 사람이 접근해야 하는 포트만 공개하십시오. -p 3001:3001로 공개된 컨테이너 포트는 ufw의 기본 거부 규칙과 관계없이 접근 가능하다는 점을 기억하십시오. Docker의 DNAT 규칙이 해당 트래픽을 INPUT가 아닌 FORWARD 경로로 처리하기 때문입니다.

이 글이 도움이 되었나요?