공개 노트

opencode serve/web로 원격 개발 이어하기: 폰이 내 개발PC 리모컨 되는 법

2026-03-06Views 558약 3분생성형 AI 활용

Summary

"집 PC에서 하던 OpenCode 작업을 밖에서 그대로 이어서 하고 싶은데, SSH는 번거롭고 모바일로는 더 답답하다"는 상황이 자주 생깁니다. 이때 해답은 간단합니다. 작업 머신에 opencode serve(또는 opencode web)로 백엔드를 켜 두고, 다른 기기에서 같은 세션·프로젝트·도구 상태에 접속해 그대로 이어가는 방식입니다. 핵심은 "TUI가 본체"가 아니라, 서버(백엔드)가 본체라는 관점이에요.

OpenCode 서버-클라이언트 구조

opencode web: 모바일 브라우저로 바로 이어서 작업하기

급할 때는 opencode web이 제일 편합니다. API 서버에 웹 UI까지 함께 올려주기 때문에, 별도 앱이나 SSH 없이도 폰 브라우저만 열면 "방금 하던 그 화면"으로 들어갈 수 있어요.¹

아이디어는 이렇습니다. 무거운 일(레포 접근, 도구 실행, 모델 호출)은 서버 머신이 처리하고, 내 손에 든 기기는 입력과 화면만 담당합니다. 그래서 모바일에서 흔히 겪는 키보드 단축키 지옥, 복붙 스트레스, 작은 화면 가독성 문제가 크게 줄어듭니다.

서버 머신에서 아래처럼 실행합니다.

opencode web --hostname 0.0.0.0 --port 4096

원격 작업 흐름 예시

(개념 이미지: 원격 기기 → 네트워크 → 작업 머신으로 접속해 컨트롤하는 흐름)

opencode serve란? "화면 없는 백엔드"를 띄우는 이유

opencode serve는 UI 없이 돌아가는 headless HTTP 서버입니다. OpenCode 기능을 HTTP API로 열어두고, TUI든 웹이든 다른 클라이언트가 붙어서 세션 생성, 메시지 전송, 파일/명령 실행을 요청하는 구조죠.¹

이 구조가 좋은 이유는 "작업의 기억(세션/컨텍스트)이 서버에 남는다"는 점입니다. 노트북을 닫았다가 다시 열어도, 폰으로 들어갔다가 다시 데스크톱으로 돌아와도, 같은 백엔드에 붙기만 하면 흐름이 이어집니다.

로컬에서 빠르게 켜는 방법은 아래처럼 단순합니다.

opencode serve

서버가 살아있는지 확인하려면 헬스 체크를 한 번 던져보면 됩니다.

curl http://127.0.0.1:4096/global/health

API 문서는 브라우저에서 /doc로 확인할 수 있어요.

open http://127.0.0.1:4096/doc

이미 떠 있는 서버에 TUI로 재접속할 땐 attach를 씁니다.

opencode attach http://127.0.0.1:4096

API 문서(OpenAPI) 참고 이미지

(개념 이미지: 서버가 OpenAPI 문서로 명세를 제공하면, 클라이언트/자동화가 붙기 쉬워집니다)

보안: 포트 오픈보다 "Tailscale + 비번"이 마음 편합니다

원격 접속을 위해 포트를 인터넷에 바로 열 수도 있지만, 그 순간부터는 피곤해집니다. 제가 권장하는 최소 조합은 두 겹입니다.

첫째는 OpenCode 자체 비밀번호입니다. OPENCODE_SERVER_PASSWORD를 설정하면 HTTP Basic Auth가 켜지고, 기본 사용자명은 opencode입니다.²

export OPENCODE_SERVER_USERNAME=opencode
export OPENCODE_SERVER_PASSWORD='<your-password>'

둘째는 네트워크를 Tailscale로 감싸는 방식입니다. 핵심은 "OpenCode는 localhost만 듣게 하고, 외부 접근은 tailnet 내부에서만"으로 만드는 겁니다. 이러면 내 OpenCode가 공용 인터넷에 직접 노출되지 않아서 훨씬 단순해져요.

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

Tailscale/WireGuard 개념 참고

시사점

원격 개발을 "SSH로 터미널 접속"이라고만 생각하면, 모바일에서는 고역이 됩니다. 하지만 OpenCode는 백엔드를 서버로 분리해 두는 구조라서, opencode web만 잘 띄워두면 폰도 태블릿도 자연스럽게 "리모컨"이 됩니다.

처음 세팅은 이렇게만 기억해도 충분합니다. "웹으로 간편 접속은 opencode web", "자동화·확장·여러 클라이언트는 opencode serve", 그리고 보안은 "비번 + Tailscale로 localhost 유지". 이 조합이면 밖에서도 집 PC의 OpenCode 세션을 거의 끊김 없이 이어갈 수 있습니다.

참고

¹OpenCode 서버 문서

²Documentation: Web Interface Client Interaction Architecture · Issue #11616 · anomalyco/opencode · GitHub