VS Code SSH 원격 접속 개발 환경 세팅하기 완벽 가이드

VS Code SSH 원격 접속 개발 환경 세팅하기

회사 업무용 노트북은 사양이 애매하고, 집에 있는 고성능 데스크톱이나 클라우드 서버의 성능을 활용하고 싶을 때가 많습니다. 저는 처음에 AWS EC2 인스턴스를 띄워놓고 Putty로 접속해서 vim으로 코딩했는데, 솔직히 너무 불편했습니다. 자동완성도 제대로 안 되고, 파일 탐색도 일일이 ls 명령어로 확인해야 했죠. 그러다가 VS Code SSH 원격 접속 개발 환경 세팅하기를 알게 되면서 완전히 새로운 세계가 열렸습니다.

왜 VS Code SSH 원격 개발을 사용해야 할까?

로컬 환경 vs 원격 개발 환경

로컬 개발 환경은 내 컴퓨터에서 모든 걸 처리하는 방식입니다. 간단한 프로젝트라면 문제없지만, 머신러닝 모델 학습이나 대용량 데이터 처리 작업을 하려면 내 노트북 팬이 비행기 이륙 소리를 내기 시작하죠. 원격 개발 환경은 강력한 서버의 자원을 활용하면서도, 내 로컬 에디터의 편리함을 그대로 유지할 수 있습니다.

Putty, iTerm 대비 VS Code Remote SSH의 장점

저는 초기에 iTerm으로 서버 접속해서 vim으로 개발했습니다. 리눅스 명령어에 익숙하다면 나름 멋있어 보이지만, 실전에서는 정말 비효율적이었어요. 파일 트리 구조를 한눈에 볼 수 없고, 디버깅할 때 브레이크포인트 찍기도 어렵고, Git GUI 도구도 못 쓰고… VS Code SSH 원격 접속 개발 환경 세팅하기를 하면 이런 문제가 한 번에 해결됩니다.

어떤 상황에서 필요한가?

제 경험상 이런 경우에 VS Code SSH 원격 접속 개발 환경 세팅하기가 꼭 필요했습니다:

• 부업으로 웹 크롤링 자동화를 만들 때 – 24시간 돌아가는 서버가 필요했어요
• MacBook에서 Linux 환경 개발할 때 – Docker보다 훨씬 가볍고 빨랐습니다
• 회사와 집에서 같은 개발 환경을 쓰고 싶을 때 – 코드 동기화 걱정 없이
• GPU가 필요한 ML 프로젝트를 할 때 – 클라우드 GPU 인스턴스 활용

사전 준비사항

VS Code Remote SSH 확장 설치

먼저 VS Code를 실행하고 확장 탭(Ctrl+Shift+X)에서 “Remote – SSH”를 검색해서 설치합니다. Microsoft에서 공식적으로 제공하는 확장이니 안심하고 설치하세요. 저는 처음에 비슷한 이름의 다른 확장을 설치해서 헤맸던 기억이 있습니다. 꼭 “Remote – SSH” 정확한 이름으로 검색하세요.

설치 후 왼쪽 사이드바에 원격 연결 아이콘(모니터 모양)이 생깁니다. 이게 보이면 제대로 설치된 겁니다.

원격 서버 SSH 접속 확인 (22번 포트)

VS Code SSH 원격 접속 개발 환경 세팅하기를 하려면 원격 서버가 SSH 접속을 허용해야 합니다. 대부분 22번 포트를 사용합니다. AWS EC2를 쓴다면 보안 그룹(Security Group)에서 22번 포트를 내 IP로 열어둬야 합니다.

저는 처음에 이걸 몰라서 계속 “Connection timeout” 오류를 봤습니다. 방화벽 설정을 꼭 확인하세요!

기존에 Putty나 터미널로 접속이 되는지 먼저 테스트해보는 게 좋습니다:

• Windows: cmd나 PowerShell에서 ssh user@server-ip
• Mac/Linux: 터미널에서 ssh user@server-ip

SSH 클라이언트 설치 확인 (Windows/Mac/Linux)

Mac과 Linux는 기본적으로 SSH 클라이언트가 설치되어 있습니다. 문제는 Windows입니다. Windows 10 이후 버전은 OpenSSH가 기본 탑재되어 있지만, 이전 버전은 별도로 설치해야 합니다.

