VS Code Remote Agent Sessions 어떻게 쓰나요? 2026 원격 맥 배포

Remote Agent Sessions를 검토할 때는 다음 상태를 하나로 묶지 마십시오.

• 접속 가능: SSH 또는 인증된 Dev Tunnel이 원격 맥에 연결됩니다.
• 작업 폴더 사용 가능: Agents window가 호스트를 인식하고 지정한 저장소를 엽니다.
• 개발 도구 사용 가능: 같은 계정의 로그인 셸에서 Xcode 명령, 의존성 도구, 프로젝트 스크립트를 실행할 수 있습니다.

첫 번째 상태만 통과하고 세 번째 상태를 통과하지 못하는 경우가 흔합니다. 원격 맥은 켜져 있고 네트워크에서 접근 가능해야 합니다. macOS에서는 Apple Remote Login 설정 안내에 따라 원격 로그인을 켜고, 시험용 계정과 저장소를 따로 준비하십시오.

최소 조건은 독립 계정, 접근 가능한 저장소, 문제가 생겼을 때 되돌릴 수 있는 시험 환경입니다. 공유 계정과 실제 출시 인증서가 있는 작업 폴더로 첫 검증을 시작하지 않는 편이 좋습니다.

배포 전 판정 체크리스트

아래 항목 중 하나라도 확인하지 못했다면 실제 저장소나 출시 자산으로 진행하지 마십시오.

• [ ] 원격 맥이 켜져 있고 네트워크에서 접근 가능합니다.
• [ ] SSH 또는 인증된 Dev Tunnel 중 하나의 접근 경로가 정해졌습니다.
• [ ] 시험용 사용자 계정과 작업 폴더가 분리되어 있습니다.
• [ ] Agents window에서 호스트와 작업 폴더를 선택할 수 있습니다.
• [ ] Agent가 사용하는 사용자, 셸, 현재 폴더를 확인했습니다.
• [ ] xcodebuild와 개발자 도구 경로를 같은 계정에서 확인했습니다.
• [ ] 서명 인증서와 출시 토큰이 시험 단계에서 차단되어 있습니다.
• [ ] 원격 맥 재시작 뒤 새 세션을 여는 절차를 기록했습니다.

판정은 다음처럼 단순화할 수 있습니다.

• 모든 항목을 확인함: 격리된 실제 프로젝트로 다음 단계에 진행합니다.
• 접속과 작업 폴더만 확인함: 코드 읽기와 제한된 수정만 허용합니다.
• 권한 또는 복구 항목을 확인하지 못함: 운영 연결을 보류하고 시험 환경을 다시 만듭니다.

SSH는 네트워크 주소, 포트 접근, 키 또는 계정 인증을 운영자가 직접 관리하는 방식입니다. 고정된 사설망이나 관리 가능한 방화벽 정책이 있다면 원격 관리 경로를 설명하기 쉽습니다. VS Code의 Remote SSH 구성 문서를 기준으로 클라이언트와 원격 호스트의 요구 조건을 확인하십시오.

Dev Tunnel은 주소와 네트워크 입구를 다르게 관리할 수 있지만, 계정 인증과 터널의 실행 상태가 핵심입니다. Dev Tunnel 공식 문서의 절차에 맞춰 인증된 접근만 사용해야 합니다. 익명 접근은 공유 맥이나 장기 실행 노드에서 허용할 수 있는 기본값으로 보지 마십시오.

연결 검증 순서

1. 원격 맥의 전원과 네트워크 연결 상태를 확인합니다.
2. SSH라면 Remote Login, 사용자 계정, 인증 방식을 점검합니다.
3. Dev Tunnel이라면 계정 인증과 터널 실행 상태를 확인합니다.
4. VS Code에서 Agents window를 열고 대상 호스트를 선택합니다.
5. 저장소가 아닌 임시 작업 폴더를 먼저 엽니다.
6. 연결이 끊겼을 때 화면에 표시되는 상태와 재연결 동작을 기록합니다.

이때 성공 기준은 “창이 열렸다”가 아닙니다. 호스트 이름, 사용자 이름, 현재 폴더, 셸 종류를 확인해야 합니다. 접속은 되지만 작업 폴더가 없거나 로그인 셸과 비로그인 셸의 환경 변수가 다른 경우가 있습니다.

연결 방식 선택 조건

• 고정된 네트워크 입구와 운영자가 관리하는 인증 키가 필요하면 SSH를 우선 검토합니다.
• 방화벽과 주소 관리 부담을 줄이고 계정 기반 접근을 사용하려면 인증된 Dev Tunnel을 검토합니다.
• 익명 접근만 가능한 경우에는 두 방식을 모두 운영 승인 대상에서 제외합니다.
• 여러 사용자가 같은 맥에 접근한다면 접근 기록과 회수 절차를 먼저 확정합니다.
• 연결은 되지만 Agents window에서 작업 폴더를 열지 못하면 Xcode 검증으로 넘어가지 않습니다.

