remote-devbox은(는) 무엇을 하나요?
devbox를 설정(또는 수리)합니다: 사용자 컴퓨터의 Claude 데스크톱 앱이 인터페이스 역할만 하는 동안 Claude Code 세션이 실행되는 Linux 서버입니다. 단계를 순서대로 진행하십시오. 각 단계는 무엇을 해야 하는지, 사용자만 할 수 있는 작업, 그리고 제대로 작동하는지 확인하는 방법을 설명합니다.
<skill>은 이 파일이 포함된 폴더를 의미합니다.
사용자가 얻게 되는 것
- 데스크톱 앱의 Code 탭은 그대로 유지되지만, 모든 세션(쉘, 테스트, 설치, Python, Node, Chrome)은 SSH를 통해 devbox에서 실행됩니다. 사용자 컴퓨터는 인터페이스만 표시합니다.
- 사용자의 구독을 사용합니다(API 크레딧 사용 안 함). 데스크톱 앱이 세션의 로그인을 전달하고 갱신합니다. devbox에
ANTHROPIC_API_KEY를 절대 설정하지 마십시오. 과금이 API로 넘어갑니다. - MCP 서버로 두 개의 브라우저를 제공합니다:
chrome(사용자 계정이 로그인된 공유 Chrome)과playwright(세션당 하나의 깨끗한 격리 Chrome). 가상 화면(noVNC)을 통해 사용자의 사설 네트워크 내 모든 웹 브라우저에서 공유 Chrome을 볼 수 있습니다. - 컴퓨터가 꺼져도 세션이 계속됩니다:
devbox-relay는 중단된 데스크톱 세션을 백그라운드에서 재개하고,devbox-rc는 claude.ai/code 또는 휴대폰 앱에서 시작된 세션을 호스팅합니다. - 컴퓨터와 동일한 글로벌
CLAUDE.md, 스킬, 메모리, 플러그인 훅을 사용합니다.
작동 방식에 대한 설명은 references/how-it-works.md를, 문제 발생 시에는 references/troubleshooting.md를 참조하십시오.
기본 규칙
- 사용자가 직접 해야 하는 작업: 결제 및 주문, 모든 비밀번호 및 로그인(제공업체, Tailscale, GitHub 기기 코드, Claude
/login, 공유 Chrome의 웹사이트), 데스크톱 앱 설정 내 클릭, Tailscale 관리 콘솔 사용. 정확한 링크나 명령어를 한 번에 하나씩 알려주고 기다리십시오. 비밀번호, 카드 번호 또는 일회성 코드를 직접 입력하지 마십시오. - 주문하기 전에 계획, 가격 및 약정을 설명하고 동의를 얻으십시오.
- 설정 스크립트는 멱등성을 갖습니다. 하나가 실패하면 오류를 읽고 원인을 수정한 후 다시 실행하십시오.
- devbox에서 sudo는 비밀번호가 필요 없습니다. 그러나 스크립트가 직접 수행하지 않는 시스템 변경(패키지, 서비스, 방화벽, sshd, 사용자)은 사용자에게 먼저 문의하십시오.
- 사용자의 실행 중인 devbox에서 작업할 때는
devbox-*서비스를 중지하거나,~/.claude를 편집하거나,~/.local/bin의 바이너리를 교체하기 전에 반드시 알리십시오. 세션이 실행 중일 수 있습니다.
0단계: 컴퓨터 확인
- 플랫폼. Windows:
<skill>/client/windows/스크립트 사용(Windows PowerShell 5.1 가능). macOS 또는 Linux:<skill>/client/unix/. - Windows 전용: OpenSSH 클라이언트 9.4 이상(
ssh -V). 데스크톱 앱에 필요합니다. 이전 버전인 경우:winget install Microsoft.OpenSSH.Preview. - Claude 데스크톱 앱이 설치 및 로그인되어 있고, 사용자의 플랜에 Claude Code가 포함되어 있어야 합니다.
git config --global user.name및user.email이 설정되어 있어야 합니다(스크립트가 devbox로 복사함).- 사용자에게 어떤 선택 사항을 원하는지 물어보십시오: gatehaul(무거운 빌드를 GitHub Codespaces에서 실행,
-Gatehaul/--gatehaul), 공유 로그인 Chrome(기본 켜짐), 메모리 복사.
1단계: 서버 선택 및 주문
references/providers.md를 참조하십시오. 요구 사항: KVM 가상 머신, Ubuntu 24.04, x86_64 권장(arm64도 작동하지만 종단 간 테스트되지 않음), 최소 8GB RAM(병렬 세션 여러 개와 Chrome의 경우 16~24GB), 80GB 디스크, 제공업체의 웹 콘솔(SSH가 잠긴 경우 복구 경로).
사용자가 비교할 수 있도록 도와준 후, 브라우저가 있다면 주문 페이지를 열어주십시오. 사용자가 요금제를 선택하고 결제하며 확인합니다. 제공업체가 주문 시 SSH 키를 요구하면 먼저 키를 보여주십시오:
powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -ShowKey
bash <skill>/client/unix/setup-devbox.sh --show-key
사용자에게 공개 IP와 초기 사용자(종종 root; OVH 및 Oracle에서는 ubuntu)를 물어보십시오.
2단계: 서버 부트스트래핑
powershell -ExecutionPolicy Bypass -File <skill>\client\windows\setup-devbox.ps1 -HostAddress <IP> -InitialUser root
bash <skill>/client/unix/setup-devbox.sh --host <IP> --initial-user root
사용자가 입력할 수 있는 터미널(데스크톱 앱의 터미널 패널 또는 사용자에게 직접 실행 요청)에서 실행하십시오. 사용자에게 세 가지가 필요합니다:
- 호스트 키 지문. 스크립트가 지문을 표시하고 예/아니오를 묻습니다. 사용자에게 제공업체 웹 콘솔에서
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub의 출력과 비교하도록 알리십시오. - 초기 비밀번호(주문 시 키가 제공된 경우 생략), 키가 인증될 수 있도록 한 번만 입력.
- GitHub 기기 코드:
gh auth login이 코드와 링크를 출력합니다.
스크립트가 수행하는 작업: 키 ~/.ssh/devbox_ed25519 생성(암호 없음, 데스크톱 앱이 프롬프트 없이 연결해야 함), host/10-root-bootstrap.sh 실행(dev 사용자, sudo, 키 전용 SSH, linger, 스왑, Node, gh, Chrome, Tailscale, ufw, fail2ban, unattended upgrades, 가상 화면 패키지), ~/.ssh/config에 Host devbox 블록 추가, 테스트, SSH를 dev 사용자로 제한, host/20-user-setup.sh 실행(uv, Claude Code CLI, 선택적 gatehaul, MCP 서버, ~/.local/bin 도구, 가상 화면 서비스, 릴레이 서비스 및 훅), 그런 다음 Claude 구성 동기화(6단계).
확인: ssh devbox 'claude --version; claude mcp list; systemctl --user is-active devbox-vnc devbox-chrome devbox-relay'.
3단계: 사설 네트워크 연결 후 공개 SSH 차단
- 사용자: 컴퓨터에 Tailscale을 설치하고 로그인합니다(
winget install tailscale.tailscale, Mac App Store 또는 tailscale.com/download). - devbox에서:
ssh -t devbox sudo tailscale up --hostname=devbox. 로그인 링크가 출력됩니다. 사용자가 링크를 엽니다. - 사용자: Tailscale 관리 콘솔, Machines,
devbox, Disable key expiry. 그렇지 않으면 180일 후 devbox가 네트워크에서 떠나고 제공업체 콘솔만 남습니다. ~/.ssh/config에서devbox블록의HostName을devbox(MagicDNS) 또는ssh devbox tailscale ip -4의 주소로 설정합니다.ssh devbox true로 확인합니다.- 공개 SSH 차단:
ssh -t devbox 'bash ~/devbox-setup/30-root-lockdown.sh'. Tailscale을 통하지 않은 SSH 세션이 열려 있으면 실행을 거부합니다. 해당 세션(공개 IP로 열린 데스크톱 앱 세션 포함)을 먼저 닫으십시오.
잠금 해결 방법: 제공업체 웹 콘솔에서 sudo ufw allow OpenSSH 실행.
4단계: 데스크톱 앱 연결
사용자가 데스크톱 앱에서: Code 탭, 프롬프트 상자 아래 환경 메뉴, New environment, SSH(레이블은 2026년 말 기준이며 변경될 수 있음):
| 필드 | 값 |
|---|---|
| SSH host | devbox (~/.ssh/config에서 가져옴) |
| SSH key | 비워 둠 |
| Worktree folder | ~/worktrees |
| Folder for a session | ~/dev/<project> |
첫 번째 연결 시 앱이 devbox의 ~/.claude/remote/ 아래에 자체 엔진을 설치하고 호스트 키를 표시합니다. 2단계와 동일한 지문입니다. 해당 환경의 세션은 devbox에서 실행됩니다. SSH 세션에는 Browser 창이 없습니다. 대신 포트를 전달하십시오(일일 사용 참조).
5단계: 로그인된 Chrome
ssh devbox devbox-browser login(Chrome이 디버깅 포트 없이 다시 시작됩니다. Google은 디버깅 포트가 있는 Chrome에서 로그인을 거부하는 경우가 많습니다.)- 사용자가 tailnet의 머신에서
http://devbox:6080/vnc.html을 엽니다. 비밀번호:ssh devbox devbox-browser password. Tailscale이 없는 경우:ssh -N -L 6080:localhost:6080 devbox후http://localhost:6080/vnc.html. - 사용자가 에이전트가 사용해야 하는 사이트에 로그인합니다. 은행 및 주입된 명령이 비용을 초래할 수 있는 사이트는 금지하는 것이 좋습니다. 모든 세션이 이 브라우저를 제어할 수 있습니다.
ssh devbox devbox-browser normal로 에이전트에게 다시 넘깁니다(디버깅 포트 9222, 로컬 전용).
확인: devbox 세션에서 chrome MCP에 사용자가 로그인한 사이트를 열도록 요청하고(개인 콘텐츠를 읽지 않고) 계정이 보이는지 확인합니다. 작업 표시줄 아이콘과 화면의 오른쪽 클릭 메뉴가 이 Chrome을 엽니다. devbox의 기본 브라우저이기도 합니다.
6단계: 로컬 Claude 환경 미러링
목표: devbox의 세션이 컴퓨터의 세션처럼 동작합니다.
- 글로벌 CLAUDE.md 및 스킬:
powershell -ExecutionPolicy Bypass -File <skill>\client\windows\sync-claude-config.ps1 -Memory
로컬bash <skill>/client/unix/sync-claude-config.sh --memory~/.claude/CLAUDE.md앞에<skill>/templates/host-header.md(devbox에서 다른 점: 경로, 브라우저, 화면, 지속성, sudo 규칙)를 추가하고,~/.claude/skills(.venv,node_modules,.git제외)를 병합하며,-Memory를 사용하여 로컬 프로젝트 폴더(-LocalDevDir, 기본값~/Documents/dev)의 자동 메모리를 devbox의~/dev메모리로 복사합니다. 로컬 CLAUDE.md나 스킬이 변경될 때마다 다시 실행하십시오. 헤더 템플릿을 편집하고 devbox의 복사본은 덮어쓰여지므로 편집하지 마십시오. - 설정이 필요한 스킬: 동기화된 각 스킬에 대해 Python 환경(
requirements.txt,pyproject.toml), Node 패키지, 바이너리 및SKILL.md의 Windows 경로를 찾으십시오. devbox에서 환경을 다시 만들고 경로를 수정하십시오. 필요한 시스템 도구(예:ffmpeg)는 문의 후 설치하십시오. - 플러그인: 데스크톱 앱은 SSH 세션에서 사용자의 플러그인을 설치하지만, 훅은 거기서 실행되지 않습니다.
hooks/hooks.json이 있는 각 활성화된 플러그인에 대해, 동일한 커밋의 소스를 devbox의~/.claude/hooks-thirdparty/<plugin>에 클론하고, 해당 훅을 devbox의~/.claude/settings.json에 병합하되,${CLAUDE_PLUGIN_ROOT}는 해당 폴더로 바꾸고 인터프리터는 Linux에 맞게 수정합니다(python을python3으로).jq로 병합하고 기존devbox-relay guardSessionStart 훅은 유지하십시오. 훅 스크립트를 활성화하기 전에 읽어보십시오. - MCP 서버: 로컬과 devbox에서
claude mcp list를 비교하십시오. Linux에서 의미 있는 사용자 범위 stdio 서버를 다시 추가하십시오. claude.ai 커넥터는 계정을 따릅니다. 할 일이 없습니다. - 프로젝트:
gh repo clone을 사용하여~/dev/<name>에 클론합니다. 중요한 커밋되지 않았거나 무시된 로컬 파일(.env파일은 사용자의 동의를 받고)을 복사하고, 종속성을 설치하며, 가벼운 테스트를 실행합니다. 무거운 빌드는 gatehaul이 설치된 경우 Codespaces에 속합니다. - 사용자 없이 긴 마이그레이션: 이동할 내용이 많으면 작업 목록을 작성한 후, references/setup-agent-prompt.md를 통해
claude-task로 devbox에서 자율 세션을 시작하십시오.
7단계: 컴퓨터가 꺼져도 계속되는 세션
- devbox에서 CLI 로그인(릴레이 및 원격 제어에서 사용):
ssh -t devbox claude,/login; 사용자가 링크를 열고 코드를 붙여넣습니다./exit. - 릴레이:
20-user-setup.sh에서 이미 활성화되었습니다.ssh devbox devbox-relay test(모든 케이스 OK) 및ssh devbox devbox-relay status로 확인하십시오. - 원격 제어 서버, 두 번의 확인이 필요하므로 수동으로 한 번:
ssh -t devbox 'cd ~/dev && claude remote-control', 사용자가y로 두 번 응답한 다음 Ctrl+C. 그런 다음ssh devbox 'touch ~/.config/devbox/rc-accepted && systemctl --user enable --now devbox-rc'. claude.ai/code 또는 휴대폰 앱에서 폴더와 호스트 이름으로 된 환경(예:dev · <hostname>)이 devbox에서 세션을 시작합니다. 혼자 진행되어야 하는 세션의 경우 Auto 권한 모드를 선택하십시오. claude.ai는 사용자에게 기기를 확인하기 위해 다시 로그인하도록 요청할 수 있습니다. - 선택적 실제 테스트(사용자와 함께): 권한 질문에서 중단될 작은 작업을 데스크톱 세션에서 시작하고, 사용자가 데스크톱 앱을 종료하고 약 30분 기다린 후 다시 엽니다.
~/dev/_relay/log.md로그에 릴레이가 표시되고, devbox의claude agents에relay · <name>이 표시되며, 다시 열린 원래 세션은 릴레이되었다고 표시됩니다.
8단계: 최종 확인
각 라인을 실행하고 보고하십시오:
ssh devbox 'claude --version; gh auth status 2>&1 | head -3; claude mcp list'
ssh devbox 'systemctl --user is-active devbox-vnc devbox-wm devbox-novnc devbox-panel devbox-chrome devbox-relay devbox-rc'
ssh devbox 'devbox-browser status; devbox-relay test | tail -1; free -h; df -h ~'
ssh devbox 'grep -c ANTHROPIC_API_KEY ~/.bashrc ~/.profile 2>/dev/null; sudo ufw status'
예상 결과: 모든 서비스가 active(devbox-rc는 7단계 이후), MCP 서버 chrome 및 playwright 연결됨, API 키 없음, ufw가 tailscale0(및 41641/udp)만 허용.
그런 다음 사용자에게 무엇이 준비되었는지, 아직 무엇을 해야 하는지, 각 부분에 어떻게 접근하는지 알려주십시오.
일일 사용(사용자에게 알림)
- 개발 서버 보기: devbox의
127.0.0.1:<port>에서 실행하고, 컴퓨터에서ssh -N -L <port>:localhost:<port> devbox실행 후http://localhost:<port>열기. - tmux에서 장시간 작업:
claude-task start <name> ~/dev/<project> "<prompt>" [--rc] [--mode auto], 그런 다음claude-task list | show | send | stop;tmux attach -t ct-<name>(Ctrl+b d로 나가기). - 의도적으로 세션을 백그라운드로 넘기기:
claude --resume <id> --fork-session --bg --remote-control "<name>" --permission-mode auto "<prompt>". - 릴레이 활동:
ssh devbox devbox-relay status, 로그는~/dev/_relay/log.md. - 도구 업데이트:
PW_MCP_VERSION=<v> INSTALL_GATEHAUL=1 GATEHAUL_VERSION=<tag> bash ~/devbox-setup/20-user-setup.sh. - 전원이 꺼진 서버도 일반적으로 청구됩니다.