PowerShell을 관리자 권한으로 실행해서 다음 명령어로 확인하세요:

ssh -V

버전이 출력되면 설치된 겁니다. 만약 “명령을 찾을 수 없습니다” 오류가 나오면 Windows 설정 > 앱 > 선택적 기능에서 OpenSSH 클라이언트를 설치해야 합니다.

VS Code에서 SSH 원격 접속 설정하기

SSH Config 파일 작성 및 관리

VS Code SSH 원격 접속 개발 환경 세팅하기의 핵심은 SSH config 파일입니다. 이 파일에 서버 정보를 저장해두면 매번 IP 주소와 사용자명을 입력할 필요가 없습니다.

VS Code에서 F1 키를 누르고 “Remote-SSH: Open SSH Configuration File”을 검색해서 실행합니다. 보통 다음 위치에 파일이 생성됩니다:

• Windows: C:\Users\사용자명\.ssh\config
• Mac/Linux: ~/.ssh/config

파일을 열어서 다음과 같이 작성합니다:

Host my-server
  HostName 123.456.78.90
  User ubuntu
  Port 22

저는 여러 서버를 관리해서 이렇게 여러 개를 등록해뒀습니다:

Host aws-dev
  HostName ec2-xx-xxx-xxx-xx.compute.amazonaws.com
  User ec2-user
  IdentityFile ~/.ssh/aws-key.pem

Host home-server
  HostName 192.168.0.100
  User pi
  Port 22

원격 서버 연결 및 폴더 열기

config 파일을 저장한 후 F1 키를 누르고 “Remote-SSH: Connect to Host”를 실행합니다. 방금 등록한 서버 이름(예: my-server)이 목록에 나타납니다. 선택하면 새 창이 열리면서 연결이 시작됩니다.

처음 연결할 때는 fingerprint 확인 메시지가 나옵니다. “Continue”를 선택하세요. 비밀번호를 입력하라는 창이 뜨면 서버 계정의 비밀번호를 입력합니다.

연결되면 왼쪽 하단에 “SSH: my-server”라고 표시됩니다. 이제 “Open Folder”를 클릭해서 원격 서버의 작업 폴더를 선택하세요. 저는 보통 /home/ubuntu/projects 같은 경로를 엽니다.

연결 테스트 및 터미널 사용법

