에디터 및 앱 통합

에디터 및 앱 통합 (Editor and app integrations)

외부 에디터나 데스크톱 앱을 SSH로 실행 중인 샌드박스에 연결하는 방법을 알아볼게요.

출처: 문서

본문

이 통합들은 로컬 샌드박스 SSH 접근을 사용해요. 클라우드 샌드박스는 다른 SSH 구성과 주소를 사용해요: SSH로 연결을 참고하세요.

외부 에디터나 데스크톱 앱을 실행 중인 샌드박스에 SSH로 연결할 수 있어요. 이렇게 하면 이미 익숙한 도구(VS Code, Cursor, Claude Desktop 등)를 사용하면서, 코드는 호스트가 아니라 격리된 샌드박스 안에서 실행·빌드·수행돼요.

각 샌드박스는 <name>.sbx로 접근 가능하며, <name>은 샌드박스 이름이에요. SSH가 설정되면 <name>.sbx는 다른 SSH 호스트처럼 동작하므로, 원격 개발을 SSH로 지원하는 어떤 도구든 연결할 수 있어요.

사전 요구 사항 (Prerequisites)

sbx CLI가 설치되고 로그인되어 있어야 해요. 시작하기를 참고하세요.
SSH 클라이언트. macOS와 대부분의 Linux 배포판에는 OpenSSH가 포함돼 있어요. Windows에서는 OpenSSH 클라이언트를 설치하세요.
연결하려는 에디터 또는 앱과, 그 원격-over-SSH 지원 설치.

SSH 접근 활성화 (Enable SSH access)

SSH 설정 명령을 한 번 실행하세요:

$ sbx setup ssh

이 명령은 필요하면 Docker Sandboxes 데몬을 시작하고 SSH 클라이언트를 구성해요. 언제든 다시 실행할 수 있어요.

샌드박스 생성 또는 확인 (Create or identify a sandbox)

SSH 연결에는 기존 샌드박스가 필요해요. 현재 디렉터리용으로 이름 있는 셸 샌드박스를 만들려면:

$ sbx create --name demo shell .

기존 샌드박스를 확인하려면 목록을 보세요:

$ sbx ls

SSH로 샌드박스에 연결

.sbx 접미사를 붙인 샌드박스 이름을 사용하세요. 예를 들어 demo라는 샌드박스에 연결하려면:

$ ssh demo.sbx

워크스페이스 폴더 선택 (Select the workspace folder)

앱을 샌드박스에 연결하면 원격 환경을 선택하지만 기본 워크스페이스를 자동으로 열지 않을 수 있어요. 초기 폴더는 클라이언트에 따라 달라요. 원격 폴더 선택기가 샌드박스 사용자의 홈 디렉터리인 /home/agent에서 열릴 수 있고, 대화형 ssh 셸은 /home/agent/workspace에서 시작될 수 있어요. 초기 위치에 의존하지 말고 의도한 폴더를 명시적으로 선택하세요.

기본 워크스페이스가 있는 샌드박스의 경우 각 워크스페이스 경로가 호스트에서와 같은 절대 경로로 샌드박스 안에 나타나요. 예를 들어 /Users/bob/src/my-project를 전달했다면 원격 폴더 선택기에서 그 경로를 선택하세요. Docker가 제공하는 에이전트 템플릿을 사용하는 마운트 없는 샌드박스라면 /home/agent/workspace를 선택하세요.

특정 도구 연결 (Connect a specific tool)

SSH 연결이 동작하는 방식 (How SSH connections work)

관리되는 SSH 구성

sbx setup ssh는 SSH 구성에 관리 블록을 써요: macOS와 Linux에서는 ~/.ssh/config, Windows에서는 %USERPROFILE%\.ssh\config. 그 블록은 다음과 비슷해요:

# >>> docker sandboxes (managed) >>>
Host *.sbx
    User _default_user_
    ProxyCommand "sbx" ssh proxy %n
    IdentityAgent none
    IdentityFile /dev/null
    IdentitiesOnly yes
    ControlMaster no
    ControlPath none
    UserKnownHostsFile "~/.ssh/sbx_known_hosts"
    KnownHostsCommand "sbx" ssh known-hosts %H
    StrictHostKeyChecking yes
# <<< docker sandboxes (managed) <<<

이 블록을 손으로 편집하지 마세요. 주요 항목은 다음과 같이 동작해요:

Host *.sbx는 샌드박스 호스트네임을 샌드박스 데몬에 매핑해요. 앱 호스트 선택기는 이 와일드카드에서 개별 샌드박스 이름을 발견하지 못하므로, 통합을 구성할 때 demo.sbx 같은 호스트네임을 직접 입력하세요.
User _default_user_는 데몬이 샌드박스 이미지의 기본 사용자를 사용하도록 해서, 호스트 사용자 이름이 절대 전송되지 않아요.

연결 및 인증 (Connection and authentication)

연결은 네트워크 포트나 SSH 키를 사용하지 않아요:

ProxyCommand가 SSH 스트림을 데몬의 로컬 소켓(macOS·Linux에서는 Unix 도메인 소켓, Windows에서는 named pipe)으로 릴레이해요.
데몬은 활성 Docker 로그인이 있는 동안에만 연결을 수락해요. 인증은 저장된 키가 아니라 로그인에 묶여 있어요.
호스트 키는 모든 연결에서 검증되므로, 회전된 데몬 키가 호스트 키 불일치를 절대 유발하지 않아요.

SSH가 데몬에서 종료되므로 샌드박스 안에는 SSH 서버가 실행되지 않아요. 샌드박스는 이미 생성되어 있어야 해요. 중지된 상태라면 <name>.sbx에 연결하면 자동으로 시작돼요.

환경 변수 (Environment variables)

SSH 연결은 클라이언트 환경 변수를 샌드박스 안으로 전달하지 않아요. 데몬은 호환성을 위해 SSH 환경 요청을 수신하지만 이름과 값을 무시해요.

포트 포워딩 (Port forwarding)

SSH 클라이언트는 로컬 포트 포워딩으로 샌드박스 루프백 인터페이스에서 듣는 서비스를 호스트에서 사용할 수 있게 할 수 있어요. 예를 들어 원격 개발 클라이언트는 샌드박스의 127.0.0.1:4321을 호스트의 127.0.0.1:55565에 매핑하고, 사용 가능한 호스트 포트를 자동으로 선택할 수 있어요. 트래픽은 게시된 Docker 포트가 아니라 SSH 연결을 통과해요.

샌드박스 데몬은 localhost, 127.0.0.0/8, ::1을 포함한 샌드박스의 루프백 주소로의 포워딩 연결만 수락해요. SSH 클라이언트가 호스트의 리스너 바인드 주소를 선택해요. 127.0.0.1이나 ::1에 바인딩된 리스너는 호스트에서만 도달 가능해요. 비루프백 주소에 바인딩하도록 구성된 클라이언트는 호스트의 네트워크·방화벽 구성에 따라 포워딩된 서비스를 다른 머신에서도 도달 가능하게 만들 수 있어요.

에디터 및 앱 통합