T3 Code를 샌드박스에 연결

T3 Code를 샌드박스에 연결 (Connect T3 Code to a sandbox)

T3 Code가 SSH로 샌드박스 안의 코딩 에이전트를 구동하도록 연결하는 방법과 발생할 수 있는 문제를 알아볼게요.

출처: 문서

본문

이 연결 지침은 로컬 샌드박스를 사용해요. 클라우드 SSH 설정은 SSH로 연결을 참고하세요.

T3 Code의 SSH 통합은 데스크톱 앱이 샌드박스 안에서 코딩 에이전트를 구동하게 해줘요. T3 Code에는 전용 Docker Sandboxes 통합이 없어요. 샌드박스를 일반 SSH 호스트처럼 취급해 연결하고, 앱으로 다시 터널링하는 T3 서버를 그 안에서 시작해요.

사전 요구 사항 (Prerequisites)

SSH 접근이 설정되어 있어야 해요. 에디터 및 앱 통합을 참고하세요.
T3 Code가 설치되어 있어야 해요.

첫 연결은 샌드박스에 T3 서버를 설치하며, 빌드 도구 체인이 필요해요. T3는 macOS와 Windows에만 사전 빌드 바이너리를 제공하는 node-pty에 의존해요. Linux 샌드박스에서는 node-pty가 소스에서 컴파일되며, make, python3, g++ 같은 컴파일러 없이는 빌드가 실패해요.

t3code kit는 T3 Code용 샌드박스를 준비해요: 샌드박스 생성 시 빌드 도구 체인과 t3 npm 패키지를 설치하므로, 첫 연결이 소스에서 node-pty를 빌드하는 대신 사전 설치된 서버를 시작해요. 모든 표준 에이전트 템플릿이 그러하듯, 기본 이미지가 Node.js 18 이상을 제공하는 어떤 에이전트와도 함께 쓰세요:

$ sbx run claude --kit docker.io/sbx/t3code-kit:latest

기존 샌드박스라면 도구 체인을 수동으로 설치하세요:

$ sbx exec <sandbox> -- sudo apt-get update
$ sbx exec <sandbox> -- sudo DEBIAN_FRONTEND=noninteractive apt-get install -y g++ make python3

도구 체인이 제대로 있는지 확인하세요:

$ sbx exec <sandbox> -- sh -lc 'command -v g++ && command -v make && command -v python3'

수동 설치는 샌드박스가 다시 생성될 때까지이며, 첫 연결은 여전히 소스에서 node-pty를 빌드해요. 지속되는 설정을 원하면 v2 kit 또는 사용자 정의 템플릿으로 샌드박스를 다시 만드세요.

연결 (Connect)

터미널에서 샌드박스에 연결할 수 있는지 확인하세요:

$ ssh demo.sbx

T3 Code에서 SSH 환경을 추가하고 호스트로 demo.sbx 같은 샌드박스 호스트네임을 입력하세요. t3code kit가 사전 설치하지 않았다면 첫 연결이 샌드박스 안에 T3 서버를 설치하므로 시간이 걸릴 수 있어요. 이후 연결은 더 빨라요.

그런 다음 새 프로젝트를 추가하고, 목록에서 SSH 환경을 선택한 뒤, 마운트된 워크스페이스를 샌드박스 안의 프로젝트 디렉터리로 선택하세요.

서버가 준비되지 않는 문제 해결

T3 Code가 다음과 비슷한 오류로 연결에 실패할 수 있어요(가독성을 위해 줄바꿈). 연결 실패와 샌드박스 안 npm 설치 출력을 단일 오류 대화상자로 연결해요:

Could not prepare the SSH environment: ... SshCommandError: Connecting to
sandbox "sandboxes"… Remote T3 server did not become ready on
127.0.0.1:3773. npm WARN EBADENGINE Unsupported engine { package:
'[email protected]', required: { node: '^22.22.2 || ^24.15.0 || >=26.0.0' },
current: { node: 'v22.22.1', npm: '9.2.0' } }

npm WARN EBADENGINE 줄은 전이적 ini 의존성에 대한 경고이며 실패와는 별개예요: npm은 engine-strict가 설정되었을 때만 엔진 요구 사항을 시행하는데 기본적으로 꺼져 있으므로, 이 경고만으로는 설치가 계속 진행될 수 있어요.

가장 흔한 원인은 C++ 도구 체인 누락과 디스크 가득 참인데, 둘 다 동일한 오류를 만들어내요. npm의 실제 출력을 얻어 구분하세요:

$ sbx exec <sandbox> -- sh -lc \
  'rm -rf /tmp/t3probe && mkdir -p /tmp/t3probe && cd /tmp/t3probe \
   && npm init -y >/dev/null && npm install t3@latest 2>&1 | tail -40'

컴파일러 누락은 네이티브 node-pty 빌드를 make의 Error 127로 실패시켜요:

npm ERR! make: g++: No such file or directory
npm ERR! make: *** [pty.target.mk:115: Release/obj.target/pty/src/unix/pty.o] Error 127
npm ERR! gyp ERR! build error
npm ERR! gyp ERR! stack Error: `make` failed with exit code: 2

사전 요구 사항에서 설명한 대로 빌드 도구 체인을 설치하세요.

디스크 가득 참은 ENOSPC로 실패하며, npm이 네이티브 빌드 시작 전에 실패하므로 gyp 출력이 전혀 나타나지 않아요:

npm ERR! code ENOSPC
npm ERR! nospc ENOSPC: no space left on device

여유 디스크 공간을 확인하세요:

$ sbx exec <sandbox> -- df -h /

샌드박스는 두 문제를 동시에 가질 수 있어요. 하나를 고쳐도 같은 최상위 오류가 남으므로 결론을 내리기 전에 도구 체인과 디스크 공간을 모두 확인하세요. 필요에 따라 공간을 확보하거나 도구 체인을 설치한 다음 다시 연결하세요.

`turn/setPermissionMode failed` 문제 해결

조직이 정책 파일로 Claude Code를 관리하면, 로컬 T3 Code 스레드가 turn/setPermissionMode failed로 시작에 실패할 수 있어요. T3 Code의 기본 런타임 모드는 Full access인데, 이는 Claude Agent SDK의 bypassPermissions 모드에 매핑돼요. 그 모드를 비활성화하는 관리 정책이 요청을 거부해요.

macOS에서 해당 여부를 확인하세요:

$ cat "/Library/Application Support/ClaudeCode/managed-settings.json"

permissions.disableBypassPermissionsMode가 disable로 설정되어 있다면, T3 Code를 Supervised, Auto-accept edits, Auto 같은 다른 런타임 모드로 전환한 다음 새 스레드를 시작하세요. 권한 모드는 스레드 시작 시 한 번 캡처되므로, 이미 실패한 스레드에서 모드를 전환해도 복구되지 않아요.

이 제한은 샌드박스가 아니라 Claude Code를 실행하는 호스트에 적용돼요. 샌드박스에 연결된 스레드는 호스트의 관리 정책을 받지 않으므로, 그곳에서는 Full access가 정상 동작해요.

에디터 및 앱 통합 — SSH 접근이 동작하는 방식과 설정 방법

T3 Code를 샌드박스에 연결