Remote Development (SSH, Dev Container, WSL)

이 장에서 다루는 것

이 장에서는 로컬이 아닌 곳에 있는 폴더를 워크스페이스로 열고, 그곳의 파일 · 터미널 · 언어 서버 · 빌드 도구를 그대로 사용하는 방법을 다룹니다. 지원 대상은 SSH 원격 서버, Dev Container(Docker), WSL 배포판 세 가지입니다.

원격 폴더를 열어도 프로젝트의 구성과 모델 파일 형식은 로컬과 같습니다. 대상 독자는 타깃 보드나 리눅스 빌드 환경에서 코드를 편집·빌드하려는 개발자입니다. 선행 조건은 각 방식마다 다릅니다. SSH는 접속 가능한 서버가, Dev Container는 로컬에 설치되어 실행 중인 Docker가, WSL은 Windows와 설치된 리눅스 배포판이 필요합니다. 원격에서 사용하는 코드 편집기·빌드·터미널 자체의 사용법은 16. 코드 편집 · 빌드 · 터미널 · 문서에서 확인할 수 있습니다.

17.1 진입점

원격 연결은 상태바의 원격 표시기 또는 명령 팔레트에서 시작합니다.

17.1.1 원격 표시기

상태바 가장 왼쪽에 >< 모양 표시기가 있습니다. 연결 상태에 따라 표시가 달라집니다.

상태	표시	색
연결 없음	아이콘만. 툴팁 Open a Remote Window	기본
SSH 연결 중 · 재연결 중	Connecting...	주황
SSH 연결됨	SSH: <호스트 레이블>	초록 배경
SSH 오류	Connection Error	빨강
컨테이너 연결됨	Container: <컨테이너 이름>	초록 배경
WSL 연결됨	WSL: <배포판 이름>	초록 배경

표시기를 클릭하면 화면 위쪽에서 내려오는 메뉴가 열립니다. 머리글은 Select an option to open a Remote Window 이며, Esc 또는 바깥 클릭으로 닫습니다.

17.1.2 연결되지 않은 상태의 메뉴

연결되지 않은 상태에서 표시기를 클릭하면 아래 항목이 표시됩니다.

항목	오른쪽 배지	동작
Connect to SSH Host...	Remote-SSH	SSH 빠른 연결 창을 엽니다(17.2.1)
Open Folder in Container...	Dev Containers	로컬 폴더의 devcontainer.json 으로 컨테이너를 만들고 들어갑니다
Add Dev Container Configuration Files...	Dev Containers	폴더에 devcontainer.json 을 만듭니다
Attach to Running Container...	Dev Containers	이미 실행 중인 컨테이너에 연결합니다
Connect to WSL	Remote-WSL	기본 배포판(없으면 목록의 첫 번째)에 연결합니다
Connect to WSL using Distro...	없음	배포판을 골라 연결합니다

상태바 맨 왼쪽 >< 표시기를 클릭하면 화면 위에서 이 메뉴가 내려옵니다. 머리글은 Select an option to open a Remote Window 이고, 오른쪽 배지로 어느 기능에 속하는지(Remote-SSH · Dev Containers · Remote-WSL)를 구분합니다. 맨 아래 Connect to WSL using Distro... 에만 배지가 없습니다.

17.1.3 연결된 상태의 메뉴

연결 종류에 따라 항목이 달라집니다.

연결 종류	메뉴 항목
SSH	Connect to SSH Host... / Open Remote Folder... / Close Remote Connection
WSL	Open WSL Folder... / Connect to WSL using Distro... / Close Remote Connection
컨테이너	Open Folder in Container... / Open Workspace in this Container... / Attach to Running Container... / (Rebuild Container) / (Reopen Folder Locally) / Close Remote Connection

Rebuild Container 와 Reopen Folder Locally 는 Open Folder in Container... 로 들어온 경우에만 나타납니다. Attach to Running Container... 로 연결한 컨테이너는 어느 로컬 폴더에서 왔는지 알 수 없어 두 동작이 성립하지 않습니다.

17.1.4 명령 팔레트

