원격/Devcontainer 모드 설정

이 강의를 마치면

SSH로 연결된 원격 서버에서 Plannotator를 사용할 수 있습니다
VS Code devcontainer에서 Plannotator를 설정하고 접속할 수 있습니다
WSL(Windows Subsystem for Linux) 환경에서 Plannotator를 사용할 수 있습니다
포트 포워딩을 설정하여 로컬 브라우저에서 원격 환경의 Plannotator에 접속할 수 있습니다

현재 겪고 있는 문제

원격 서버, devcontainer 또는 WSL 환경에서 Claude Code나 OpenCode를 사용하고 있습니다. AI가 계획을 생성하거나 코드 검토가 필요할 때 Plannotator가 원격 환경에서 브라우저를 열려고 하지만, 그곳에는 그래픽 인터페이스가 없거나 로컬 브라우저에서 검토 화면을 보고 싶은 상황입니다.

이 기능이 필요한 상황

원격/Devcontainer 모드가 필요한 대표적인 시나리오:

시나리오	설명
SSH 연결	SSH로 원격 개발 서버에 연결하여 작업
Devcontainer	VS Code에서 devcontainer를 사용하여 개발
WSL	Windows에서 WSL을 사용하여 Linux 개발
클라우드 환경	코드가 클라우드의 컨테이너나 가상 머신에서 실행

핵심 개념

원격 환경에서 Plannotator를 사용하려면 두 가지 문제를 해결해야 합니다:

포트 고정: 원격 환경에서는 포트 포워딩 설정이 필요하므로 랜덤 포트를 자동 선택할 수 없습니다
브라우저 접속: 원격 환경에는 그래픽 인터페이스가 없으므로 로컬 머신의 브라우저에서 접속해야 합니다

Plannotator는 PLANNOTATOR_REMOTE 환경 변수를 감지하여 자동으로 "원격 모드"로 전환됩니다:

랜덤 포트 대신 고정 포트(기본값 19432) 사용
브라우저 자동 열기 건너뛰기
터미널에 URL 출력하여 로컬 브라우저에서 수동으로 접속 가능

🎒 시작하기 전 준비

사전 요구사항

이 튜토리얼을 시작하기 전에 확인하세요:

빠른 시작 완료
Claude Code 플러그인 또는 OpenCode 플러그인 설치 및 설정 완료
기본적인 SSH 또는 devcontainer 설정 개념 이해

따라하기

1단계: 원격 모드 환경 변수 이해하기

Plannotator 원격 모드는 세 가지 환경 변수에 의존합니다:

환경 변수	설명	기본값
`PLANNOTATOR_REMOTE`	원격 모드 활성화	미설정(로컬 모드)
`PLANNOTATOR_PORT`	고정 포트 번호	랜덤(로컬) / 19432(원격)
`PLANNOTATOR_BROWSER`	사용자 지정 브라우저 경로	시스템 기본 브라우저

왜 필요한가요

PLANNOTATOR_REMOTE는 Plannotator에게 현재 원격 환경임을 알려 브라우저 열기를 시도하지 않게 합니다
PLANNOTATOR_PORT는 고정 포트를 설정하여 포트 포워딩 설정을 용이하게 합니다
PLANNOTATOR_BROWSER(선택 사항)는 로컬 머신에서 사용할 브라우저 경로를 지정합니다

2단계: SSH 원격 서버에서 설정하기

SSH 포트 포워딩 설정

SSH 설정 파일 ~/.ssh/config를 편집합니다:

bash

Host your-server
    HostName your-server.com
    User your-username
    LocalForward 9999 localhost:9999

예상 결과:

LocalForward 9999 localhost:9999 라인이 추가됨
로컬 9999 포트의 트래픽이 원격 서버의 9999 포트로 포워딩됨

원격 서버에서 환경 변수 설정

원격 서버에 연결한 후 터미널에서 환경 변수를 설정합니다:

bash

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999

왜 필요한가요

PLANNOTATOR_REMOTE=1은 원격 모드를 활성화합니다
PLANNOTATOR_PORT=9999는 SSH 설정의 포트 번호와 일치하는 고정 포트 9999를 사용합니다

영구 설정

매번 연결할 때마다 환경 변수를 수동으로 설정하는 것이 번거롭다면, 셸 설정 파일(~/.bashrc 또는 ~/.zshrc)에 추가할 수 있습니다:

bash

echo 'export PLANNOTATOR_REMOTE=1' >> ~/.bashrc
echo 'export PLANNOTATOR_PORT=9999' >> ~/.bashrc
source ~/.bashrc

Plannotator 사용하기

이제 원격 서버에서 Claude Code나 OpenCode를 정상적으로 사용할 수 있습니다. AI가 계획을 생성하거나 코드 검토가 필요할 때:

bash

# 원격 서버에서 터미널에 다음과 유사한 메시지가 출력됩니다:
[Plannotator] Server running at http://localhost:9999
[Plannotator] Access from your local machine: http://localhost:9999

