한 줄 요약
opencode serve(또는 opencode web)로 작업 머신에 OpenCode 백엔드(세션/도구/프로젝트)를 켜 두고, 다른 기기에서 접속해 같은 일을 그대로 이어가는 방식입니다. 원격 조종 리모컨처럼 쓰시면 됩니다.
먼저: opencode web(모바일 브라우저로 바로 이어서 작업)
opencode web은 API 서버에 더해 웹 UI까지 함께 띄워주는 모드입니다.1 그래서 별도 툴(SSH/TUI/앱) 없이도 모바일 브라우저만 있으면 접속해서 작업을 이어가실 수 있습니다.
무거운 연산과 레포 접근은 서버 머신이 처리하고, 폰/태블릿은 화면과 입력만 담당하는 컨트롤러가 됩니다. 키 조합 제약, 화면 가독성, 복붙 스트레스가 크게 줄어드는 게 체감 포인트입니다.
서버 머신에서 웹 UI를 띄우려면 아래처럼 실행하시면 됩니다.
opencode web --hostname 0.0.0.0 --port 4096외부에서 접속하실 때는 보안 설정이 거의 필수라서, 아래의 보안 섹션(Tailscale + Password)까지 함께 보시는 걸 권장드립니다.
web과 serve의 역할은 아래처럼 정리하시면 헷갈리지 않습니다.
web: API + 웹 UI(브라우저로 바로 사용)serve: API 중심(headless) 서버, 클라이언트가 API로 접속둘 다 같은 백엔드(세션/프로젝트/도구)를 공유하므로, 상황에 맞게 클라이언트를 바꿔 붙이실 수 있습니다.
serve가 뭐예요?
opencode serve는 화면(TUI) 없이 돌아가는 headless HTTP 서버입니다.1 OpenCode 기능을 OpenAPI 엔드포인트로 노출해서, 터미널 TUI(클라이언트)나 다른 클라이언트가 서버에 접속해 세션을 만들고, 메시지를 보내고, 파일/명령을 실행할 수 있게 해줍니다.2
서버가 제공하는 API는 /doc에서 확인하실 수 있습니다(예: http://localhost:4096/doc). 서버 상태는 GET /global/health로 확인하시면 됩니다(예: http://localhost:4096/global/health).
핵심은 구조입니다. TUI가 곧 서버라기보다, 서버가 있고 TUI/웹은 붙는 클라이언트에 가깝습니다. 그래서 서버를 한 번 띄워 두면 여러 클라이언트가 동시에 붙을 수도 있고, 자동화/외부 연동도 쉬워집니다.
아래 이미지는 서버/클라이언트 구조를 한 장으로 정리해 둔 것입니다.
(캡션: OpenCode 백엔드 서버(serve/web)에 여러 클라이언트(TUI, 브라우저 등)가 접속해 같은 작업 컨텍스트를 공유하는 흐름을 보여드립니다.)
빠른 시작(로컬)
가장 기본 실행은 아래와 같습니다.
opencode serve기본값은 127.0.0.1:4096에서 대기합니다. 호스트/포트를 명시하고 싶으시면 아래처럼 지정하시면 됩니다.
opencode serve --hostname 127.0.0.1 --port 4096상태 확인은 아래처럼 하시면 됩니다.
curl http://127.0.0.1:4096/global/health스펙 문서는 아래처럼 보시면 됩니다.
# 브라우저로 열어도 됩니다
open http://127.0.0.1:4096/doc(환경에 따라 open 대신 주소를 브라우저에 직접 붙여 넣으셔도 됩니다.)
이미 떠 있는 서버에 TUI로 붙으시려면 opencode attach를 사용하시면 됩니다.
opencode attach http://127.0.0.1:4096원격에서 이어서 하기(attach/web)
이 방식의 진짜 장점은 “원격에서 이어서 하기”입니다. 집/회사 개발 머신에서 serve나 web을 켜 두시면, 밖에서는 노트북/휴대폰/태블릿이 그 서버로 접속해서 같은 세션과 작업을 그대로 이어가실 수 있습니다. 느낌은 원격 조종(remote control)에 가깝습니다. 무거운 연산과 레포 접근은 서버 머신이 맡고, 손에 든 기기는 컨트롤러가 됩니다.
흐름을 단순화하면 아래처럼 보시면 됩니다.
[원격 기기(브라우저/TUI)] -> (네트워크) -> [opencode web/serve 실행 중인 머신] -> [레포/쉘/LLM]여기서 serve와 web의 차이는 이렇게 잡아두시면 좋습니다.
opencode serve는 API 중심(headless)입니다. 기본 전제는 “클라이언트(TUI/IDE 플러그인/자동화)가 API로 서버에 요청한다”는 구조입니다.
opencode web은 API에 더해 웹 UI까지 같이 제공합니다. 그래서 SSH로 터미널에 들어가 TUI를 쓰는 것보다 쉬운 경우가 많고, 특히 모바일에서는 브라우저가 훨씬 편합니다(키 조합, 화면 가독성, 복붙 측면에서 유리합니다).
웹 UI로 사용하시려면 서버 머신에서 아래처럼 실행하시면 됩니다.
opencode web --hostname 0.0.0.0 --port 4096그리고 같은 서버에 터미널 TUI도 함께 붙이실 수 있습니다.
opencode attach http://<server-ip>:4096여기까지는 “연결만 되면 끝”에 가깝고, 실제 운영에서는 다음 섹션의 보안 설정이 거의 필수에 가깝습니다.
보안(Tailscale + Password)
원격 접속을 “인터넷에 포트 열기”로 해결하실 수도 있지만, 그 순간부터는 방어를 제대로 해두시는 게 좋습니다. 제가 권장드리는 기본 조합은 두 겹입니다.
첫째, OpenCode 자체에 비밀번호를 설정해 주세요. OPENCODE_SERVER_PASSWORD를 설정하면 HTTP Basic Auth가 켜집니다. 기본 사용자명은 opencode이며, 바꾸고 싶으시면 OPENCODE_SERVER_USERNAME를 사용하시면 됩니다. 이 설정은 opencode serve와 opencode web 모두에 적용됩니다.
export OPENCODE_SERVER_USERNAME=opencode
export OPENCODE_SERVER_PASSWORD='<your-password>'둘째, 네트워크는 Tailscale로 감싸시는 걸 권장드립니다. 요지는 “포트를 인터넷에 직접 공개하지 말고, tailnet 내부에서만 접속”하는 것입니다. Tailscale은 WireGuard 기반으로 기기 간 통신을 암호화하고, tailnet 정책으로 접근을 통제할 수 있어서 원격 개발용으로 궁합이 좋습니다.
아래 이미지는 Tailscale/WireGuard 터널 개념을 떠올리기 좋은 참고용이다.
이미지 출처: How Tailscale Makes Managing Wireguard Easy - YouTube
제가 가장 선호하는 패턴은 아래입니다.
“OpenCode 서버는 localhost(127.0.0.1)에만 바인딩하고, 외부에서 들어오는 길은 Tailscale serve가 HTTPS로 프록시한다.”
이렇게 하시면 OpenCode가 LAN/WAN에 직접 노출되지 않습니다. 오픈 포트 스캐닝 같은 노이즈를 한 겹 피하고 시작하시는 셈입니다.
OpenCode를 로컬에만 묶어두시고:
opencode web --hostname 127.0.0.1 --port 4096그리고 Tailscale 쪽에서 HTTPS로 내보내시면 됩니다(개념 예시입니다).
sudo tailscale serve --bg --yes --https 443 http://127.0.0.1:4096이 패턴을 쓰시면 “내 서버는 항상 localhost만 듣는다”는 단순한 보안 기준을 유지하기가 훨씬 쉬워집니다.
WSL에서 막힐 때 체크리스트
WSL2 기본 네트워킹은 NAT라서, 다른 기기(폰/태블릿)에서 WSL 안의
opencode web/serve로 바로 접근이 번거로울 수 있습니다.Windows 11 22H2+라면
.wslconfig에 mirrored 모드를 켜는 것이 도움이 될 때가 있습니다.3
[wsl2]
networkingMode=mirroredmirrored 모드에서도 방화벽/Hyper-V 쪽에서 막힐 수 있습니다. 안내된 참고 명령(관리자 PowerShell)은 아래처럼 생겼습니다.
Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow지금 OpenCode가 어디에 바인딩되어 있는지부터 확인해 주세요. WSL/LAN 접속을 기대하시면서
127.0.0.1만 듣고 있으면 밖에서 들어올 수 없습니다(다만 보안 관점에서는 “localhost + Tailscale 프록시”가 더 권장되는 편입니다).WSL2 NAT 환경에서 “WSL의 서버를 LAN에 열어야 하는 상황”이면, WSL 문서에 나온 것처럼 Windows 쪽
netsh interface portproxy로 포트 포워딩을 잡아야 할 때가 있습니다.3 설정이 복잡해지기 쉬우니, 가능하면 Tailscale로 우회하시는 편이 보통 덜 고생하십니다.
serve를 쓰는 장점(체크리스트)
세션이 서버에 남습니다: 클라이언트를 껐다 켜도 작업 맥락을 이어가기 쉽습니다.
여러 클라이언트 동시 접속이 가능합니다: 터미널(TUI)로 붙어 있다가, 브라우저로도 같은 백엔드를 보면서 작업하실 수 있습니다.
serve는 API 중심이라 자동화/연동에 유리합니다:/doc스펙을 보고 필요한 요청을 만들어 붙이기 좋습니다.원격 작업이 SSH보다 단순해질 때가 많습니다: 특히
opencode web은 브라우저만 되어서 모바일에서 체감이 큽니다.보안을 구성하기 쉬운 편입니다: Basic Auth + “localhost 바인딩 + Tailscale로만 접근” 조합이 깔끔합니다.
참고
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.