OpenCode Web 개요
OpenCode 는 터미널 기반으로 사용할 수도 있지만, web 기능을 통해 브라우저에서 바로 사용할 수도 있다. 기본적으로 opencode web 을 실행하면 로컬 서버가 올라오고, 브라우저에서 OpenCode 세션을 확인하고 이어서 작업할 수 있다. 또한 이미 실행 중인 OpenCode Web 서버에 attach 로 터미널 UI를 다시 붙일 수 있기 때문에, 웹과 터미널을 동시에 같은 세션 상태로 사용할 수 있다.
나는 평소 노트북에서 OpenCode 세션을 열어두고 작업하다가, 노트북을 덮거나 이동하면 세션이 끊기는 점이 불편했다. 그래서 항상 켜두는 집의 맥미니에 OpenCode Web 을 띄워두고, 노트북이나 휴대폰에서는 그 서버에 접속하는 방식으로 사용해보기로 했다.
OpenCode Web 을 쓰는 이유
- 맥미니에서 OpenCode 세션을 계속 유지할 수 있다.
- 노트북을 닫거나 자리를 이동해도 세션이 맥미니에 남아 있다.
- 휴대폰에서는 브라우저로 바로 붙을 수 있다.
- 노트북에서는 브라우저로도 붙을 수 있고, 필요하면
opencode attach로 터미널 UI도 다시 붙일 수 있다. - Tailscale 과 함께 사용하면 포트포워딩 없이도 외부에서 안전하게 접속할 수 있다. OpenCode 는
--hostname,--port,--mdns, 인증용 환경변수 등을 지원하고, Tailscale 은 MagicDNS 로 각 장비에*.ts.net이름을 붙여준다.
OpenCode Web 기본 개념
OpenCode Web 은 기본적으로 127.0.0.1 에 랜덤 포트로 실행된다. 즉, 아무 옵션 없이 opencode web 을 실행하면 현재 장비에서만 접속 가능한 로컬 웹 서버가 뜬다. 다른 기기에서 접속하려면 --hostname 0.0.0.0 으로 바인딩 범위를 넓혀야 한다. 포트도 명시하지 않으면 랜덤 포트가 선택되므로, 여러 기기에서 접속하려면 --port 로 고정하는 편이 훨씬 편하다. 또한 네트워크 접근 시에는 OPENCODE_SERVER_PASSWORD 를 설정해 인증을 거는 것이 권장된다. 사용자명 기본값은 opencode 이고, 필요하면 OPENCODE_SERVER_USERNAME 으로 바꿀 수 있다.
또 하나 유용한 점은 opencode attach 이다. 이미 떠 있는 opencode web 서버에 터미널 TUI를 다시 붙일 수 있기 때문에, 맥미니에서 올라간 OpenCode 서버를 기준으로 브라우저와 터미널을 같이 사용할 수 있다. 즉, 웹에서 보던 세션을 노트북 터미널에서 이어서 다룰 수 있다.
Tailscale 과 함께 사용하는 이유
맥미니, 노트북, 휴대폰이 모두 Tailscale 에 붙어 있다면 구성이 굉장히 단순해진다. 별도의 공유기 포트포워딩 없이, Tailscale 네트워크 안에서 맥미니 주소로 바로 접속할 수 있기 때문이다.
특히 MagicDNS 를 켜두면 각 장비는 machine-name.tailnet-name.ts.net 형태의 이름을 갖게 된다. 경우에 따라서는 짧은 머신명만으로도 접근이 가능하지만, 가장 명확한 방법은 전체 *.ts.net 주소를 사용하는 것이다. 집 밖에서 아이폰으로 접속할 때도 같은 주소를 그대로 사용할 수 있다는 점이 편하다.
아이폰에서는 Tailscale 의 VPN On Demand 도 같이 켜두면 더 편하다. 이 기능을 사용하면 Wi-Fi 나 Cellular 조건에 따라 Tailscale 연결을 자동으로 올릴 수 있다. 즉, 외부에서 Safari 로 맥미니의 OpenCode Web 주소를 열 때 Tailscale 이 자동으로 연결되도록 구성할 수 있다.
OpenCode Web 맛보기
내가 사용한 가장 단순한 방식은 아래와 같다.
- 맥미니에 OpenCode Web 실행
- 고정 포트 사용
- 비밀번호 설정
- 다른 장비에서는 Tailscale 주소로 접속
1. 맥미니에서 OpenCode Web 실행
export OPENCODE_SERVER_PASSWORD=‘강한비밀번호’
opencode web —hostname 0.0.0.0 —port 4096
위와 같이 실행하면 맥미니에서 OpenCode Web 서버가 뜬다.
기본 동작과 달리 0.0.0.0 으로 열었기 때문에 다른 장비에서도 접근할 수 있고, 포트를 4096 으로 고정했기 때문에 접속 주소도 매번 바뀌지 않는다. 네트워크 접근용이므로 비밀번호도 같이 걸어두었다.
이제 다른 장비에서는 아래처럼 접속하면 된다.
http://macmini.tailnet-name.ts.net:4096
예를 들어 내 맥미니의 Tailscale 이름이 macmini 이고, tailnet 이름이 example.ts.net 이라면 아래처럼 접속하는 식이다.
http://macmini.example.ts.net:4096
여기서 macmini.example.ts.net 형태의 주소는 Tailscale MagicDNS 가 제공하는 이름이다.
휴대폰에서는 어떻게 붙는가
휴대폰에서는 별도의 터미널 앱보다 브라우저 접속이 가장 단순하다.
아이폰에서 Safari 를 열고 아래 주소로 접속하면 된다.
http://macmini.example.ts.net:4096
로그인 창이 뜨면 사용자명은 기본적으로 opencode 이고, 비밀번호는 OPENCODE_SERVER_PASSWORD 로 설정한 값을 입력하면 된다. OpenCode Web 은 세션 목록을 보여주고, 기존 세션을 다시 열어 이어서 사용할 수 있다.
아이폰에서 더 편하게 쓰고 싶다면 Tailscale 앱에서 VPN On Demand 를 켜두는 것도 좋다. 외부 Wi-Fi 나 셀룰러 환경에서 Tailscale 연결이 자동으로 올라오도록 만들 수 있어서, 매번 수동으로 VPN 을 올리지 않아도 된다.
노트북에서는 어떻게 붙는가
노트북에서는 두 가지 방식이 가능하다.
첫 번째는 브라우저로 접속하는 방식이다.
http://macmini.example.ts.net:4096
두 번째는 터미널 UI로 다시 붙는 방식이다.
opencode attach http://macmini.example.ts.net:4096
이 방식의 장점은 브라우저와 터미널이 같은 세션과 상태를 공유한다는 점이다. 예를 들어 맥미니에서 OpenCode Web 을 띄워두고, 휴대폰에서 잠깐 세션을 확인한 뒤, 나중에 노트북 터미널에서 attach 로 이어서 작업할 수 있다.
설정 파일로 관리할 수도 있다
매번 실행 옵션을 길게 치기 번거롭다면 opencode.json 에 서버 설정을 넣어둘 수도 있다. OpenCode Web 문서에서는 server 항목에 port, hostname, mdns, cors 등을 넣는 예시를 제공한다. 커맨드라인 플래그가 설정 파일보다 우선한다는 점도 같이 기억해두면 좋다.
예시는 아래와 같다.
{
“server”: {
“port”: 4096,
“hostname”: “0.0.0.0”,
“mdns”: true
}
}
mDNS 를 켜면 로컬 네트워크에서는 opencode.local 같은 이름으로도 발견할 수 있다. 다만 내가 이번 글에서 구성한 방식은 Tailscale 을 전제로 한 단순 구성이기 때문에, 실제 사용에서는 Tailscale 주소만으로도 충분했다.
정리
정리하면, 내가 원했던 것은 세션이 노트북에 매달려 있지 않고 집 맥미니에 남아 있는 구조였다. OpenCode Web 과 Tailscale 을 같이 사용하니 이 구성이 생각보다 단순하게 만들어졌다.
- 맥미니에서
opencode web실행 --hostname 0.0.0.0과--port로 네트워크 접근 가능하게 설정OPENCODE_SERVER_PASSWORD로 인증 추가- 노트북/휴대폰에서는 Tailscale 주소로 접속
- 필요하면 노트북 터미널에서
opencode attach로 같은 세션 재접속
개인적으로는 “항상 켜져 있는 집 맥미니를 OpenCode 호스트로 쓰고, 나는 어디서든 그 세션에 붙는다” 는 사용감이 꽤 좋았다. 특히 휴대폰에서 브라우저로 세션을 확인할 수 있다는 점이 생각보다 편했다. 앞으로는 여기에 launchd 로 자동 실행까지 붙여서 맥미니가 재부팅돼도 바로 OpenCode Web 이 올라오도록 구성해볼 생각이다.
Reference
사용후기
OpenCode 를 처음에는 그냥 터미널 기반 도구로만 생각했는데, web 과 attach 를 같이 써보니 활용 방식이 꽤 넓어졌다. 특히 내 노트북이 아니라 집의 항상 켜져 있는 장비를 기준점으로 세션을 유지할 수 있다는 점이 좋았다. 아직 장기간 써본 것은 아니지만, 적어도 “맥미니에 세션을 붙여두고 여러 단말에서 이어서 쓰는 방식” 은 꽤 실용적이라는 느낌을 받았다. 다음에는 여기에 자동 실행까지 붙여서 더 안정적으로 써봐야겠다. 👋