OpenCode Web 브라우저: UI 실행, 포트 설정과 안전한 접속

OpenCode Web은 OpenCode 서버의 브라우저 인터페이스입니다. 세션을 확인하거나 프로젝트를 브라우저 탭으로 열고, TUI와 다른 화면을 유지할 때 유용합니다. 호스팅 계정이 아니므로 Provider 인증 정보를 대신 관리하지는 않습니다.

첫 명령은 hostname을 바꾸지 않은 opencode web이어야 합니다. 공식 Web 문서는 127.0.0.1에 바인딩하고 사용 가능한 포트를 선택한 뒤 기본 브라우저를 연다고 설명합니다. 이 로컬 경계에서 프로젝트, Provider, 권한과 세션을 확인하세요.

그 다음에 고정 포트, 네트워크 hostname, mDNS, CORS를 선택합니다. 각 설정은 연결 가능한 대상을 바꿉니다. 브라우저가 열리지 않으면 프로세스나 포트, 원치 않는 사람이 접속하면 공개 범위를 먼저 의심합니다.

opencode web

사용할 저장소에서 명령을 실행하세요. OpenCode가 Web 서버를 시작하고 브라우저를 엽니다. 프로세스를 소유한 터미널을 잠시 유지하며 주소, 포트와 경고를 기록하세요. 페이지가 열렸다고 올바른 파일이나 모델을 본다는 뜻은 아닙니다.

반복 가능한 주소가 필요하면 opencode web --port 4096을 사용하세요. 고정 포트는 북마크, 스크립트, opencode attach에 편리하지만 충돌할 수 있습니다. 모든 포트를 공개하지 말고 먼저 어떤 프로세스가 사용 중인지 확인하세요.

첫 Web 작업은 읽기 전용으로 합니다. 프로젝트를 나열하고 작은 파일을 요약한 뒤 세션 또는 서버 상태를 확인하세요. 같은 workspace에서 Git status와 모델을 확인하면 브라우저, 프로세스, 저장소와 Provider를 분리해 볼 수 있습니다.

포트는 호스트의 번호이고 hostname은 어느 인터페이스가 연결을 받을지 결정합니다. 127.0.0.1은 로컬 전용입니다. --port 4096은 번호를 바꾸고 --hostname 0.0.0.0은 네트워크 인터페이스까지 노출 범위를 바꿉니다.

신뢰할 수 있는 LAN에서는 mDNS가 편리합니다. 공식 예시는 opencode web --mdns로 opencode.local을 알리고 --mdns-domain으로 여러 인스턴스를 구분합니다. 검색 기능은 암호화나 인증이 아닙니다.

CORS는 어떤 브라우저 Origin이 교차 출처 요청을 보낼 수 있는지 정합니다. 사용자 프론트엔드에 필요할 수 있지만 노출된 서버를 비공개로 만들지는 않습니다. 허용 목록을 좁히고 실제 Origin을 테스트하세요.

공식 경고는 분명합니다. OPENCODE_SERVER_PASSWORD를 설정하지 않으면 서버가 보호되지 않습니다. 로컬 실험에는 괜찮을 수 있지만 다른 기기에서 접근할 수 있는 서버에는 부족합니다. 시작 프로세스에 주입하고 opencode.json, 기록, 캡처, 커밋된 .env에 저장하지 마세요.

기본 사용자 이름은 opencode이며 OPENCODE_SERVER_USERNAME으로 바꿀 수 있습니다. 이 인증은 Web 서버만 보호하고 Provider나 저장소를 보호하지 않습니다. 키, 권한, 마운트와 프로세스 사용자를 따로 검토하세요.

--hostname 0.0.0.0 전에 방화벽과 네트워크 구간을 확인하세요. 사설 네트워크, 짧은 수명의 비밀번호와 알려진 포트를 우선합니다. Proxy, VPN 또는 프론트엔드가 있다면 TLS 종료 지점과 세션을 보는 계층을 기록하세요.

Web 시작 화면에서는 활성 세션을 보고 새 세션을 만들 수 있습니다. 프롬프트를 보내기 전에 프로젝트를 확인하세요. 프로세스나 저장소가 바뀌어도 브라우저 탭은 남을 수 있으므로 서버 상태를 다시 확인합니다.

서버 상태는 Web 프로세스와 코딩 세션을 구분하는 데 도움이 됩니다. 모델이 없으면 Provider와 모델 ID를, 파일이 없으면 작업 디렉터리와 사용자를 먼저 확인하세요.

두 인터페이스를 같이 쓰려면 Web 서버를 시작한 뒤 다른 터미널에서 opencode attach http://localhost:4096을 실행하세요. 공식 문서는 세션과 상태를 공유한다고 설명합니다. 쓰기 작업자는 하나로 유지하고 작은 diff를 검토하세요.

공식 Web 페이지는 Windows에서 파일 시스템과 터미널 통합을 위해 WSL에서 opencode web을 실행하는 방법을 권장합니다. 저장소가 Linux 경로에 있거나 도구가 WSL에 설치됐거나 PowerShell의 PATH와 home이 다를 때 중요합니다.

명령이 어디에서 실행되는지, 저장소가 어디에 있는지, 어떤 사용자가 프로세스를 소유하는지 기록하세요. Windows 브라우저가 WSL에 연결할 수 있어도 localhost, 방화벽과 경로는 터미널에서 보이지 않는 경계를 넘을 수 있습니다. 편집 전 읽기 전용으로 테스트하세요.

페이지는 열리지만 명령이나 파일 참조가 실패하면 opencode --version, 현재 디렉터리, Provider 환경 변수와 Web을 시작한 shell을 비교하세요. 배포, VS Code와 권한 가이드는 인접 계층을 다루며 이 페이지는 브라우저 서버에 집중합니다.

프로세스와 URL부터 확인하고 안쪽으로 이동하세요. 연결 오류는 프로세스, 포트, hostname, 방화벽 또는 CORS일 가능성이 큽니다. 페이지는 열리지만 세션이 시작되지 않으면 프로젝트, Provider, 권한 또는 모델을 확인합니다. 모든 것을 동시에 바꾸면 증거가 사라집니다.

고정 포트라면 어떤 프로세스가 듣고 있는지와 출력된 URL의 포트가 같은지 확인하세요. 네트워크 hostname은 localhost와 비밀번호가 동작한 뒤 두 번째 기기에서 테스트합니다. mDNS는 알린 이름과 실제 주소를 비교합니다.

세션이 예상과 다르면 시작 명령, 작업 디렉터리, 모델 ID, 변수 출처와 Git status를 기록하세요. 짧은 읽기 요청과 작은 문서 변경을 재현하고, 비밀·무관 파일·worktree 밖 경로가 diff에 나타나면 중지합니다.

브라우저로 프로젝트와 대화를 검토하기 쉽거나 실행 중 서버를 다른 화면에서 보고 싶거나 팀이 반복 가능한 로컬 URL을 원할 때 Web을 사용하세요. 키보드 작업, shell 중심 작업, 브라우저가 없는 환경에는 TUI가 더 적합합니다.

Web은 Provider, 권한, Docker 가이드를 대체하지 않습니다. 서버에 접근하는 방식만 바꿉니다. 인증 정보, 권한, 마운트, MCP 도구와 Git 검토는 각각 확인해야 합니다. 다음 결정에 맞는 좁은 가이드로 연결하세요.

안정적인 순서는 로컬 시작, 프로젝트와 모델 확인, hostname을 넓히기 전 비밀번호 설정, 포트 기록, 필요할 때 TUI 연결, 종료 시 서버 중지입니다. 개발용 listener를 공용 서비스로 취급하지 마세요.