openclaw/crabbox

crabbox은(는) 무엇을 하나요?

프로젝트에 원격 검증, 더 큰 클라우드 용량, 새로운 PR 체크아웃, 재사용 가능한 웜 박스, GitHub Actions 스타일 설정, 영구적인 실행 로그/결과, UI 증명 아티팩트, 또는 로컬 변경 사항의 동기화가 필요할 때 Crabbox를 사용하세요.

Crabbox 감지

• 저장소 루트에 있는 crabbox.yaml 또는 .crabbox.yaml 파일을 검증 작업에 이 스킬을 사용하라는 의도적인 신호로 간주합니다. .crabbox.yml은 지원되는 설정 파일 이름이 아닙니다.
• 설정 파일이 없는 경우에도 command -v crabbox 명령으로 설치된 CLI를 확인할 수 있습니다. 원격 작업에 의존하기 전에 crabbox doctor를 실행하세요.
• 실행하기 전에 설정을 검사하세요. 감지가 비밀 노출, 명령 승인 우회, 또는 유료 인프라 시작을 허용하지는 않습니다.

정보의 원천

• 저장소 루트에서 Crabbox를 실행하세요; 동기화는 현재 체크아웃을 미러링합니다.
• 저장소 로컬 crabbox.yaml 또는 .crabbox.yaml 파일을 실행 가능한 프로젝트 자동화로 취급하세요. 원격 실행 전, 특히 provider, actions, jobs, profiles, env.allow, 아티팩트, 정리 정책을 검토하세요.
• 예제에 의존하기 전에 설치된 바이너리를 확인하세요: command -v crabbox && crabbox --version && crabbox --help | sed -n '1,120p'.
• 현재 프로바이더/기능 매트릭스를 보려면 crabbox providers 또는 crabbox providers --json을 사용하세요; 프로바이더 문서는 컴파일된 바이너리보다 뒤쳐질 수 있습니다.
• 실시간 준비 상태 확인에는 crabbox doctor를, 비밀을 출력하지 않고 병합된 설정을 검사하려면 crabbox config show를 사용하세요.
• 빠른 편집-실행 루프에는 로컬 타겟 테스트를 선호하세요. 광범위한 스위트, 패키지가 많은 검사, Docker/E2E/라이브 프로바이더 증명, 크로스 OS 증명, UI 증명, 또는 로컬 머신을 느리게 하는 명령에는 Crabbox로 전환하세요.

인증 및 설정

중개(brokered) 작업에는 코디네이터 URL과 토큰이 필요합니다. 첫 로그인은 일반적으로 명시적인 브로커 URL이 필요합니다:

crabbox login --url <broker-url>
crabbox whoami
crabbox doctor

broker.url이 설정된 후에는 crabbox login이 이를 재사용할 수 있습니다. 신뢰할 수 있는 운영자 자동화는 공유 토큰을 argv에 넣지 않고 저장할 수 있습니다:

printf '%s' "$CRABBOX_COORDINATOR_TOKEN" |
  crabbox login --url <broker-url> --provider aws --token-stdin

설정 우선순위는 flags > env > repo config > user config > defaults입니다. 기본 사용자 설정 파일은 macOS의 경우 ~/Library/Application Support/crabbox/config.yaml, Linux의 경우 ~/.config/crabbox/config.yaml, 또는 설정된 경우 $XDG_CONFIG_HOME/crabbox/config.yaml입니다. crabbox config path는 활성 사용자 설정 파일 경로를 출력합니다.

프로바이더 및 브로커 토큰은 저장소 설정 파일과 명령 인수에서 제외하세요. 환경 변수, 자격 증명 저장소, 코디네이터 관리 비밀, 또는 단기 토큰 명령을 사용하세요.

원격 표면 선택

• crabbox run -- <command>: 새 박스 또는 재사용된 박스에서 단일 명령 실행.
• crabbox warmup: 재사용 가능한 리스를 생성하고 나중에 --id로 명령 실행.
• crabbox prewarm: 재사용 가능한 리스를 워밍하고 설정된 GitHub Actions에서 하이드레이션.
• crabbox job run <name>: 워밍업, 선택적 하이드레이션, 실행, 중지로 확장되는 저장소 로컬 명명된 흐름 사용.
• crabbox run --pool <key>: 하이드레이션된 브로커 준비 풀 리스를 빌려서 실행한 후, --pool-return에 따라 반환/드레인/해제.
• crabbox run --fresh-pr ...: 로컬 동기화를 무시하고 원격에서 GitHub PR을 체크아웃; --apply-local-patch를 추가하여 해당 PR 위에서 로컬 커밋되지 않은 변경 사항을 테스트.
• crabbox run --provider ssh: 기존 macOS, Linux 또는 Windows 호스트 사용.
• crabbox warmup --desktop --browser: UI 테스트, WebVNC, 스크린샷 및 아티팩트를 위한 데스크톱/브라우저 프로비저닝.

