샌드박스에서 Git 사용

샌드박스에서 Git 사용 (Use Git with sandboxes)

직접, 클론, 호스트 워크트리 모드로 Git 저장소를 작업하는 방법과 커밋 서명을 알아볼게요.

출처: 문서

본문

이 워크스페이스 모드는 로컬 샌드박스에 적용돼요. 클라우드 샌드박스에서는 파일을 전송하거나 원격 저장소를 클론하세요. 샌드박스 파일시스템을 환경 간에 복사하려면 샌드박스 이동을 참고하세요. 호스트 마운트와 클론 모드 볼륨은 그 스냅샷에 포함되지 않아요.

샌드박스는 Git 저장소 작업에 세 가지 접근을 지원해요. 올바른 선택은 브랜치 격리를 원하는지와 작업을 병렬로 실행할 계획인지에 달려 있어요:

직접 모드 클론 모드(--clone) 호스트 워크트리
브랜치 관리 당신, 호스트에서 에이전트, 클론 안에서 당신, 호스트에서
호스트에서 보이는 변경 즉시 fetch 또는 에이전트 push 후 즉시
에이전트가 Git 사용 가능 예 예 아니요
병렬성 아니요 여러 에이전트, 샌드박스 하나 병렬 작업당 샌드박스 하나
생성 시 고정 아니요 예 —

직접 모드 (Direct mode)

가장 간단한 접근이에요. 샌드박스가 호스트 작업 트리를 직접 마운트해요 — 에이전트가 파일을 그 자리에서 편집하고 변경이 즉시 나타나요. 브랜치는 스스로 관리하세요.

  1. 작업할 브랜치를 체크아웃하세요:

    $ git checkout -b feat/my-feature

  2. 샌드박스를 시작하세요. 특별한 플래그가 필요 없어요:

    $ sbx run claude

  3. 에이전트가 작업 트리의 파일을 편집해요. 평소처럼 diff를 검토하고, 스테이징하고, 커밋하세요:

    $ git diff
$ git add -p
$ git commit
$ git push -u origin feat/my-feature

샌드박스가 작업 트리를 마운트하므로 호스트에서 브랜치를 전환하면 에이전트가 보는 것도 바뀌어요. 이 때문에 직접 모드는 에이전트와 턴바이턴으로 협업하는 집중 단일 브랜치 작업에 잘 맞아요.

클론 모드 (Clone mode)

클론 모드에서 sbx는 샌드박스 안에 별도 Git 클론을 만들어요. 에이전트는 호스트 작업 트리 대신 이 클론을 편집해요. 브랜치를 fetch하거나 에이전트가 원격으로 푸시할 때까지 그 변경은 샌드박스 안에 남아요. 호스트 저장소는 /run/sandbox/source에서도 읽기 전용으로 사용할 수 있어요. 샌드박스 클론은 호스트 체크아웃에 연결된 Git 워크트리가 아니에요.

하나의 클론 모드 샌드박스가 병렬 작업을 위해 여러 브랜치와 워크트리를 담을 수 있어요. --clone 플래그가 클론을 만들지만, 작업을 서로 분리하지는 않아요. 병렬 작업을 격리하려면 에이전트 도구에 작업마다 별도 브랜치나 워크트리를 만들라고 지시하세요.

[!NOTE] --clone은 생성 시 플래그이며 기존 샌드박스에서 바꿀 수 없어요. 샌드박스를 클론 모드에서 직접 모드로 바꾸려면 제거하고 다시 만드세요. 같은 저장소에 두 모드를 모두 실행하려면 고유한 이름으로 별도 샌드박스를 만드세요.

샌드박스 remote 동작 (Sandbox remote behavior)

CLI는 origin, upstream 같은 호스트 저장소의 Git remote를 샌드박스 안의 클론으로 복사해요. file:// URL과 파일시스템 경로 같은 로컬 경로 remote는 샌드박스 안에서 도달할 수 없으므로 복사되지 않아요.

샌드박스 안의 클론을 노출하는 Git 데몬은 샌드박스의 일부로 실행돼요. 샌드박스가 실행 중일 때만 도달할 수 있어요:

  • sbx stop은 데몬을 종료해요. 샌드박스가 다시 시작될 때까지 git fetch sandbox-<name>은 실패해요.
  • 샌드박스를 재시작하면 데몬에 다른 임시 포트가 할당돼요. CLI가 호스트 저장소의 Git 구성에서 sandbox-<name> remote URL을 업데이트하므로 수동 재구성 없이 fetch가 계속돼요.
  • sbx rm은 샌드박스, 데몬, 게시된 포트, 호스트 저장소의 sandbox-<name> remote 항목을 제거해요.