명령 팔레트에는 SSH와 WSL 항목만 있습니다. Dev Container 항목은 없으므로 상태바 표시기 메뉴를 사용해야 합니다.

분류	항목
Remote-SSH	Connect to SSH Host... / Open Remote Folder... / Disconnect from SSH Host / Add New SSH Host...
WSL	New WSL Terminal / Open WSL Folder... / Connect to WSL...

New WSL Terminal 은 이름과 달리 터미널만 여는 항목이 아니므로 주의가 필요합니다. Connect to WSL... 과 완전히 같은 동작이며, 배포판 선택 창을 띄우고 고른 배포판으로 연결한 뒤 창을 다시 로드합니다. 이미 WSL에 연결된 상태에서 터미널만 하나 더 필요하면 터미널 패널의 New Terminal 버튼을 사용합니다.

Disconnect from SSH Host 는 연결을 끊는 데 그치지 않고 저장된 원격 워크스페이스 기억까지 지웁니다. 다음 실행 시 자동으로 재연결하지 않습니다.

Ctrl+Shift+P 로 명령 팔레트를 열고 Remote 를 입력한 화면입니다. REMOTE-SSH 분류 아래에 네 항목이 모여 있고, 위 표와 같이 Dev Container 항목은 여기에 없습니다. 그쪽은 상태바 표시기 메뉴를 써야 합니다.

17.2 SSH

17.2.1 빠른 연결

Connect to SSH Host... 를 선택하면 화면 위쪽에 입력 창이 열립니다. 관리자 화면이 바로 열리지는 않습니다.

1. 입력란에 접속 정보를 입력하고 Enter 를 누릅니다. 안내 문구는 Enter SSH connection command (e.g. user@hostname, ssh user@host -p 2222) 입니다. user@host, user@host:2222, ssh user@host -p 2222 형식을 모두 해석합니다. 형식이 맞지 않으면 Invalid Format 대화상자에 Use: user@hostname or user@hostname:port 가 표시됩니다.
2. 입력하지 않고 아래 목록에서 선택할 수도 있습니다. 저장된 호스트는 Saved Hosts 아래에 레이블 과 user@host:port 로 나열됩니다.
3. 목록 맨 아래의 + Add New SSH Host... 또는 Configure SSH Hosts... 를 선택하면 호스트 관리자가 열립니다(17.2.2).
4. 연결이 성공하면 창이 다시 로드되고, 워크스페이스가 없으면 원격 폴더 선택 창이 자동으로 열립니다. 상태바에 SSH: <레이블> 이 표시되면 연결된 것입니다.

입력으로 직접 연결하면 그 정보가 user@host 레이블로 자동 저장되어 다음부터 목록에 나타납니다. 저장 위치는 PAIO 전용 파일이 아니라 사용자의 ~/.ssh/config 이며, 인증은 저장된 키와 ssh-agent를 먼저 시도하는 방식으로 등록됩니다(17.2.4).

Connect to SSH Host... 를 고르면 관리자가 아니라 이 입력 창이 먼저 열립니다. 입력란 아래로 Saved Hosts 목록이 이어지고, 그 밑에 + Add New SSH Host... 와 Configure SSH Hosts... 가 있습니다. 둘 중 아무것이나 고르면 호스트 관리자로 넘어갑니다.

17.2.2 SSH 호스트 관리자

제목이 SSH Remote Hosts 인 대화상자입니다. 각 요소는 다음과 같이 동작합니다.

요소	동작
Reload Config	~/.ssh/config 를 다시 읽습니다
+ Add Host	새 호스트 입력 양식을 엽니다
각 호스트의 Connect	그 호스트로 연결합니다
연필 아이콘	편집
✕ 아이콘	삭제합니다. Delete this SSH host configuration? 확인을 거칩니다
Disconnect (아래쪽)	연결되어 있을 때만 나타납니다

저장된 호스트가 없으면 No saved hosts. / Add a new host or import from SSH config. 가 표시됩니다. 연결 중에는 Connecting to <user>@<host>... 가, 실패하면 Connection failed: <원인> 과 Back to Host List 버튼이 나타납니다.