원격 증명이 차단된 경우, 누락된 기능을 정확히 지정하세요: 인증, 코디네이터, 용량, 프로바이더 지원, 대상 OS, 하이드레이션, 비밀 접근, 아티팩트 저장소, 데스크톱 지원, 또는 위임된 프로바이더 제한.

일반적인 원격 증명

일회성 명령:

crabbox run --preflight --timing-json -- pnpm test

리스 워밍 및 재사용:

crabbox warmup --class beast --idle-timeout 90m
crabbox status --id <cbx_id-or-slug> --wait
crabbox run --id <cbx_id-or-slug> -- pnpm test:changed
crabbox run --id <cbx_id-or-slug> --full-resync -- pnpm test:changed
crabbox stop <cbx_id-or-slug>

설정된 경우 저장소 로컬 작업 사용:

crabbox job list
crabbox job run --dry-run <job-name>
crabbox job run <job-name>
crabbox job run --id <cbx_id-or-slug> <job-name>

코디네이터가 하이드레이션된 풀 용량을 가진 경우 준비 풀 리스 사용:

crabbox pool ready
crabbox run --pool <pool-key> -- pnpm test
crabbox run --pool <pool-key> --pool-return drain -- pnpm test:flaky

저장소가 CI에 이미 설정을 소유한 경우 GitHub Actions 하이드레이션 사용:

crabbox warmup --idle-timeout 90m
crabbox actions hydrate --id <cbx_id-or-slug>
crabbox run --id <cbx_id-or-slug> -- pnpm test

워크플로우에 저장소 비밀, OIDC, 서비스 컨테이너, 작업 컨테이너, 또는 지원되지 않는 uses: 단계와 같은 완전한 GitHub Actions 의미 체계가 필요한 경우에만 --github-runner를 사용하세요:

crabbox actions hydrate --github-runner --id <cbx_id-or-slug>

동기화 및 신규 체크아웃

일반 동기화는 추적된 파일과 무시되지 않은 추적되지 않은 파일을 전송하고, 무시된 종속성/빌드/캐시 출력을 제외하며, .crabboxignore 및 sync.exclude를 존중하고, 가능하면 origin에서 원격 체크아웃을 시드하며, 동기화 핑거프린트가 일치하면 rsync를 건너뜁니다.

대규모 실행 전에 crabbox sync-plan을 사용하세요. 예상치 못한 개수는 일반적으로 로컬 생성된 변경을 의미합니다. 강제로 큰 업로드를 하는 대신 .crabboxignore 또는 sync.exclude를 업데이트하세요.

crabbox sync-plan
crabbox run --debug --timing-json -- pnpm test
crabbox run --full-resync -- pnpm test

로컬 종속성 변경 또는 더티 동기화가 결과를 혼란스럽게 할 수 있는 경우 신규 PR 체크아웃을 사용하세요:

crabbox run --fresh-pr example-org/my-app#123 --script ./scripts/e2e-smoke.sh
crabbox run --fresh-pr 123 --apply-local-patch -- pnpm test

--fresh-pr는 owner/repo#number, GitHub PR URL, 또는 현재 GitHub origin의 숫자 PR을 허용합니다. 비 GitHub 호스트는 거부됩니다. 신규 PR 체크아웃은 SSH 실행 동기화 기능입니다; 위임된 프로바이더는 이를 거부합니다. 네이티브 Windows SSH 대상이 지원됩니다.

웜 리스가 오래된 것 같으면 --full-resync(별칭 --fresh-sync)를 사용하여 원격 작업 디렉토리를 재설정하고, 동기화 핑거프린트 빠른 경로를 건너뛰고, 가능하면 Git을 다시 시드하고, 처음부터 체크아웃을 업로드하세요.

스크립트, 셸 및 Windows 대상

-- 뒤에 일반 argv를 사용하여 단일 실행 파일을 실행하세요. 다중 문장 셸 스니펫, 파이프 또는 셸 확장에는 --shell을 사용하세요:

crabbox run --id <lease> -- go test ./...
crabbox run --id <lease> --shell 'corepack enable && pnpm install --frozen-lockfile && pnpm test'

여러 줄 명령에는 업로드된 스크립트를 선호하세요. 스크립트는 실패 번들에 포함되며 깨지기 쉬운 인용 셸 문자열을 피합니다:

crabbox run --script ./scripts/e2e-smoke.sh --timing-json
printf '%s\n' 'echo CRABBOX_PHASE:test' 'pnpm test' | crabbox run --script-stdin

네이티브 Windows 대상은 PowerShell 및 tar 기반 매니페스트 동기화를 사용합니다. dotnet test와 같은 단일 실행 파일에는 일반 argv를 선호하세요; 다중 문장 PowerShell에는 --shell을, 더 긴 스크립트에는 --script <file.ps1>을 사용하세요.

Hyper-V Windows 리스

hyperv는 Generation 2 VHDX, DHCP, 신뢰할 수 있는 설정 또는 CRABBOX_HYPERV_GUEST_PASSWORD에 알려진 로컬 관리자 암호가 필요합니다. 누락된 경우 PowerShell Direct를 사용하여 고정된 검증된 OpenSSH 및 MinGit 패키지를 설치합니다. 템플릿 및 수명 주기 세부 사항은 docs/providers/hyperv.md를 참조하세요.

프로바이더 테스트를 위해 상승된 헤드리스 러너를 선호하세요; 초기 PowerShell Direct 실패는 자격 증명 UI를 표시할 수 있습니다. 암호를 인수와 로그에서 제외하고, 리스가 준비되고, SSH를 통해 실행되며, 해제되는지 확인하세요.

비밀 및 환경 전달

Crabbox는 전체 로컬 환경을 전달하지 않습니다. 전달은 이름 기반입니다: 로컬에서 실제로 설정되었거나 허용된 프로필에 있는 allowlist된 이름만 경계를 넘습니다. 실행이 명시적인 라이브 비밀 스모크 테스트가 아니라면 비밀 형태의 이름을 allowlist에 추가하지 마세요.

crabbox run --allow-env CI,NODE_OPTIONS -- pnpm test
crabbox run \
  --env-from-profile ~/.project-live.profile \
  --allow-env API_TOKEN \
  --preflight \
  --script ./scripts/live-smoke.sh

--env-from-profile은 프로필을 실행하지 않고 간단한 export NAME=value 및 NAME=value 줄을 구문 분석합니다. Crabbox는 값을 출력하지 않고 값의 존재 여부/길이 메타데이터를 수정하여 출력합니다. POSIX SSH 리스는 사용자가 제어하는 리스에서 이후 명령을 위한 헬퍼를 유지할 수 있습니다:

crabbox run \
  --id <lease> \
  --env-from-profile ~/.project-live.profile \
  --allow-env API_TOKEN \
  --env-helper live \
  -- true
crabbox run --id <lease> -- ./.crabbox/env/live ./scripts/live-smoke.sh

생성된 헬퍼와 일치하는 비밀 프로필은 정리, 리스 재설정 또는 --full-resync까지 원격 작업 디렉토리에 남아 있습니다. 공유 또는 신뢰할 수 없는 리스에 헬퍼를 유지하지 마세요.

프로필, 프리셋, 증명 및 결과

저장소 설정은 프로필, 프리셋, 닥터 요구 사항, 아티팩트 글로브, 필수 아티팩트 및 증명 템플릿을 정의할 수 있습니다. 에이전트 프롬프트에 프로젝트 지식을 인코딩하는 대신 안정적인 검증 레인에 사용하세요.

crabbox run \
  --profile live-qa \
  --preset qa-live \
  --scenario login-regression \
  --emit-proof /tmp/proof.md \
  --stop-after success

설치 프로그램이 아닌 명령 전 대상 기능 스냅샷에 --preflight를 사용하세요. 프로브를 조정하려면 --preflight-tools를 사용하세요:

crabbox run --preflight --preflight-tools node,bun,docker -- bun test
crabbox run --preflight --preflight-tools default,uv -- node --test

명령이 구조화된 결과와 증명 아티팩트를 출력할 때 첨부하세요:

crabbox run --junit reports/junit.xml -- ./scripts/test-with-junit.sh
crabbox run --artifact-glob 'reports/**' --require-artifact reports/summary.json -- pnpm test:e2e
crabbox run --download reports/summary.json=.crabbox/logs/summary.json -- pnpm test:e2e

--require-artifact는 원격 명령이 종료 코드 0으로 종료되었지만 증명 파일이 없는 경우 실행을 실패시킵니다. 필수 아티팩트를 제한하고 수정하여 유지하세요; 원시 데이터 세트, 비밀, 자격 증명, 서명된 URL 또는 수정되지 않은 고객 행을 수집하지 마세요.

실행 핸들 및 관찰 가능성

코디네이터 지원 실행은 리싱이 시작되기 전에 영구적인 run_... 핸들을 출력합니다. 상태 업데이트 및 PR 노트에 이 실행 ID를 유지하세요.