폴더를 열면 왼쪽에 파일 트리가 보입니다. 이게 바로 원격 서버의 실제 파일들입니다! 이제 Ctrl+`(백틱)을 눌러 터미널을 열어보세요. 이 터미널은 원격 서버에서 실행되는 터미널입니다.

간단한 테스트를 해봅시다:

pwd – 현재 경로 확인
ls -la – 파일 목록 확인
python –version – 파이썬 버전 확인

저는 처음에 이게 로컬 터미널인 줄 알고 헤맸는데, VS Code SSH 원격 접속 개발 환경 세팅하기를 하면 터미널도 원격 서버에서 실행됩니다. 매우 직관적이에요!

SSH 키 기반 인증으로 보안 강화하기

SSH 키 페어 생성하기

매번 비밀번호 입력하는 게 귀찮고, 보안도 약합니다. SSH 키 인증을 설정하면 비밀번호 없이 자동으로 로그인할 수 있습니다. VS Code SSH 원격 접속 개발 환경 세팅하기에서 이 부분이 정말 중요합니다.

로컬 컴퓨터의 터미널(또는 PowerShell)에서 다음 명령어를 실행합니다:

ssh-keygen -t rsa -b 4096 -C “your_email@example.com”

키를 저장할 경로를 물어보는데, 그냥 Enter를 눌러 기본 경로(~/.ssh/id_rsa)에 저장하세요. passphrase를 물어보는데, 보안을 더 강화하고 싶으면 입력하고 아니면 Enter로 넘어갑니다.

저는 처음에 passphrase를 설정했다가 결국 지웠습니다. 자동화 스크립트 돌릴 때마다 입력해야 해서 번거로웠거든요.

ssh-copy-id로 공개키 등록하기

생성한 공개키를 원격 서버에 등록해야 합니다. Mac/Linux라면 간단합니다:

ssh-copy-id user@server-ip

비밀번호를 한 번만 입력하면 공개키가 원격 서버의 ~/.ssh/authorized_keys 파일에 자동으로 추가됩니다.

Windows는 ssh-copy-id가 없어서 수동으로 해야 합니다. PowerShell에서:

type $env:USERPROFILE\.ssh\id_rsa.pub | ssh user@server-ip “cat >> ~/.ssh/authorized_keys”

저는 이 과정에서 “Permission denied” 오류를 여러 번 봤는데, 원격 서버의 ~/.ssh 폴더 권한이 문제였습니다. 원격 서버에 접속해서 다음 명령어로 권한을 수정하세요:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

비밀번호 없이 자동 로그인 설정

공개키 등록이 끝나면 VS Code를 완전히 종료하고 다시 시작합니다. 그리고 다시 원격 서버에 연결해보세요. 비밀번호를 묻지 않고 바로 연결되면 성공입니다!

SSH config 파일에 IdentityFile 경로를 명시하면 더 확실합니다:

Host my-server
  HostName 123.456.78.90
  User ubuntu
  IdentityFile ~/.ssh/id_rsa

AWS EC2는 pem 키 파일을 제공하는데, 이 경로를 직접 지정하면 됩니다:

IdentityFile ~/.ssh/my-key.pem

원격 개발 환경 최적화 팁

원격 서버에 확장 프로그램 설치하기

VS Code SSH 원격 접속 개발 환경 세팅하기의 놀라운 점은 확장 프로그램을 원격 서버에도 설치할 수 있다는 겁니다. Python 개발한다면 원격 서버에 Python 확장을 설치하면 자동완성, 린팅이 모두 원격 서버 기준으로 동작합니다.

확장 탭(Ctrl+Shift+X)을 보면 확장들이 “LOCAL”과 “SSH: 서버이름”으로 구분되어 있습니다. 원격 서버에 설치하려면 SSH 섹션에서 Install 버튼을 누르면 됩니다.

제가 원격 서버에 필수로 설치하는 확장들:

• Python – 파이썬 개발 필수
• GitLens – Git 히스토리 확인
• Docker – 컨테이너 관리
• Prettier – 코드 포맷팅

포트 포워딩 활용법

원격 서버에서 웹 앱을 개발할 때 포트 포워딩이 정말 유용합니다. 예를 들어 Flask 앱을 5000번 포트로 실행하면, 로컬 브라우저에서는 접근할 수 없습니다. 이때 포트 포워딩을 설정하면 localhost:5000으로 접근 가능합니다.

VS Code 하단의 “PORTS” 탭을 클릭하고 “Forward a Port”를 클릭한 후 5000을 입력하면 됩니다. 이제 로컬 브라우저에서 http://localhost:5000 으로 접속하면 원격 서버의 앱이 보입니다!

저는 이걸 몰라서 처음에 원격 서버의 공인 IP로 접속하려고 했는데, 방화벽 때문에 계속 막혔습니다. 포트 포워딩을 알고 나서 개발이 훨씬 편해졌어요.

연결 끊김 방지 및 성능 최적화

원격 연결이 자주 끊기는 게 가장 큰 스트레스입니다. SSH config 파일에 다음 설정을 추가하면 연결이 훨씬 안정적입니다:

Host *
  ServerAliveInterval 60
  ServerAliveCountMax 3

60초마다 살아있는지 확인하고, 3번 응답이 없으면 연결을 끊는 설정입니다. 이렇게 하면 네트워크가 일시적으로 끊겼다가 복구되어도 연결이 유지됩니다.

성능 최적화를 위해 원격 서버의 VS Code Server 캐시를 주기적으로 정리하는 것도 좋습니다:

rm -rf ~/.vscode-server

저는 한 달에 한 번 정도 실행합니다. VS Code가 느려졌다 싶으면 이 명령어 한 방이면 해결돼요.

자주 묻는 질문 (FAQ)

Q. 연결이 자주 끊기는 경우 해결 방법은?

VS Code SSH 원격 접속 개발 환경 세팅하기에서 가장 많이 받는 질문입니다. 먼저 SSH config에 ServerAliveInterval과 ServerAliveCountMax를 설정하세요. 그래도 문제가 있다면 네트워크 방화벽이나 VPN 문제일 수 있습니다. 회사 네트워크에서는 보안 정책 때문에 장시간 SSH 연결을 끊는 경우가 많습니다. 이럴 때는 tmux나 screen 같은 터미널 멀티플렉서를 사용하면 연결이 끊겨도 작업 세션이 유지됩니다.

Q. AWS EC2 인스턴스 접속 시 주의사항은?

AWS EC2는 pem 키 파일을 사용합니다. 이 파일의 권한이 너무 열려있으면 SSH가 거부합니다. 반드시 다음 명령어로 권한을 조정하세요: chmod 400 your-key.pem (Mac/Linux) 또는 파일 속성에서 상속 비활성화 후 본인만 읽기 권한 설정 (Windows). 그리고 보안 그룹에서 22번 포트를 내 IP로만 열어두는 게 안전합니다. 0.0.0.0/0으로 열어두면 전 세계에서 접속 시도가 들어올 수 있어요.

Q. Windows에서 Permission denied 오류 해결법은?

Windows에서 SSH 키를 생성했을 때 권한 문제가 자주 발생합니다. .ssh 폴더와 키 파일의 권한을 조정해야 합니다. 파일 탐색기에서 .ssh 폴더를 우클릭 > 속성 > 보안 탭 > 고급 > 상속 비활성화 > 본인 계정만 남기고 모두 제거하세요. 또는 Git Bash를 사용하면 Linux 명령어로 chmod를 쓸 수 있어 더 쉽습니다. 저도 처음에는 PowerShell로 하다가 Git Bash로 갈아탔습니다.

Q. 여러 서버를 동시에 관리할 수 있나요?

물론입니다! VS Code는 여러 원격 서버에 동시에 연결할 수 있습니다. 각 서버마다 새 창을 열면 됩니다. 저는 개발 서버, 스테이징 서버, 운영 서버를 각각 다른 창으로 띄워놓고 작업합니다. SSH config 파일에 서버들을 모두 등록해두면 관리가 편합니다. Host 이름을 dev-server, staging-server 같이 구분하기 쉽게 지으면 좋습니다.

Q. 원격 서버의 파일을 로컬로 다운로드하려면?

파일 탐색기에서 파일을 우클릭하고 “Download”를 선택하면 됩니다. 여러 파일이나 폴더도 가능합니다. 반대로 로컬 파일을 원격으로 업로드할 때는 드래그 앤 드롭으로 간단하게 할 수 있습니다. 저는 처음에 scp 명령어로 일일이 전송했는데, VS Code에서는 정말 쉽게 할 수 있어서 놀랐습니다.

마치며

원격 개발 환경의 생산성 향상 효과

VS Code SSH 원격 접속 개발 환경 세팅하기를 도입한 후 제 개발 생산성이 확실히 올라갔습니다. 카페에서 맥북으로 작업하다가 집에 와서 데스크톱으로 이어서 작업하는 게 너무 자연스러워졌어요. 코드 동기화 걱정도 없고, 환경 설정도 한 번만 하면 되니까요.

특히 부업으로 크롤링 자동화를 만들 때, AWS 서버에서 24시간 돌려놓고 필요할 때만 VS Code로 접속해서 로그 확인하고 코드 수정하는 워크플로우가 정말 편합니다. Putty로 하던 때와는 비교도 안 될 정도로 쾌적합니다.

다음 단계로 시도해볼 것들

VS Code SSH 원격 접속 개발 환경 세팅하기를 마스터했다면 다음 단계로 도전해볼 만한 것들이 있습니다:

• Docker 컨테이너 원격 개발 – Remote-Containers 확장으로 격리된 환경 구축
• WSL 연동 – Windows에서 Linux 개발 환경을 더 가볍게
• Jupyter Notebook 통합 – 데이터 분석 작업을 원격 서버에서
• GitHub Codespaces – 클라우드 기반 개발 환경 경험

저는 이제 Docker 컨테이너 원격 개발을 시도해보려고 합니다. 프로젝트마다 독립된 환경을 만들 수 있어서 더 깔끔할 것 같거든요. 여러분도 VS Code SSH 원격 접속 개발 환경 세팅하기로 어디서든 코딩하는 자유를 누려보세요!