예상 결과:

터미널에 Plannotator URL이 표시됨
원격 환경에서 브라우저가 열리지 않음(정상 동작)

로컬 브라우저에서 접속하기

로컬 머신의 브라우저에서 다음 주소를 엽니다:

http://localhost:9999

예상 결과:

Plannotator 검토 화면이 정상적으로 표시됨
로컬 환경에서처럼 계획 검토나 코드 검토를 진행할 수 있음

체크포인트 ✅:

[ ] SSH 포트 포워딩 설정 완료
[ ] 환경 변수 설정 완료
[ ] 원격 서버 터미널에 URL 출력됨
[ ] 로컬 브라우저에서 검토 화면 접속 가능

3단계: VS Code Devcontainer에서 설정하기

devcontainer 설정

.devcontainer/devcontainer.json 파일을 편집합니다:

json

{
  "name": "Your Devcontainer",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  "containerEnv": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  },

  "forwardPorts": [9999]
}

왜 필요한가요

containerEnv는 컨테이너 내부의 환경 변수를 설정합니다
forwardPorts는 VS Code에게 컨테이너 포트를 로컬로 자동 포워딩하도록 지시합니다

devcontainer 재빌드 및 시작

VS Code 명령 팔레트를 엽니다(Ctrl+Shift+P 또는 Cmd+Shift+P)
Dev Containers: Rebuild Container를 입력하고 실행합니다
컨테이너 재빌드가 완료될 때까지 기다립니다

예상 결과:

VS Code 오른쪽 하단에 포트 포워딩 상태가 표시됨(보통 작은 아이콘)
클릭하면 "Port 9999"가 포워딩되었음을 확인할 수 있음

Plannotator 사용하기

devcontainer에서 Claude Code나 OpenCode를 정상적으로 사용합니다. AI가 계획을 생성할 때:

bash

# 컨테이너 내부 터미널 출력:
[Plannotator] Server running at http://localhost:9999

예상 결과:

터미널에 Plannotator URL이 표시됨
컨테이너에서 브라우저가 열리지 않음(정상 동작)

로컬 브라우저에서 접속하기

로컬 머신의 브라우저에서 다음 주소를 엽니다:

http://localhost:9999

예상 결과:

Plannotator 검토 화면이 정상적으로 표시됨

체크포인트 ✅:

[ ] devcontainer 설정에 환경 변수와 포트 포워딩 추가 완료
[ ] 컨테이너 재빌드 완료
[ ] VS Code에서 포트 포워딩 상태 확인됨
[ ] 로컬 브라우저에서 검토 화면 접속 가능

4단계: WSL 환경에서 설정하기

WSL 환경 설정은 SSH 연결과 유사하지만, 포트 포워딩을 수동으로 설정할 필요가 없습니다—WSL이 자동으로 localhost 트래픽을 Windows 시스템으로 포워딩합니다.

환경 변수 설정

WSL 터미널에서 환경 변수를 설정합니다:

bash

export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999

영구 설정

WSL 셸 설정 파일(~/.bashrc 또는 ~/.zshrc)에 환경 변수를 추가합니다:

bash

echo 'export PLANNOTATOR_REMOTE=1' >> ~/.bashrc
echo 'export PLANNOTATOR_PORT=9999' >> ~/.bashrc
source ~/.bashrc

Plannotator 사용하기

WSL에서 Claude Code나 OpenCode를 정상적으로 사용합니다:

bash

# WSL 터미널 출력:
[Plannotator] Server running at http://localhost:9999

예상 결과:

터미널에 Plannotator URL이 표시됨
WSL에서 브라우저가 열리지 않음(정상 동작)

Windows 브라우저에서 접속하기

Windows 브라우저에서 다음 주소를 엽니다:

http://localhost:9999

예상 결과:

Plannotator 검토 화면이 정상적으로 표시됨

체크포인트 ✅:

[ ] 환경 변수 설정 완료
[ ] WSL 터미널에 URL 출력됨
[ ] Windows 브라우저에서 검토 화면 접속 가능

자주 발생하는 문제

포트가 이미 사용 중

다음과 유사한 오류가 표시되는 경우:

Error: bind: EADDRINUSE: address already in use :::9999

해결 방법:

포트 번호 변경:

bash

export PLANNOTATOR_PORT=10000  # 사용되지 않는 다른 포트로 변경

또는 9999 포트를 사용 중인 프로세스 종료:
bash
```
lsof -ti:9999 | xargs kill -9
```

SSH 포트 포워딩이 작동하지 않음

로컬 브라우저에서 Plannotator에 접속할 수 없는 경우:

확인 사항:

[ ] SSH 설정 파일의 LocalForward 포트 번호가 PLANNOTATOR_PORT와 일치하는지 확인
[ ] SSH 연결을 끊고 다시 연결했는지 확인
[ ] 방화벽이 포트 포워딩을 차단하지 않는지 확인