단일 작업 (Single task)

  1. 클론 모드 샌드박스를 시작하세요:

    $ sbx run --clone claude .

  2. 에이전트가 편집을 시작하기 전에 브랜치를 만들라고 요청하세요:

    Create a branch feat/my-feature and make the changes.

  3. 끝나면 에이전트의 브랜치를 fetch하세요:

    $ git fetch sandbox-<name>
$ git log sandbox-<name>/feat/my-feature
$ git diff main..sandbox-<name>/feat/my-feature

  4. 브랜치를 호스트로 당기고 푸시하거나, 에이전트에게 직접 푸시하라고 하세요:

    # Pull to host, then push
$ git checkout -b feat/my-feature sandbox-<name>/feat/my-feature
$ git push -u origin feat/my-feature
$ gh pr create

# Or ask the agent
# "Push feat/my-feature to origin and open a PR."

병렬 작업 (Parallel tasks)

  1. 클론 모드 샌드박스를 시작하고 에이전트 뷰를 여세요:

    $ sbx run --clone claude .

  2. 각 독립 작업을 별도 백그라운드 세션으로 분배하세요. 에이전트 도구가 브랜치나 워크트리로 변경을 분리할 수 있습니다. 그렇지 않으면 다음과 같은 프로젝트 지침을 추가하세요:

    Always start each task on its own git branch before making changes.

  3. 에이전트들이 끝나면 모든 브랜치를 fetch하세요:

    $ git fetch sandbox-<name>
$ git log sandbox-<name>/feat/task-a
$ git log sandbox-<name>/feat/task-b

  4. 보관하고 싶은 브랜치를 체크아웃하고 평소처럼 PR을 여세요.

호스트 워크트리 (Host worktree)

호스트에 Git 워크트리를 만들고 샌드박스를 그곳에 가리킬 수 있어요. 에이전트가 워크트리의 파일을 직접 편집해요 — 하지만 샌드박스가 워크트리 디렉터리만 마운트하므로(부모 저장소는 아님) .git 포인터 파일을 해석할 수 없어 Git 접근이 없어요. 에이전트는 파일을 읽고 쓸 수 있지만, 커밋, 브랜치, 상태 확인은 할 수 없어요.

이것은 클론 모드의 생성 시 고정 없이 브랜치 격리를 원하고, 변경을 검토한 후 호스트에서 직접 커밋할 때 유용해요.

  1. 호스트에서 워크트리를 만드세요:

    $ git worktree add -b feat/my-feature ../my-feature-work

  2. 워크트리를 워크스페이스로 샌드박스를 시작하세요:

    $ sbx run claude ../my-feature-work

  3. 에이전트가 파일을 편집해요. 끝나면 호스트에서 커밋하고 푸시하세요:

    $ cd ../my-feature-work
$ git diff
$ git add -p && git commit
$ git push -u origin feat/my-feature
$ gh pr create

커밋 서명 (Commit signing)

SSH 에이전트 포워딩은 기본적으로 활성화돼요. SSH_AUTH_SOCK이 설정되면 샌드박스가 호스트 SSH 에이전트를 샌드박스로 포워딩하므로, 개인 키가 호스트를 떠나지 않고 에이전트가 SSH 키로 커밋을 서명할 수 있어요. 포워딩을 껐거나 고정 SSH 에이전트 소켓을 사용한다면 SSH 에이전트 구성을 참고하세요.

  1. 서명 키가 호스트 SSH 에이전트에 로드되어 있는지 확인하세요:

    $ ssh-add ~/.ssh/id_ed25519
$ ssh-add -L  # confirm the key appears

  2. 샌드박스 안에서 Git이 SSH로 서명하도록 구성하세요. 호스트 경로는 샌드박스 안에 존재하지 않으므로 파일 경로가 아니라 포워딩된 키를 직접 사용하세요:

    $ git config --global gpg.format ssh
$ git config --global user.signingkey "key::$(ssh-add -L | head -n 1)"

  3. 평소처럼 커밋을 서명하세요:

    $ git commit -S -m "feat: my change"

이 구성을 모든 샌드박스에 자동 적용하려면 위 설정을 모두 처리하는 git-ssh-sign 커뮤니티 kit를 사용하세요. 내장 에이전트와 함께 쓰는 방법은 Kits v2를 참고하세요.

문제 해결은 샌드박스 커밋이 서명되지 않음을 참고하세요.

더 알아보기 (Learn more)