노트북 터미널에서 돌리는 Claude Code 세션은 그 노트북 사정에 그대로 묶입니다. 한 저장소에 세션을 두 개 띄우면 작업 폴더를 같이 쓰니 같은 파일이나 포트를 두고 부딪힐 수 있습니다. 권한도 내 계정 그대로이고 노트북이 잠들거나 와이파이가 끊기면 세션도 멈춥니다. 클라우드 세션은 이 세 가지 제약을 풀려고 나온 기능입니다. 클라우드 세션이 어떻게 생겼고 어떤 작업을 클라우드로 보내면 좋은지 정리합니다.

한눈에 보기

  • 클라우드 세션은 작업마다 새 가상 머신(VM)을 띄우고, 저장소를 새 브랜치로 복제해 일을 시킵니다. 결과는 브랜치로 남고 원하면 풀 리퀘스트로 만듭니다.
  • Pro, Max, Team, Enterprise 요금제에 추가 비용 없이 포함됩니다. 머신 비용은 따로 받지 않고 Claude Code의 사용 한도를 함께 씁니다.
  • 작업끼리 서로 간섭하지 않으니 여러 작업을 동시에 돌리거나 테스트를 수십 번 반복하는 일에 잘 맞습니다.
  • 첫 세션이 실패하는 가장 흔한 원인은 GitHub 연결입니다. 로그인과 GitHub App 설치는 서로 다른 권한입니다.

원문은 어떤 글인가

Addy Osmani가 2026년 10월 6일에 쓴 실전 안내서이고 읽는 데 18분쯤 걸립니다. 작은 예제 저장소에 실제 클라우드 세션 네 개를 돌려 대화 기록과 변경 내용, 걸린 시간을 그대로 보여 줍니다. 원문은 노트북 터미널에서 Claude Code를 쓰는 사람을 독자로 놓고 씁니다. 원문: Claude Code in the cloud

세 작업을 세 머신에서 동시에

예제 저장소 tidepool은 가상의 항구 세 곳의 조수를 예측하는 작은 Node API입니다. 문제가 세 개 있었습니다. 네 번에 한 번꼴로 실패하는 테스트, 코드와 맞지 않는 API 문서, 문자열을 이어 붙여 만드는 로그입니다. 저자는 16초 안에 세션 세 개를 띄워 하나씩 맡겼습니다. 아래 그림은 세 세션의 실제 진행 시간입니다.

세 클라우드 세션의 실제 타임라인: VM 1은 불안정한 테스트 수정, VM 2는 API 문서 갱신, VM 3은 구조화 로그 작업이며 모두 87초 안에 끝남

그림 1. 가로축은 첫 세션을 띄운 뒤 흐른 초입니다. 빗금 구간은 데모용으로 예제 저장소를 새로 만드는 준비 단계이고 평소에는 GitHub 복제가 이 자리를 대신합니다. 점 하나가 도구 호출 한 번입니다. 출처: 원문 .

세 세션은 61초에서 72초 사이를 돌았고 첫 세션을 띄운 지 87초 만에 모두 끝났습니다.

  • 불안정한 테스트: 원인은 TtlCache.get 의 경쟁 상태였습니다. 값을 읽어 오는 도중 같은 키로 요청이 또 들어오면 로더가 한 번 더 불렸습니다. Claude는 진행 중인 promise를 캐시에 넣도록 고치고 npm test 를 40번 연달아 돌려 실패 0회를 확인했습니다.
  • API 문서: 서버를 띄워 모든 엔드포인트에 curl을 보내 보고 문서가 틀린 곳 다섯 군데를 찾았습니다.
  • 로그: JSON 로그로 바꾸고 테스트 5개를 더했습니다. 그런데 테스트 하나가 실패했고 따라가 보니 첫 세션이 고치던 그 경쟁 상태였습니다. Claude는 맡은 범위 밖이라 캐시를 건드리지 않고, 요약에 테스트가 깨끗하지 않다고만 적었습니다.

세 세션이 저장소 사본과 프로세스, 브랜치를 따로 가진 덕에 문서 세션과 로그 세션은 각자 API 서버를 띄우고도 충돌하지 않았습니다. 대신 로그 세션 쪽에서는 옆 세션의 캐시 수정이 보이지 않았습니다. 병렬로 나눌 때는 파일 경계를 기준으로 자르고, 다른 세션이 이미 고치는 문제가 보고서에 올라올 수 있다고 생각해 두면 됩니다.

클라우드 세션은 어떻게 생겼나

다음 그림은 세션 하나의 구성입니다. 점선 상자가 VM이고 GitHub 토큰과 네트워크 정책은 그 바깥에 있습니다.