연결 뒤 Agent Host가 원격 호스트에서 명령을 실행하는 구조를 확인해야 합니다. Agent가 사용하는 계정과 네가 직접 연 SSH 셸의 계정이 다르면 결과도 달라집니다.

다음 순서로 작은 명령부터 실행하십시오.

• 현재 사용자와 작업 폴더를 확인합니다.
• 셸 이름과 주요 환경 변수를 출력합니다.
• 저장소 파일을 읽게 합니다.
• 테스트용 파일 한 개만 수정하게 합니다.
• 패키지 관리자와 프로젝트 의존성 상태를 확인합니다.
• 되돌릴 수 있는 최소 테스트 명령을 실행합니다.

로컬 터미널에서는 성공하지만 Agent 세션에서 실패한다면 다음 항목을 비교하십시오.

• 로그인 셸과 비로그인 셸의 초기화 파일
• PATH와 개발 도구 경로
• 작업 폴더의 소유자와 읽기·쓰기 권한
• 저장소 인증 방식
• Agent 명령에 대한 승인 상태
• 터미널에서만 설정한 임시 환경 변수

명령을 자동 승인하면 속도는 빨라질 수 있지만, 원격 접속 경로와 결합될 때 파일 삭제, 비밀값 읽기, 의존성 변경의 범위가 커집니다. VS Code Agent 승인 안내와 보안 문서의 경고를 확인한 뒤 저장소별로 승인 범위를 정하십시오.

주의: 원격 세션이 연결되었다는 사실은 Agent가 해당 맥에서 안전하게 모든 명령을 실행해도 된다는 뜻이 아닙니다. 승인 범위를 넓힐 때마다 변경 기록과 즉시 중단할 방법을 함께 남기십시오.

원격 Agent 세션에서 Xcode를 사용할 때는 “Xcode가 설치되어 있다”는 표현을 피해야 합니다. 먼저 활동 중인 개발자 디렉터리와 명령줄 도구를 같은 계정에서 확인하십시오. Apple의 Xcode 명령줄 도구 참고 문서와 빌드 설정 참고 문서를 기준으로 프로젝트에 필요한 항목을 대조합니다.

검증 결과는 다음 네 등급으로 나누면 됩니다.

1. 명령 실행: xcodebuild를 호출할 수 있고 개발자 디렉터리가 올바릅니다.
2. 비그래픽 프로젝트 검사: 실제 프로젝트의 의존성 확인과 빌드 설정 조회가 됩니다.
3. 빌드와 테스트: 격리된 프로젝트에서 빌드와 명령줄 테스트가 완료됩니다.
4. 서명과 출시: 인증서, 프로비저닝 프로파일, 팀 식별자, 출시 절차까지 별도 승인으로 통과합니다.

첫 번째 등급은 네 번째 등급을 의미하지 않습니다. Simulator는 그래픽 세션과 런타임 상태의 영향을 받습니다. 서명은 인증서와 프로파일의 접근 범위를 추가로 요구합니다. 무인 출시 역시 토큰과 중단 절차가 필요합니다.

따라서 Agent에는 먼저 읽기, 제한된 수정, 비그래픽 검사 권한만 부여하십시오. 그래픽 세션, 서명 자산, 생산 출시가 필요한 작업은 독립된 승인 흐름으로 옮기십시오.

Xcode 결과에 따른 다음 조치

• xcodebuild 호출만 성공하면 도구 경로 확인 단계로 기록합니다.
• 실제 프로젝트의 설정 조회까지 성공하면 비그래픽 검사 단계로 올립니다.
• 빌드와 명령줄 테스트까지 성공하면 격리된 개발 작업을 허용합니다.
• Simulator, 서명, 출시까지 필요하면 별도 승인과 추가 검증 없이는 운영에 연결하지 않습니다.

개인 시험 노드와 공유 노드는 같은 정책을 적용하면 안 됩니다.

개인 노드에서는 작업 폴더를 별도로 만들고, Agent가 접근할 저장소를 명시하십시오. 공유 노드에서는 사용자 계정, 저장소, 작업 트리, 임시 빌드 디렉터리를 분리합니다. 장기 자격 증명은 환경 변수에 무조건 넣지 말고, Agent가 읽어도 되는 값과 사람이 직접 승인해야 하는 값을 구분하십시오.

특히 다음 값은 기본 접근 대상에서 제외하는 것이 좋습니다.

• 코드 서명 인증서와 개인 키
• 출시 토큰
• 조직용 저장소의 장기 접근 토큰
• 다른 팀의 저장소 경로
• 운영 서버 접속 정보

자동 승인과 원격 접속을 동시에 사용하는 경우에는 허용 명령, 대상 폴더, 중단 조건을 문서로 남기십시오. 변경 기록이 없으면 사고 뒤에 어떤 권한이 원인이었는지 확인하기 어렵습니다.

장기 실행을 고려한다면 정상 연결보다 실패 상태를 먼저 시험해야 합니다.