Devcontainer 포트 포워딩이 작동하지 않음

VS Code가 자동으로 포트를 포워딩하지 않는 경우:

해결 방법:

.devcontainer/devcontainer.json의 forwardPorts 설정 확인
수동으로 포트 포워딩:
- VS Code 명령 팔레트 열기
- Forward a Port 실행
- 포트 번호 9999 입력

WSL에서 접속 불가

Windows 브라우저에서 WSL의 Plannotator에 접속할 수 없는 경우:

해결 방법:

환경 변수가 올바르게 설정되었는지 확인
localhost 대신 0.0.0.0 사용 시도(WSL 버전과 네트워크 설정에 따라 다름)
Windows 방화벽 설정 확인

이 강의 요약

원격/Devcontainer 모드의 핵심 포인트:

포인트	설명
환경 변수	`PLANNOTATOR_REMOTE=1`로 원격 모드 활성화
고정 포트	`PLANNOTATOR_PORT`로 고정 포트 설정(기본값 19432)
포트 포워딩	SSH/Devcontainer는 포트 포워딩 설정 필요, WSL은 자동 포워딩
수동 접속	원격 모드에서는 브라우저가 자동으로 열리지 않으므로 로컬 브라우저에서 수동 접속 필요
영구 설정	환경 변수를 설정 파일에 추가하여 반복 설정 방지

다음 강의 예고

다음 강의에서는 **환경 변수 설정 상세 가이드**를 배웁니다.
배우게 될 내용:
사용 가능한 모든 Plannotator 환경 변수
각 환경 변수의 역할과 기본값
다양한 시나리오에 맞게 환경 변수를 조합하는 방법

부록: 소스 코드 참조

소스 코드 위치 보기

업데이트 날짜: 2026-01-24

기능	파일 경로	라인 번호
원격 세션 감지	`packages/server/remote.ts`	16-29
서버 포트 가져오기	`packages/server/remote.ts`	34-49
서버 시작 로직	`packages/server/index.ts`	91-97
브라우저 열기 로직	`packages/server/browser.ts`	45-74
WSL 감지	`packages/server/browser.ts`	11-34

주요 상수:

DEFAULT_REMOTE_PORT = 19432: 원격 모드 기본 포트 번호

주요 함수:

isRemoteSession(): 원격 세션에서 실행 중인지 감지
getServerPort(): 서버 포트 가져오기(원격은 고정 포트, 로컬은 랜덤 포트)
openBrowser(url): 크로스 플랫폼 브라우저 열기

원격/Devcontainer 모드 설정 ​

이 강의를 마치면 ​

현재 겪고 있는 문제 ​

이 기능이 필요한 상황 ​

핵심 개념 ​

🎒 시작하기 전 준비 ​

따라하기 ​

1단계: 원격 모드 환경 변수 이해하기 ​

2단계: SSH 원격 서버에서 설정하기 ​

SSH 포트 포워딩 설정 ​

원격 서버에서 환경 변수 설정 ​

Plannotator 사용하기 ​

로컬 브라우저에서 접속하기 ​

3단계: VS Code Devcontainer에서 설정하기 ​

devcontainer 설정 ​

devcontainer 재빌드 및 시작 ​

Plannotator 사용하기 ​

로컬 브라우저에서 접속하기 ​

4단계: WSL 환경에서 설정하기 ​

환경 변수 설정 ​

Plannotator 사용하기 ​

Windows 브라우저에서 접속하기 ​

자주 발생하는 문제 ​

포트가 이미 사용 중 ​

SSH 포트 포워딩이 작동하지 않음 ​

Devcontainer 포트 포워딩이 작동하지 않음 ​

WSL에서 접속 불가 ​

이 강의 요약 ​

다음 강의 예고 ​

부록: 소스 코드 참조 ​

원격/Devcontainer 모드 설정

이 강의를 마치면

현재 겪고 있는 문제

이 기능이 필요한 상황

핵심 개념

🎒 시작하기 전 준비

따라하기

1단계: 원격 모드 환경 변수 이해하기

2단계: SSH 원격 서버에서 설정하기

SSH 포트 포워딩 설정

원격 서버에서 환경 변수 설정

Plannotator 사용하기

로컬 브라우저에서 접속하기

3단계: VS Code Devcontainer에서 설정하기

devcontainer 설정

devcontainer 재빌드 및 시작

Plannotator 사용하기

로컬 브라우저에서 접속하기

4단계: WSL 환경에서 설정하기

환경 변수 설정

Plannotator 사용하기

Windows 브라우저에서 접속하기

자주 발생하는 문제

포트가 이미 사용 중

SSH 포트 포워딩이 작동하지 않음

Devcontainer 포트 포워딩이 작동하지 않음

WSL에서 접속 불가

이 강의 요약

다음 강의 예고

부록: 소스 코드 참조