본문으로 건너뛰기

VS Code Remote Tunnel 기반 개발 환경 가이드

등록일: 2026-05-08 최종 수정일: 2026-05-11

본 문서는 스마트폰(S23) 및 랩독(Lapdock) 환경에서 홈서버 자원을 활용하기 위한 'Remote Tunnel'의 설치, 자동 실행 설정, 트러블슈팅 및 제거 방법을 기술함.

1. 서버 측 설정 (Home Server Side)​

[설치 및 인증]​

  1. 홈서버 터미널에서 다음 명령어를 실행하여 터널을 개설함. 
    code tunnel
  2. 출력되는 8자리 인증 코드를 확인한 뒤, github.com/login/device 또는 microsoft.com/devicelogin 접속.
  3. 코드 입력 후 GitHub 또는 Microsoft 계정으로 로그인하여 인증을 완료함.
  4. 생성된 터널 주소(https://vscode.dev/tunnel/<servername>)를 기록함.

[백그라운드 서비스 등록]​

터미널을 종료하거나 서버 재부팅 시에도 터널이 자동 실행되도록 시스템 서비스로 등록하고 세션을 유지함.

# 서비스 설치 및 자동 시작 설정
code tunnel service install

# (권장) 유저 로그아웃 후에도 서비스가 중단되지 않도록 Linger 설정
sudo loginctl enable-linger $USER

2. 트러블슈팅 (Troubleshooting)​

[인증 대기 문제 발생 시]​

접속 시 "오프라인"으로 표시되거나 로그에 authorization_pending 에러가 발생할 경우 아래 절차를 따름.

  1. 기존 서비스 중지 및 로그아웃

    systemctl --user stop code-tunnel.service
    code tunnel user logout

  2. 수동 재인증 수행

    code tunnel --name <기존 서버이름>
    # 출력되는 코드로 브라우저에서 재인증 완료 후 Ctrl+C로 종료

  3. 서비스 재시작

    systemctl --user start code-tunnel.service
    # 상태 확인
    code tunnel service log

3. 클라이언트 접속 (Client Side)​

[PWA 설치]​

  1. 폰 브라우저(삼성 인터넷/크롬)에서 기록한 터널 주소로 접속함.
  2. 브라우저 메뉴에서 **'홈 화면에 추가'**를 선택하여 설치함.
  3. 홈 화면의 아이콘을 실행하여 독립된 앱 환경에서 작업함.

[원격 연결]​

  1. 하단 파란색 원격 아이콘 또는 Connect to Tunnel 메뉴를 선택함.
  2. 서버에서 설정한 터널 이름을 선택하여 홈서버 환경에 진입함.

4. 서비스 제거 및 정리 (Uninstall)​

환경을 초기화하거나 서비스를 중단하고 싶을 때 아래 명령어를 사용함.

[서비스 해제]​

# 서비스 중단 및 제거
code tunnel service uninstall

[터널 로그아웃 및 데이터 정리]​

# 계정 로그아웃
code tunnel user logout

# (수동 설치한 경우) 바이너리 삭제
rm code vscode_cli.tar.gz

5. 운용 팁​

  • 확장 프로그램: Cline, Codex 등의 AI 확장은 서버 측에 설치되어 클라이언트 자원을 소모하지 않음.
  • 포트 포워딩: React, Spring Boot 실행 시 자동으로 로컬 루프백(localhost) 터널링이 수행됨.
  • 네트워크: 인터넷 재연결 시 세션이 자동으로 복구되므로 이동 중에도 안정적인 작업이 가능함.