• VS Code 클라이언트를 종료합니다.
• 클라이언트의 네트워크를 끊었다가 복구합니다.
• Dev Tunnel을 중지했다가 다시 인증합니다.
• 원격 맥을 재시작합니다.
• Remote Login 또는 Agent Host가 다시 준비되는지 확인합니다.
• 작업 폴더와 셸 환경이 이전과 같은지 비교합니다.
• 중단된 명령의 결과와 저장되지 않은 변경 내용을 확인합니다.

원격 맥 재시작 뒤 이전 Agent 세션이 그대로 이어진다고 가정하면 안 됩니다. 새 세션을 열어야 할 수 있고, 실행 중이던 명령이 중단되었을 수도 있습니다. 복구 시험에서는 성공 여부뿐 아니라 복구에 필요한 수동 조치, 확인해야 할 로그, 작업 재개 기준을 기록하십시오.

운영 투입 판정

다음 기준으로 결론을 세 단계로 나누십시오.

• 계속 시험: 접속, 작업 폴더, 셸 환경, 최소 Xcode 명령, 재연결 절차가 모두 확인된 경우입니다.
• 제한 사용: 코드 읽기와 제한된 수정은 가능하지만 Simulator, 서명 또는 재시작 복구가 불안정한 경우입니다.
• 운영 투입 보류: 인증서가 분리되지 않았거나, 승인 기록이 없거나, 원격 맥 재시작 뒤 복구 절차가 재현되지 않는 경우입니다.

실제 원격 맥이 필요하다면 CALMVPS의 맥 임대 구성을 확인한 뒤 짧은 시험 기간으로 별도 노드를 만들 수 있습니다. 연결 방식과 지역별 접근 조건은 CALMVPS의 원격 맥 신청 안내에서 현재 제공 범위를 확인하십시오. 다만 서비스 선택 전에 위의 명령 실행, Xcode, 권한, 복구 검증을 먼저 수행해야 합니다.

VS Code Remote Agent Sessions는 맥 호스트에 연결할 수 있나요?

가능합니다. 원격 맥이 켜져 있고 네트워크에서 접근 가능해야 하며, SSH 또는 계정 인증이 끝난 Dev Tunnel을 사용해야 합니다. Agents window에서 호스트와 작업 폴더를 선택한 뒤 세션이 열리는지 확인하십시오. 연결 성공만으로 Xcode 빌드나 서명 작업까지 보장되지는 않습니다.

원격 Agent 세션에서 xcodebuild를 바로 실행해도 되나요?

셸에서 xcodebuild 명령을 호출할 수 있는지는 같은 계정의 개발자 도구 경로와 프로젝트 상태를 먼저 확인해야 판단할 수 있습니다. 명령이 실행되는 것과 빌드가 성공하는 것은 다릅니다. 실제 프로젝트에서 의존성 확인, 비그래픽 빌드, 테스트를 각각 수행하고 서명과 출시 작업은 별도 승인 단계로 분리하십시오.

SSH와 Dev Tunnel 중 원격 맥 연결에는 무엇이 더 적합한가요?

고정된 네트워크 입구와 운영자가 관리하는 키 인증이 필요하면 SSH가 더 단순합니다. 방화벽이나 주소 관리 부담을 줄이고 계정 기반 접근을 사용하려면 인증된 Dev Tunnel을 검토할 수 있습니다. 익명 터널은 공유 개발 노드의 승인 가능한 방식으로 보지 말고, 두 방식 모두 접근 기록과 중단 절차를 준비하십시오.

원격 맥이 다시 시작되면 Agent 세션은 어떻게 복구하나요?

재시작 뒤에는 이전 세션이 자동으로 계속된다고 가정하지 마십시오. 원격 로그인이 다시 가능한지, Agent Host가 재기동되는지, 작업 폴더와 셸 환경이 같은지 순서대로 확인해야 합니다. 연결이 복구되지 않으면 새 세션을 열고 중단된 명령의 결과와 저장되지 않은 변경 내용을 먼저 점검한 뒤 작업을 재개하십시오.

공유 맥에서 Agent의 저장소와 자격 증명을 어떻게 나누나요?

사용자 계정과 작업 폴더를 분리하고, 저장소별 작업 트리와 최소 권한 승인 정책을 적용하십시오. 서명 인증서, 출시 토큰, 장기 비밀값은 Agent가 기본적으로 읽지 못하는 위치에 두는 편이 안전합니다. 자동 승인 모드와 원격 접속을 함께 켜야 한다면 변경 기록, 중단 조건, 회수 절차를 먼저 문서화하십시오.

현재 방식이 개인 PC나 리눅스 서버에만 의존한다면 Xcode 도구 체인을 직접 재현하기 어렵고, 개발용 맥을 계속 켜 두는 관리 부담도 생깁니다. 공유 맥 한 대에 권한과 서명 자산을 몰아넣으면 계정 분리와 복구 검증도 약해집니다. 이런 조건에서는 CALMVPS로 짧은 기간 원격 맥을 임대해 격리 시험 노드를 만들고, 실제 Agent 작업 기록을 확인한 뒤 장기 사용 여부를 정하는 편이 안전합니다. 장기간 고정 부하가 있거나 물리 장치와 직접 연결해야 한다면 자가 보유 맥이 더 적합할 수 있습니다.