호스트 목록의 원본은 ~/.ssh/config 하나뿐입니다. 목록은 표시할 때마다 이 파일을 다시 읽어 만들어지고, 호스트를 추가·수정·삭제하면 이 파일의 Host 블록이 직접 수정됩니다. 따라서 파일을 손으로 편집해도 별도 가져오기 없이 반영되며, 반대로 PAIO에서 호스트를 지우면 그 블록이 파일에서 사라집니다. Host * 처럼 와일드카드가 들어간 블록은 목록에 나타나지 않습니다.

제목이 SSH Remote Hosts 인 대화상자입니다. 머리글에 Reload Config 와 + Add Host 가 있고, 그 아래에 ~/.ssh/config 에서 읽어들인 호스트가 레이블과 user@host:port 로 나열됩니다. 끝의 괄호는 파일 내용으로 다시 판정한 인증 방식입니다.

17.2.3 호스트 입력 항목

호스트를 추가하거나 편집할 때 입력하는 항목은 다음과 같습니다.

항목	기본값 / 자리표시자	설명
Label	비움 (My Server)	표시 이름. 비우면 user@host 가 됩니다
Host	비움 (192.168.1.100 or hostname)	IP 또는 호스트명. 필수
Port	22	1~65535
Username	비움 (ubuntu)	계정. 필수
Authentication	Private Key	Private Key / Password / SSH Agent
Private Key Path	비움 (~/.ssh/id_rsa)	Private Key 를 골랐을 때만 나타납니다
Remote Workspace Path (optional)	비움 (/home/user/workspace)	입력해도 아무 곳에서도 쓰이지 않습니다(아래 참고)

Host 나 Username 이 비어 있으면 각각 Host is required / Username is required 경고가 표시되고 저장되지 않습니다. 저장 버튼은 새로 만들 때 Save, 편집할 때 Update 로 표시되고, 그 왼쪽에 Cancel 이 있습니다.

+ Add Host 를 누른 화면입니다. 위 표의 일곱 항목과 자리표시자가 그대로 보입니다. Authentication 이 Private Key 이므로 Private Key Path 가 함께 나와 있고, 새로 만드는 중이므로 버튼은 Save 입니다.

저장은 ~/.ssh/config 의 Host 블록으로 이뤄지므로 그 파일이 표현할 수 있는 항목만 남습니다. Label · Host · Username · Port · Private Key Path 는 각각 Host · HostName · User · Port · IdentityFile 로 기록됩니다(레이블과 호스트가 같으면 HostName 이, 포트가 22면 Port 가 생략됩니다). 반면 Authentication 선택과 Remote Workspace Path는 기록되지 않습니다. 목록을 다시 읽을 때 Authentication은 파일 내용으로 다시 판정됩니다(ForwardAgent yes 면 SSH Agent, IdentityFile 이 있으면 Private Key, 둘 다 없으면 SSH Agent). 즉 Password 를 골라 저장해도 다음 목록 갱신에서는 그 선택이 남지 않습니다.

Remote Workspace Path 는 저장되지 않을 뿐 아니라 읽는 곳도 없습니다. 연결 후 열 폴더는 항상 원격 폴더 선택 창(17.5)에서 선택합니다.

17.2.4 인증이 시도되는 순서

빠른 연결과 목록 클릭으로 연결할 때는 아래 순서를 따릅니다.

1. 자격 증명 없이 먼저 연결합니다. 이 단계에서 ~/.ssh 의 키와 ssh-agent가 자동으로 시도됩니다.
2. 실패하면 비밀번호를 묻습니다. 문구는 <user>@<host>'s password: 입니다.
3. 비밀번호로도 실패하면 Failed to connect: <원인> 이 표시됩니다.

호스트 관리자에서 Connect 를 누르는 경로는 저장된 Authentication 값을 따릅니다. Password 면 Enter password for <user>@<host>: 를, Private Key 면 Enter passphrase for <키 경로> (leave empty if none): 를 묻습니다. 암호가 없으면 비워 둡니다.

17.2.5 호스트 키 검증