클라우드 세션 구성도: 왼쪽에 시작 경로, 가운데 VM 안에 Claude Code·저장소 복제본·환경 설정, 오른쪽 VM 밖에 GitHub 프록시와 보안 프록시

그림 2. 왼쪽 START OR CHECK FROM은 세션을 시작하는 곳이고 그중 브라우저·모바일 앱·데스크톱에서는 진행도 볼 수 있습니다. 가운데 FRESH VM PER SESSION은 세션마다 새로 뜨는 VM, 오른쪽 OUTSIDE THE VM은 토큰과 네트워크를 맡는 프록시입니다. 출처: 원문 .

원문이 일하는 방식이 달라진다고 짚는 점은 네 가지입니다.

항목클라우드 세션에서는
머신작업마다 새 VM. 세션끼리 파일과 포트를 공유하지 않음
GitHub 토큰VM에 들어가지 않음. 세션은 자기 작업 브랜치에만 푸시하는 짧은 수명의 자격 증명을 받음
설정저장소의 CLAUDE.md, 규칙, 스킬은 따라오고 내 ~/.claude 는 노트북에 남음
쉬는 VM회수됨. 다시 열면 대화는 복원되지만 머신은 새것이니 남길 작업은 커밋

로컬 세션이 사라지는 것은 아닙니다. 작업에 내 머신에만 있는 것이 필요하면 로컬이 맞습니다. 실제 데이터가 든 로컬 데이터베이스나 VPN 너머 서비스, GPU, 휴대폰 시뮬레이터가 그런 예입니다. 고칠 때마다 몇 초 안에 내 브라우저에서 화면을 확인해야 하는 작업도 로컬이 편합니다. Zero Data Retention을 쓰는 조직은 클라우드 세션이 아예 꺼지므로 로컬만 쓸 수 있습니다.

클라우드에 잘 맞는 작업

원문은 일곱 가지 사례를 듭니다. 실무에서 바로 쓸 만한 것을 추리면 이렇습니다.

  • 작은 수정 여러 개를 병렬로: claude --cloud "작업 설명" 을 작업 수만큼 실행합니다. 이 명령은 GitHub 원격의 현재 브랜치를 복제하므로 로컬 커밋을 먼저 푸시해야 합니다. 작업 설명에는 무엇이 고장 났고, 어떤 상태가 되면 끝이고 그걸 어떤 명령으로 보여 줄지 적습니다.
  • 수정을 증명하게 하기: 클라우드 VM은 내 CPU를 쓰지 않으니 증명을 넉넉히 요구할 수 있습니다. 앞의 테스트 세션은 한 번의 명령으로 전체 테스트를 40번 돌렸습니다.

클라우드 세션 화면에서 src/cache.js를 고친 뒤 npm test를 40번 반복해 runs=40 fails=0이 출력된 모습

그림 3. 아래쪽 runs=40 fails=0 이 40번 실행에 실패 0회라는 뜻이고 Root cause 문단이 원인 설명입니다. 출처: 원문 .

포그라운드 명령은 기본 2분(최대 10분)이 지나면 시간 초과되고 그 뒤로 최대 30분 더 백그라운드에서 돕니다. 환경 변수 BASH_DEFAULT_TIMEOUT_MS, BASH_MAX_TIMEOUT_MS 로 기본값을 늘릴 수 있습니다.

  • 계획은 책상에서, 실행은 클라우드에서: 큰 변경은 대화가 싼 로컬에서 먼저 계획을 맞춥니다. 아래 흐름처럼 진행합니다.
flowchart LR
  A["로컬 plan 모드<br/>계획 합의"] -->|"커밋·푸시"| B["claude --cloud<br/>계획 실행"]
  B -->|"브랜치 푸시"| C["claude --teleport<br/>터미널로 가져오기"]
  C --> D["손으로 마무리"]

claude --teleport 를 쓰면 클라우드 세션의 브랜치와 대화가 통째로 내 터미널로 넘어옵니다. 브랜치는 이미 푸시돼 있어야 하고 작업 트리가 깨끗해야 합니다. 커밋 안 한 변경이 있으면 stash할지 묻습니다.

  • 믿기 어려운 코드 돌리기: 외부 기여자의 PR이나 새 의존성의 설치 스크립트를 노트북에서 돌리면, 그 코드 옆에 SSH 키와 클라우드 CLI 로그인이 같이 있습니다. 클라우드 세션의 일회용 VM에는 그런 게 없고, 네트워크도 None까지 좁힐 수 있습니다. 다만 None으로 막아도 Anthropic API 요청은 나가니 그 경로로 데이터가 VM 밖에 나갈 수 있고, 세션이 자기 브랜치로 푸시하는 것도 막히지 않습니다.