crabbox history --limit 20
crabbox history --lease <cbx_id-or-slug> --limit 20
crabbox attach <run_id>
crabbox attach <run_id> --after <seq>
crabbox events <run_id> --after <seq> --limit 100
crabbox events <run_id> --json
crabbox logs <run_id>
crabbox results <run_id>

안정적인 기계 판독 가능 타이밍 레코드가 필요할 때 run, warmup 및 actions hydrate에 --timing-json을 사용하세요. 명령은 stdout 또는 stderr에 마커를 출력하여 하위 단계를 표시할 수 있습니다:

echo CRABBOX_PHASE:install
pnpm install --frozen-lockfile
echo CRABBOX_PHASE:test
pnpm test

출력 이벤트는 상한 미리보기입니다. 보존된 출력 테일에는 logs를, 구문 분석된 테스트 요약에는 results를 사용하세요.

데스크톱, WebVNC 및 UI 증명

시각적 QA, 헤드 브라우저 자동화 또는 UI 증명을 위한 데스크톱/브라우저 리스를 생성하세요:

crabbox warmup --desktop --browser
crabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env wayland
crabbox warmup --provider aws --os ubuntu:26.04 --desktop --browser --desktop-env gnome

ubuntu:26.04는 프로바이더 카탈로그가 지원하는 기본 이식 가능한 Linux OS 선택기입니다. 테스트가 이전 LTS에 있어야 하는 경우에만 --os ubuntu:24.04를 사용하세요. 명시적인 프로바이더 이미지 플래그는 여전히 --os보다 우선합니다.

인간 데모의 경우, crabbox webvnc --open이 브라우저 조각에 리스 암호를 미리 로드하므로 네이티브 VNC보다 WebVNC를 선호하세요:

crabbox webvnc --id <lease> --open --take-control
crabbox webvnc status --id <lease>
crabbox webvnc reset --id <lease> --open --take-control
crabbox vnc --id <lease> --open

입력 자동화의 경우, 수동 xdotool 대신 일급 헬퍼를 사용하세요:

crabbox desktop doctor --id <lease>
crabbox desktop launch --id <lease> --browser --url https://example.com --webvnc --open --take-control
crabbox desktop click --id <lease> --x 640 --y 420
crabbox desktop paste --id <lease> --text "[email protected]"
printf '[email protected]' | crabbox desktop paste --id <lease>
crabbox desktop type --id <lease> --text "[email protected]"
crabbox desktop key --id <lease> ctrl+l
crabbox screenshot --id <lease> --output desktop.png

데스크톱/WebVNC가 멈춘 경우, 인라인 복구 출력을 먼저 신뢰하세요: problem: 및 rescue: 줄은 일반적으로 webvnc status/reset, desktop doctor 또는 네이티브 vnc --open과 같은 정확한 다음 명령을 지정합니다.

UI QA 증명을 위해 제품 저장소 브랜치에 스크린샷이나 비디오를 커밋하는 대신 아티팩트를 사용하세요:

crabbox artifacts collect --id <lease> --all --output artifacts/<slug>
crabbox artifacts publish --dir artifacts/<slug> --pr <number>
crabbox artifacts list <artifact-manifest-url-or-dir>
crabbox artifacts pull <artifact-manifest-url-or-dir> --output /tmp/<slug>-proof

artifacts publish는 설정된 경우 브로커 저장소를 사용하거나 명시적인 S3/R2 / Cloudflare/로컬 호스팅 플래그를 사용합니다. 생성된 Markdown 또는 저장소 명령을 검토할 때 공개 PR 댓글 전에 --dry-run을 사용하세요.

프로바이더 경계

SSH 리스 프로바이더는 대상이 지원할 때 전체 동기화/실행 표면(스크립트, 신규 PR 체크아웃, 캡처, 다운로드, Actions 하이드레이션, SSH, 포트, WebVNC, code-server, 데스크톱, 브라우저, 캐시 볼륨 및 정리)을 지원합니다.

위임된 실행 프로바이더는 명령 전송을 소유합니다. crabbox providers --json 및 프로바이더 문서가 일치하는 기능을 광고하지 않는 한, SSH 실행 기능(--capture-stdout, --capture-stderr, --capture-on-fail, --script, --script-stdin, --fresh-pr, 로컬 캡처, --download, --full-resync, --env-helper)을 거부할 것으로 예상하세요. --keep-on-failure는 Crabbox가 실패한 명령 후 중지할 원샷 위임 프로바이더에게 여전히 유용합니다.

모듈 런타임 위임 프로바이더는 특정 제한 사항이 있을 수 있습니다. 자세한 내용은 프로바이더 문서를 확인하세요.