PAIO는 호스트 키 지문을 자체 저장소에 기록합니다. OpenSSH의 ~/.ssh/known_hosts 는 읽지도 쓰지도 않으므로, 터미널에서 접속해 본 서버라도 PAIO에서는 처음 보는 호스트로 취급됩니다.

• 처음 보는 호스트는 확인 절차 없이 수락하고 지문을 기록합니다. 첫 연결을 막지 않습니다.
• 다음 연결에서 지문이 바뀌면 연결을 거부하고 Host Key Changed 대화상자를 표시합니다. 중간자 공격이나 서버 재설치를 뜻합니다. Trust new key 를 선택하면 저장된 지문을 지우고 한 번 더 연결하며, Cancel 을 선택하면 그대로 실패합니다.

17.2.6 연결 유지와 자동 재연결

• 10초 간격으로 keep-alive를 보내고 3회 연속 응답이 없으면 끊어진 것으로 판단합니다.
• 연결이 끊기면 최대 3회까지 자동으로 재연결합니다. 대기 시간은 1초 → 2초 → 4초로 늘어나며 최대 10초를 넘지 않습니다. 이 동안 표시기는 Connecting... 이 됩니다.
• 3회를 모두 실패하면 Connection lost after max reconnect attempts 상태가 됩니다.
• 재연결에 성공하면 열려 있던 코드 편집기가 원격 언어 서버를 자동으로 다시 시작합니다.
• 앱을 다시 켤 때 저장된 원격 워크스페이스로 재연결하다가 실패하면 Could not establish connection to '<호스트>' 대화상자가 표시되고, Retry 또는 Open Folder... 를 선택할 수 있습니다.

17.2.7 연결 실패 메시지

연결에 실패하면 원인별로 아래 문구로 바꿔 보여 줍니다. 해당하지 않으면 원문이 그대로 표시됩니다.

원인	메시지
인증 실패	Authentication failed — check your SSH key, password, or that ssh-agent is running.
접속 거부	Connection refused — check the host address/port and that the SSH server (sshd) is running.
시간 초과	Connection timed out — check your network, the host address, and any firewall.
호스트 없음	Host not found — check the hostname/address.
도달 불가	Host unreachable — check the network and that the host is online.
핸드셰이크 실패	SSH handshake failed — the server may use an incompatible key exchange. (원문)

17.3 Dev Container (Docker)

17.3.1 사전 조건

로컬에 Docker가 설치되어 실행 중이어야 합니다. 그렇지 않으면 화면 오른쪽 아래에 토스트가 표시되고 동작이 중단됩니다. 상태별 메시지는 다음과 같습니다.

상태	메시지
Docker 미설치	Docker is not installed. Install Docker Desktop to use Dev Containers.
데몬이 아직 준비되지 않음	Docker Desktop is starting or not responding. Wait a moment and try again.

컨테이너 생성은 앱에 함께 포함된 @devcontainers/cli 로 수행합니다. 별도로 설치할 필요는 없습니다.

Docker가 설치되어 있지만 데몬이 동작하지 않는 상태에서 Open Folder in Container... 를 고른 모습입니다. 화면 오른쪽 아래에 위 표의 두 번째 메시지가 표시되고 동작이 거기서 멈춥니다. 모달 대화상자가 아니므로 닫지 않고 다른 작업을 계속할 수 있습니다.

17.3.2 Open Folder in Container

1. Open Folder in Container... 를 선택합니다.
2. 폴더 선택 대화상자(Select Folder to Open in Container)에서 로컬 폴더를 선택합니다.
3. PAIO가 그 폴더에서 설정 파일을 찾습니다. 찾는 위치는 <폴더>/.devcontainer/devcontainer.json 과 <폴더>/.devcontainer.json 두 곳입니다. 없으면 No Dev Container Configuration 대화상자에 This folder doesn't have a .devcontainer/devcontainer.json file. Create one first (or pick another folder). 가 표시되고 중단됩니다.
4. Select a devcontainer.json file 창이 열려 찾은 설정 파일을 한 번 더 확인합니다. 여기서 취소하면 진행이 중단됩니다. 자동 감지 안내(17.3.7)를 통해 들어온 경우에는 이 단계를 건너뜁니다.
5. 오른쪽 아래에 진행 토스트가 표시되고 컨테이너가 만들어집니다(17.3.3).
6. 완료되면 컨테이너에 연결되고 창이 다시 로드됩니다. 워크스페이스는 devcontainer 가 알려 준 폴더로, 알 수 없으면 /workspaces/<폴더 이름> 으로 들어갑니다. 터미널도 컨테이너 안에서 하나 자동으로 열립니다.
7. 상태바에 Container: <컨테이너 이름> 이 표시되면 성공입니다.