이 밖에 휴대폰에서 세션을 시작하거나 지켜보기, CI 실패와 리뷰 댓글을 자동으로 고치는 Auto-fix, 일정이나 GitHub 이벤트로 세션을 시작하는 routine도 소개합니다.

GitHub 연결과 환경 준비

GitHub 쪽에서 필요한 권한은 두 가지입니다. GitHub 로그인은 내가 누구인지만 알려 줍니다. 어느 비공개 저장소를 볼 수 있는지는 그 저장소를 가진 계정이나 조직에 Claude GitHub App을 설치해야 정해집니다. 비공개 저장소가 목록에 없을 때는 아래 순서로 확인합니다.

flowchart TD
  A["비공개 저장소가<br/>목록에 없음"] --> D{"소유 계정·조직에<br/>App이 설치됐나"}
  D -->|"아니오"| E["그 계정·조직에 App 설치<br/>조직은 소유자 승인"]
  D -->|"예"| F["App 저장소 접근 범위와<br/>SAML SSO 승인 확인"]

공개 저장소는 로그인만으로 됩니다. 브라우저로 연결할 때 조직의 비공개 저장소는 App이 그 조직에 설치돼야 보입니다. gh CLI를 쓰고 있다면 Claude Code 안에서 /web-setup 으로 gh 토큰을 넘기는 길도 있습니다. 이때는 App 없이도 그 토큰이 닿는 저장소에 접근하지만 Team과 Enterprise 요금제에서는 소유자가 Quick setup을 먼저 켜 둬야 합니다. Auto-fix, GitHub 이벤트로 시작하는 routine, 프로젝트는 어느 쪽이든 App이 있어야 동작합니다.

연결 다음은 환경입니다. 세션이 스스로 테스트를 돌릴 수 있어야 검증된 결과를 돌려받습니다. JavaScript, Python, Go, Rust 저장소 대부분은 기본 환경(Default)으로 충분합니다. 시스템 패키지는 setup script에 넣는데 root로 실행되고 exit 0으로 끝나야 하며 5분 안쪽에 끝나야 캐시됩니다. npm install 같은 프로젝트 준비는 .claude/settings.json 의 SessionStart 훅에 두면 로컬과 클라우드에서 똑같이 돌아갑니다. 통합 테스트 실행법 같은 지식은 CLAUDE.md에 적어야 합니다. 내 ~/.claude 는 VM에 가지 않기 때문입니다.

인사이트

여기서부터는 원문이 아니라 이 블로그의 해석입니다.

  1. 로그 세션이 남의 범위인 캐시 버그를 발견하고도 고치지 않고 보고만 한 장면이 인상적입니다. 데이터 파이프라인이나 에이전트 작업을 병렬로 나눌 때도 각 작업의 범위를 프롬프트에 명확히 적고, 범위 밖 문제는 보고만 하라고 정해 두면 브랜치 병합이 훨씬 수월해집니다.

  2. 클라우드 세션에서 쓸 만한 결과가 오느냐는 증명할 명령을 적었느냐에 크게 달려 있어 보입니다. 데이터 작업이라면 “쿼리를 고쳐라"보다 “고친 쿼리로 검증 SQL을 돌려 행 수와 합계가 기준과 같은지 보여라"처럼 끝난 상태를 숫자로 확인하게 쓰는 편이 리뷰 시간을 줄입니다.

  3. 개인 설정이 VM에 따라가지 않는다는 점은 팀에 오히려 좋은 압력입니다. 테스트 명령과 스킬, MCP 설정을 저장소에 올려야 클라우드 세션이 일을 할 수 있으니, 사람 신입에게도 필요한 문서가 자연스럽게 저장소에 쌓입니다.

바로 해볼 것

  • claude.ai/code에서 GitHub를 연결하고 자주 쓰는 비공개 저장소의 소유 계정이나 조직에 Claude GitHub App이 설치됐는지 확인합니다.
  • 백로그에서 서로 다른 파일을 건드리는 작은 작업 두 개를 골라, 각각 증명 명령을 붙여 claude --cloud 로 동시에 맡겨 봅니다. 실행 전에 로컬 커밋을 푸시합니다.
  • 저장소 CLAUDE.md에 테스트 실행 명령이 적혀 있는지 봅니다. 없다면 한 줄 추가합니다.

원문: Claude Code in the cloud: a field guide to cloud sessions