{"id":29906074,"url":"https://github.com/squatboy/browser-use-vnc","last_synced_at":"2025-10-13T06:42:11.039Z","repository":{"id":307692720,"uuid":"1030379567","full_name":"squatboy/browser-use-vnc","owner":"squatboy","description":"Real-time monitoring and user-control of Browser-use headed browser through VNC. (+Working on Multi-Session Support)","archived":false,"fork":false,"pushed_at":"2025-08-30T12:08:07.000Z","size":48,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-30T14:18:38.154Z","etag":null,"topics":["browser-use","docker","novnc","playwright","vnc","x11vnc","xvfb"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/squatboy.png","metadata":{"files":{"readme":"README.ko.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-01T14:36:59.000Z","updated_at":"2025-08-30T12:08:11.000Z","dependencies_parsed_at":"2025-08-30T14:14:32.128Z","dependency_job_id":"bd164a3a-5a37-4d98-84ef-3e2a5de82d57","html_url":"https://github.com/squatboy/browser-use-vnc","commit_stats":null,"previous_names":["squatboy/browser-use-vnc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/squatboy/browser-use-vnc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squatboy%2Fbrowser-use-vnc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squatboy%2Fbrowser-use-vnc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squatboy%2Fbrowser-use-vnc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squatboy%2Fbrowser-use-vnc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/squatboy","download_url":"https://codeload.github.com/squatboy/browser-use-vnc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squatboy%2Fbrowser-use-vnc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013971,"owners_count":26085429,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser-use","docker","novnc","playwright","vnc","x11vnc","xvfb"],"created_at":"2025-08-01T20:14:05.984Z","updated_at":"2025-10-13T06:42:11.034Z","avatar_url":"https://github.com/squatboy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Browser-Use noVNC Web View\n\nVNC/noVNC를 사용하여 실시간 웹 주소 접근 기반 가상 모니터를 제공하는 Docker 기반 시스템으로, **vnc**와 **agent** 두 개의 컨테이너로 구성되어 있습니다. `vnc` 컨테이너는 가상 디스플레이 서버와 VNC 서비스를 실행하고, `agent` 컨테이너는 `agent.py`와 같은 브라우저 자동화 스크립트를 실행합니다. 두 컨테이너는 공유된 X11 UNIX 소켓 볼륨을 통해 통신하며, 세션을 격리하고 보안을 보장합니다.\n\n\u003cbr\u003e\n\n## 시스템 아키텍처\n\n\u003cimg width=\"996\" height=\"933\" alt=\"473523324-d86b43ec-4204-4a94-ae86-01c63c39dfe1\" src=\"https://github.com/user-attachments/assets/4431006a-1656-49ce-b97c-07b719b23743\" /\u003e\n\n### 멀티 세션 플로우\n\u003cimg width=\"1138\" height=\"570\" alt=\"image\" src=\"https://github.com/user-attachments/assets/8379e126-1940-4096-8857-3cdb141f4ad6\" /\u003e\n\n\u003cbr\u003e\n\n각 사용자가 browser-use task 실행을 요청하면 오케스트레이터가 새로운 세션 생성을 트리거합니다. 이때 개별 세션마다 VNC/agent 컨테이너 쌍이 독립적으로 기동되고, 해당 세션에 대해 noVNC를 통한 실시간 가상 모니터 화면이 제공됩니다. 각 세션은 Docker 네임스페이스와 전용 X11 소켓 볼륨을 기반으로 완전히 격리되어 실행되며, 이를 통해 세션 간 디스플레이 데이터가 안전하게 분리됩니다.\n\n## 데모 영상\n\n![vncsingle](https://github.com/user-attachments/assets/6468d96a-6f57-411f-9012-c39017110ff6)\n\n\n#### 멀티 세션\n\n![multisession](https://github.com/user-attachments/assets/f7d62f1d-575e-475a-8462-a9167ee1a9d6)\n\n\n\n## Containers\n### vnc\n\n- **Xvfb**: 가상 디스플레이 서버 (예: :99)\n- **x11vnc**: VNC 서버\n- **websockify**: VNC를 WebSocket으로 변환하여 noVNC 접근 제공\n\n### agent\n- Browser-use Python 스크립트 실행 (예: `agent.py`)\n- `vnc` 컨테이너와 X11 소켓 볼륨을 공유하여 가상 디스플레이에 출력 렌더링\n\n\u003cbr\u003e\n\n## 시작하기\n\n### 요구사항\n\n- Docker \u0026 Docker Compose\n- git\n- Python 3.8 이상\n\n### 1. 저장소 클론\n\n```bash\ngit clone https://github.com/squatboy/browser-use-vnc.git\ncd browser-use-vnc/\n```\n\n### 2. `.env` 파일 및 agent 스크립트 준비\n- `agent/.env`: Browser-Use에 사용될 LLM API KEY 작성\n- `agent/agent.py`: Browser-Use 에이전트 스크립트 파일\n- `orchestrator/.env`: `PUBLIC_HOST=\u003c서버의 공인 IP 또는 도메인\u003e` 지정 (반드시 설정 필요, orchestrator가 noVNC 접속 URL 생성 시 사용)\n\n\u003e 이 파일들은 Docker Compose에 의해 자동으로 로드되어 agent 및 orchestrator 컨테이너를 구성하고 실행합니다.\n\n### 3. FastAPI Orchestrator 실행\n\n1. **orchestrator 폴더에서 가상환경 생성 및 활성화**\n\n```bash\ncd orchestrator\npython3 -m venv .venv\nsource .venv/bin/activate\n```\n\n2. **pip 업그레이드 및 requirements.txt 설치**\n\n```bash\npip install -U pip\npip install -r requirements.txt\n```\n\n3. **uvicorn으로 서버 실행**\n\n```bash\nuvicorn app_orchestrator:app --host 0.0.0.0 --port 8000\n```\n\n### 4. 새 세션 생성\n\nPOST 요청을 보내 새로운 VNC/agent 세션을 생성합니다:\n\n```bash\ncurl -X POST http://\u003cServer-IP\u003e:8000/sessions\n```\n\n응답에는 세션 ID와 동적으로 할당된 noVNC URL이 포함됩니다.\n\n예시 응답:\n\n```json\n{\n  \"session_id\": \"1a2b3c4d\",\n  \"novnc_url\": \"http://\u003cServer-IP\u003e:6081/vnc.html?autoconnect=true\u0026resize=scale\"\n}\n```\n\n### 5. 세션 접속\n\n제공된 URL을 웹 브라우저에서 열어 noVNC를 통해 가상 모니터에 접속합니다.\n\n\u003cbr\u003e\n\n## 멀티 세션 수동 테스트 예시\n\n오케스트레이션을 통해 사용하지 않고 직접 다른 `SESSION_ID`와 `NOVNC_PORT` 환경 변수를 지정하고 별도의 Docker Compose 프로젝트를 실행하여 여러 독립 세션을 수동으로 생성할 수 있습니다.\n\n```bash\n# 첫 번째 세션\ncd vnc/\nSESSION_ID=session1 NOVNC_PORT=6081 docker compose -p vnc1 up -d --build\n\n# 두 번째 세션\nSESSION_ID=session2 NOVNC_PORT=6082 docker compose -p vnc2 up -d --build\n```\n\n\u003cimg width=\"928\" height=\"106\" alt=\"image\" src=\"https://github.com/user-attachments/assets/4b0ece57-77e8-4a11-90b6-ff77d1f8e726\" /\u003e\n\n\n그런 다음 세션에 각각 접속합니다:\n\n- http://:6081/vnc.html\n- http://:6082/vnc.html\n\n\u003cimg width=\"743\" height=\"97\" alt=\"image\" src=\"https://github.com/user-attachments/assets/643ce7ba-3434-491a-a302-398da8aa6aa4\" /\u003e\n\u003cimg width=\"743\" height=\"97\" alt=\"image\" src=\"https://github.com/user-attachments/assets/e6fed99b-eb47-421e-a146-01e5d5ece702\" /\u003e\n\n\n각 세션은 고유한 X11 소켓 볼륨을 사용하므로 세션 간 데이터 누출 없이 격리됩니다.\n\n\n## 보안 그룹 \u0026 네트워크 설정\n\n공용 서버에 배포할 경우, 세션에 필요한 noVNC 포트만 열어두세요 (예: 6080, 6081, 6082, ...). 필요에 따라 접근을 제한하는 것이 중요합니다.\n\n\n## BrowserSession Python 설정 예시\n\nAgent 컨테이너 내에서 브라우저를 실행할 때, 다음 설정을 사용하여 Docker 관련 일반적인 문제를 피하세요:\n\n```python\nbrowser_session = BrowserSession(\n    headless=False,\n    args=[\n        \"--no-sandbox\",            # Docker에서 root로 실행할 때 필요\n        \"--disable-dev-shm-usage\"  # 제한된 컨테이너 환경에서 /dev/shm 크래시 방지\n    ],\n)\n```\n\n\n## 커스터마이징 \u0026 고급 사용법\n\n- 시스템은 `vnc` 컨테이너(가상 디스플레이 및 VNC 서비스)와 `agent` 컨테이너(브라우저 자동화 스크립트)를 분리합니다.\n- 자동화 워크플로우에 맞게 agent 스크립트(`agent.py`)를 확장하거나 수정할 수 있습니다.\n- agent 컨테이너는 `vnc` 컨테이너가 관리하는 가상 디스플레이에 브라우저 출력을 렌더링하기 위해 공유된 X11 소켓 볼륨에 연결됩니다.\n\n\n## 사용 사례: 웹사이트 내 VNC 데스크탑 임베딩\n\nnoVNC 웹 클라이언트를 iframe에 삽입하여 원격 데스크탑을 웹 애플리케이션에 직접 통합할 수 있습니다:\n\n```html\n\u003ciframe\n    src=\"http://\u003cServer-IP\u003e:6080/vnc.html?autoconnect=true\"\n    width=\"1280\" height=\"720\"\u003e\n\u003c/iframe\u003e\n```\n\n\n## 문제 해결 \u0026 팁\n\n- **Chrome 실행 실패**: `docker compose restart`로 컨테이너를 재시작하세요.\n- **VNC 연결 실패**: 방화벽이나 보안 그룹에서 noVNC 포트의 인바운드 트래픽 허용 여부를 확인하세요.\n\n\n## 추가 참고 사항\n\n- 각 세션은 Docker 네임스페이스와 고유한 X11 소켓 볼륨을 통해 격리됩니다.\n- `agent`와 `vnc` 컨테이너 간의 통신은 네트워크가 아닌 X11 UNIX 소켓을 통해서만 이루어집니다.\n- 사용 사례에 맞게 agent 측 스크립트와 종속성을 자유롭게 추가하거나 수정할 수 있습니다.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquatboy%2Fbrowser-use-vnc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquatboy%2Fbrowser-use-vnc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquatboy%2Fbrowser-use-vnc/lists"}