17.3.3 진행 토스트

진행 상황은 화면을 가리지 않는 오른쪽 아래 토스트로 표시됩니다. 모달 대화상자가 아니므로 그동안 다른 작업을 할 수 있습니다. 단계별 제목은 다음과 같습니다.

단계	표시되는 제목
시작	Setting up dev container
베이스 이미지 내려받기	Pulling base image
이미지 빌드	Building image
feature 설치	Installing features
컨테이너 시작	Starting container
postCreateCommand 실행	Running postCreateCommand
마무리	Finalizing
완료	Container ready
실패	Dev container failed
취소됨	Cancelled

• Show log 를 누르면 최근 50줄의 로그가 펼쳐지고 버튼이 Hide log 로 바뀝니다.
• Cancel 을 누르면 버튼이 Cancelling... 으로 바뀌고 진행 중인 작업이 중단됩니다.
• 성공하면 Container ready 를 잠깐 보여 준 뒤 토스트가 스스로 사라집니다.
• 실패하면 로그가 자동으로 펼쳐지고 전체 빌드 로그로 교체되며, Cancel 버튼이 Close 로 바뀝니다. 이어서 Dev Container Failed 대화상자에 원인이 표시됩니다.

17.3.4 Attach to Running Container

1. Attach to Running Container... 를 선택합니다.
2. Select a running container to attach 목록에서 컨테이너를 선택합니다. 항목마다 이름, 상태, 이미지가 함께 표시됩니다. 실행 중인 컨테이너만 나타나며, 하나도 없으면 No running containers found! 토스트가 표시됩니다.
3. 연결되면 창이 다시 로드되고, 컨테이너 안 폴더 선택 창이 열립니다. 터미널도 하나 자동으로 열립니다.

17.3.5 Add Dev Container Configuration Files

.devcontainer/devcontainer.json 을 새로 만드는 마법사입니다.

1. Add Dev Container Configuration Files... 를 선택합니다. 현재 워크스페이스가 원격(UNC 경로 또는 docker://)이면 Local Folder Required 대화상자에 Adding a Dev Container configuration only works on local folders. Reopen Folder Locally first. 가 표시되고 중단됩니다.
2. Add Dev Container Configuration Files — select a template (C/C++ / Rust) 목록에서 템플릿을 선택합니다.

템플릿	설명(화면 문구)	만들어지는 내용
C/C++	Ubuntu 22.04 + gcc / g++ / clang / cmake / gdb / lldb (apt install)	이름 C/C++ Dev Container, postCreateCommand 로 build-essential gcc g++ clang cmake gdb lldb pkg-config 설치
Rust	Ubuntu 22.04 + rustup / cargo / rustc (devcontainer feature)	이름 Rust Dev Container, ghcr.io/devcontainers/features/rust:1 feature
C/C++ + Rust	Ubuntu 22.04 + both of the above (paio recommended — for SDV/automotive work)	이름 C/C++/Rust Dev Container, 위 둘을 모두 포함

2단계의 템플릿 목록입니다. 위 표의 세 항목이 각각 설명 문구와 함께 나오며, 폴더를 고르는 것은 이 다음 단계입니다. 머리글은 템플릿이 세 개인 지금도 (C/C++ / Rust) 로 표시됩니다.

3. 워크스페이스가 열려 있으면 그 폴더에, 아니면 폴더 선택 대화상자에서 고른 폴더에 파일을 만듭니다.
4. 파일이 이미 있으면 Overwrite Existing Configuration? 확인을 거칩니다. Overwrite 를 선택하면 덮어씁니다.
5. 작성이 끝나면 오른쪽 아래에 컨테이너로 다시 열지 묻는 안내가 바로 표시됩니다(17.3.7).

세 템플릿 모두 베이스 이미지는 mcr.microsoft.com/devcontainers/base:ubuntu-22.04 이고 컨테이너 사용자는 vscode 입니다. PAIO는 SDV · 자동차 도메인 IDE이므로 C/C++와 Rust 템플릿만 제공합니다.

17.3.6 Rebuild Container

devcontainer.json 을 수정한 뒤 반영하는 동작입니다. Open Folder in Container... 로 들어온 경우에만 메뉴에 나타납니다.

1. Rebuild Container 를 선택하면 확인 대화상자가 표시됩니다. 내용은 기존 컨테이너가 제거되고 다시 만들어지며, 바인드 마운트된 워크스페이스 폴더 바깥의 변경(수동 설치한 패키지 등)은 사라진다는 안내입니다. Rebuild 를 눌러 진행합니다.
2. 기존 연결이 정리됩니다. 언어 서버, 터미널, 파일 감시가 함께 끊어집니다.
3. 진행 토스트가 표시됩니다. 화면은 최초 생성과 같고 제목만 Rebuilding <이름> 으로 시작합니다.
4. 완료되면 새 컨테이너에 연결되고 워크스페이스로 다시 들어갑니다. 실패하면 Rebuild Failed 대화상자가 표시됩니다.

메뉴가 보이지 않는 상태에서 실행하면 Cannot Rebuild 안내가 나타납니다. Attach로 연결한 컨테이너는 devcontainer.json 을 추적하지 않으므로 docker CLI로 직접 다시 만들어야 합니다.

17.3.7 Reopen Folder Locally와 자동 안내

Reopen Folder Locally 는 컨테이너 연결을 끊고 원래의 로컬 폴더를 다시 엽니다. 이 항목도 Open Folder in Container... 로 들어온 경우에만 나타납니다.

한편 .devcontainer 가 있는 로컬 폴더를 워크스페이스로 열면 오른쪽 아래에 안내가 자동으로 표시됩니다.

This folder contains a Dev Container configuration.
Reopen in container "<이름>"?

안내의 버튼은 다음과 같이 동작합니다.

버튼	동작
Reopen in Container	컨테이너 생성 절차로 들어갑니다. 이후 이 폴더에서는 자동 안내가 다시 표시되지 않습니다
Don't show again	이 폴더에서 다시 묻지 않습니다
Dismiss	이번만 닫습니다

오른쪽 아래에 표시되는 자동 안내입니다. 둘째 줄의 따옴표 안에는 devcontainer.json 의 이름이 들어가며, 위 표의 세 버튼이 그대로 보입니다.

이미 원격·컨테이너·WSL 모드일 때는 이 안내가 표시되지 않습니다.

17.3.8 컨테이너가 밖에서 멈춘 경우

PAIO 밖에서(예: docker stop) 컨테이너가 멈추면 연결 상태가 정리되고 상태바 표시가 사라지면서 아래 토스트가 표시됩니다. 다시 사용하려면 폴더를 컨테이너로 다시 열어야 합니다.

Disconnected — the <이름> container has stopped. Reopen the folder to reconnect.

17.4 WSL (Windows)

WSL 관련 항목은 세 가지입니다.

항목	동작
Connect to WSL	기본 배포판(없으면 목록의 첫 번째)에 연결합니다
Connect to WSL using Distro...	Select a WSL distribution to connect to 목록에서 배포판을 고릅니다. 기본 배포판에는 default 표시가 붙습니다
Open WSL Folder...	배포판 안의 폴더를 엽니다. 이미 연결되어 있으면 그 배포판을, 아니면 기본 배포판을 사용합니다

Connect to WSL using Distro... 를 고르면 열리는 목록입니다. 머리글은 Select a WSL distribution to connect to 이고, 기본 배포판에만 오른쪽에 default 표시가 붙습니다.

두 연결 항목 모두 같은 순서로 진행됩니다.

1. 배포판을 정합니다.
2. 창이 다시 로드됩니다.
3. 로드 후 배포판 안 폴더 선택 창이 자동으로 열립니다. 시작 경로는 배포판 안의 $HOME 이며, 조회에 실패하면 /home 입니다.
4. 배포판 안에서 터미널이 하나 자동으로 열립니다.
5. 폴더를 선택하면 wsl://<배포판><경로> 형태로 워크스페이스가 열리고, 상태바에 WSL: <배포판> 이 표시됩니다.

WSL이 없거나 배포판이 하나도 설치되어 있지 않으면 WSL Not Available 대화상자에 아래 안내가 표시됩니다.

WSL is not available, or no Linux distribution is installed.

Install WSL:  wsl --install
Install a distro:  wsl --install -d Ubuntu

워크스페이스 경로가 \\wsl$\... 또는 \\wsl.localhost\... 형태이면 별도 연결 절차 없이도 WSL 연결로 인식되어 상태바에 배포판 이름이 표시됩니다.

17.5 원격 폴더 선택 창 (공통)

SSH · WSL · 컨테이너 세 경우 모두 같은 폴더 선택 창을 사용합니다. 화면 위쪽에서 내려오며 머리글만 다릅니다(Open Remote Folder (SSH), Open WSL Folder (<배포판>), Open Folder in Container (<이름>)). 창의 각 요소는 다음과 같이 동작합니다.

요소	동작
눈 아이콘 (Hide dot files / Show dot files)	점으로 시작하는 항목을 숨기거나 표시합니다. 기본은 모두 표시입니다
경로 입력란	경로를 직접 입력하고 Enter 를 누르면 그 경로로 엽니다
OK	지금 보고 있는 디렉터리를 워크스페이스로 엽니다
Show Local	로컬 폴더 선택 대화상자를 열어 로컬 워크스페이스로 되돌아갑니다
..	상위 디렉터리로 이동합니다. 한 번만 클릭하면 됩니다
폴더 항목	한 번 클릭으로 그 폴더로 들어갑니다

목록에는 폴더만 표시됩니다. 파일은 나타나지 않습니다. 경로를 읽지 못하면 Failed to browse: <원인> 이 표시됩니다. Esc 또는 바깥 클릭으로 닫습니다.

WSL로 열렸을 때의 모습입니다. 머리글이 Open WSL Folder (<배포판>) 으로 바뀌고, 오른쪽 끝에 눈 아이콘이 있습니다. 시작 경로는 배포판 안의 $HOME 이며, 목록 맨 위의 .. 로 상위로 올라갑니다. 파일 없이 폴더만 보이는 것도 확인할 수 있습니다.

처음 표시되는 위치는 경우마다 다릅니다.

경우	시작 경로
SSH	/home
WSL	배포판 안의 $HOME. 조회에 실패하면 /home
컨테이너	컨테이너의 작업 디렉터리(workdir). 없으면 /

연결이 없는 상태에서 폴더 열기를 선택하면 안내 대화상자가 표시되고 중단됩니다. SSH는 Not Connected 에 Connect to an SSH host first. 가, 컨테이너는 Not Attached to a Container 에 Attach to a container first. 가 표시됩니다.

17.6 원격 언어 서버와 빌드 도구

17.6.1 자동 배포

원격 · 컨테이너 · WSL 워크스페이스에서 C/C++/Rust 파일을 열거나 빌드하면, PAIO가 함께 배포한 Linux x64 바이너리를 원격 환경으로 업로드해 그곳에서 실행합니다. 원격에 직접 설치할 필요가 없습니다. 배포되는 도구와 원격 설치 위치는 다음과 같습니다.

배포되는 도구	원격 설치 위치
clangd	~/.paio-server/bin/clangd
rust-analyzer	~/.paio-server/bin/rust-analyzer
CMake	~/.paio-server/cmake/
gcc / g++	~/.paio-server/gcc/
Rust 툴체인(cargo · rustc)	~/.paio-server/rust/

• 같은 버전이 이미 올라가 있으면 다시 올리지 않습니다.
• 언어 서버 업로드 진행 상황은 오른쪽 아래 배너로 표시됩니다. 진행 중에는 Deploying clangd to remote… (42%) 가, 끝나면 Remote LSP ready 가 잠깐 표시되고 사라집니다. 실패하면 Remote LSP: <도구> deploy failed (<원인>) 이 몇 초간 남습니다.
• CMake · gcc · Rust 배포에 실패하면 원격 시스템의 cmake / gcc / cargo 로 넘어갑니다. 그것도 없으면 빌드 출력에 설치 안내가 붙습니다(16.2.4 참고).

17.6.2 지원 범위

번들 바이너리는 glibc 기반 Linux x86_64 용입니다. 다음 환경은 지원되지 않습니다.

조건	결과
Linux x86_64가 아닌 환경 (arm64, macOS 등)	배포 거부
musl 계열 배포판 (Alpine 등)	배포 거부

SSH 원격이 지원 범위 밖이면 워크스페이스마다 한 번씩 아래 경고 토스트가 표시됩니다.

This remote server is not a supported environment (e.g. arm64, Alpine/musl, or non-Linux), so code intelligence (completion / diagnostics) is unavailable. PAIO bundles language servers for glibc Linux x64 remotes only.

WSL 배포판이 지원 범위 밖이면 언어 서버 배포가 WSL distro is not x86_64 — only Linux x64 is supported 또는 WSL distro uses musl (Alpine) — only glibc is supported 로 중단됩니다. CMake · gcc · Rust 툴체인 배포도 같은 이유로 중단되며 문구만 조금 짧습니다.

컨테이너 안에서 Rust를 사용하려면 cargo가 있어야 합니다. PAIO는 먼저 자신의 Rust 툴체인을 배포해 보고, 그래도 없으면 컨테이너에 이미 설치된 cargo를 찾습니다. 둘 중 하나라도 있으면 rust-analyzer가 시작됩니다.

셋 다 없으면 rust-analyzer는 시작되지 않습니다. 화면에는 아무 안내도 나오지 않고 상태만 stopped 로 남으므로, 컨테이너에서 Rust 자동 완성이 조용히 동작하지 않으면 컨테이너 안 cargo 설치 여부를 먼저 확인하는 것이 좋습니다(16.1.3 참고).

17.7 연결 종료

Close Remote Connection 을 선택하면 연결을 끊고 열려 있던 원격 워크스페이스를 닫은 뒤 창을 다시 로드합니다. 로컬 상태로 돌아옵니다. 세 방식 모두 저장된 원격 워크스페이스 기억을 함께 지우므로 다음 실행 시 자동으로 다시 연결하지 않습니다. 워크스페이스를 닫는 과정에서 더티 상태인 편집기 탭은 먼저 저장됩니다.

17.8 제한 사항과 주의점

원격 개발을 사용하기 전에 알아 두면 좋은 제한 사항입니다.

• 연결하거나 끊을 때마다 창이 다시 로드됩니다. 저장하지 않은 편집은 미리 저장하는 것이 좋습니다.
• 포트 포워딩은 제공되지 않습니다.
• 원격에서 파일이 바뀐 것이 화면에 늦게 반영될 수 있습니다. 환경에 따라 감지 방식이 달라지기 때문입니다. 반영이 늦으면 탐색기 상단의 Refresh Explorer 버튼을 사용합니다.
• PAIO가 PATH 앞에 붙이는 번들 툴체인 경로는 호스트 경로이므로 원격 터미널에서는 쓸모가 없습니다. SSH 셸에는 아예 적용되지 않습니다(16.3.3 참고). 원격에서 사용하는 빌드 도구는 17.6의 자동 배포 경로를 따릅니다.
• 원격 빌드는 120초에서 강제 종료됩니다.
• 컨테이너 기능은 로컬 Docker에 의존합니다. Docker Desktop이 실행 중이 아니면 어떤 컨테이너 항목도 진행되지 않습니다.
• 한 창은 한 번에 하나의 원격 모드만 가집니다. SSH · 컨테이너 · WSL을 동시에 연결할 수 없습니다.