openclaw/crabbox

O que crabbox faz?

Use o Crabbox quando um projeto precisar de prova remota, maior capacidade de nuvem, um checkout limpo de PR, uma caixa aquecida reutilizável, configuração no estilo GitHub Actions, logs/resultados duráveis, artefatos de prova de UI, ou sincronização a partir de um checkout local sujo.

Detectar Crabbox

• Trate crabbox.yaml ou .crabbox.yaml na raiz do repositório como um sinal intencional para usar esta skill para trabalho de validação. .crabbox.yml não é um nome de arquivo de configuração suportado.
• Se nenhum dos dois arquivos de configuração existir, command -v crabbox ainda identifica uma CLI instalada. Execute crabbox doctor antes de depender dela para trabalho remoto.
• Inspecione a configuração antes de executá-la. A detecção não implica permissão para expor segredos, ignorar a aprovação de comandos ou iniciar infraestrutura paga.

Fonte Da Verdade

• Execute o Crabbox a partir da raiz do repositório; a sincronização espelha o checkout atual.
• Trate crabbox.yaml ou .crabbox.yaml local no repositório como automação executável do projeto. Revise-o antes de execuções remotas, especialmente provider, actions, jobs, profiles, env.allow, artefatos e política de limpeza.
• Verifique o binário instalado antes de confiar nos exemplos: command -v crabbox && crabbox --version && crabbox --help | sed -n '1,120p'.
• Use crabbox providers ou crabbox providers --json para a matriz atual de provedores/capacidades; a documentação do provedor pode ficar desatualizada em relação ao binário compilado.
• Use crabbox doctor para verificações de prontidão em tempo real e crabbox config show para inspecionar a configuração mesclada sem imprimir segredos.
• Prefira testes locais direcionados para ciclos rápidos de edição. Mude para o Crabbox para suítes amplas, verificações pesadas de pacotes, provas Docker/E2E/provedor vivo, provas entre sistemas operacionais, provas de UI ou comandos que sobrecarregam a máquina local.

Autenticação E Configuração

A operação intermediada precisa de uma URL de coordenador e um token. O primeiro login geralmente precisa de uma URL de intermediário explícita:

crabbox login --url <url-do-intermediario>
crabbox whoami
crabbox doctor

Após broker.url estar configurado, crabbox login pode reutilizá-lo. A automação de operador confiável pode armazenar um token compartilhado sem colocá-lo em argv:

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

A precedência de configuração é flags > env > config do repo > config do usuário > padrões. O caminho padrão da config do usuário é ~/Library/Application Support/crabbox/config.yaml no macOS, ~/.config/crabbox/config.yaml no Linux, ou $XDG_CONFIG_HOME/crabbox/config.yaml quando definido. crabbox config path imprime o caminho ativo da config do usuário.

Mantenha tokens de provedor e intermediário fora da configuração do repositório e dos argumentos de comando. Use variáveis de ambiente, um armazenamento de credenciais, segredos gerenciados pelo coordenador ou um comando de token de curta duração.

Escolher A Superfície Remota

• crabbox run -- <comando>: um comando em uma caixa nova ou reutilizada.
• crabbox warmup: criar uma concessão reutilizável e executar comandos depois com --id.
• crabbox prewarm: aquecer uma concessão reutilizável e hidratá-la a partir de GitHub Actions configurados.
• crabbox job run <nome>: usar um fluxo nomeado local no repositório que se expande para warmup, hidratação opcional, execução e parada.
• crabbox run --pool <chave>: pegar emprestada uma concessão hidratada de um pool pronto do intermediário, executar e depois retornar/drenar/liberar de acordo com --pool-return.
• crabbox run --fresh-pr ...: ignorar a sincronização local e fazer checkout de um PR do GitHub no remoto; adicionar --apply-local-patch para testar alterações locais não confirmadas em cima desse PR.
• crabbox run --provider ssh: usar um host macOS, Linux ou Windows existente.
• crabbox warmup --desktop --browser: provisionar uma área de trabalho/navegador visível para testes de UI, WebVNC, capturas de tela e artefatos.

Se a prova remota estiver bloqueada, nomeie precisamente a capacidade ausente: autenticação, coordenador, capacidade, suporte do provedor, SO alvo, hidratação, acesso a segredos, armazenamento de artefatos, suporte a área de trabalho ou uma limitação do provedor delegado.

Prova Remota Comum

Comando único:

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

Aquecer e reutilizar uma concessão:

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

Usar um job local no repositório quando configurado:

crabbox job list
crabbox job run --dry-run <nome-do-job>
crabbox job run <nome-do-job>
crabbox job run --id <cbx_id-ou-slug> <nome-do-job>

Usar uma concessão de pool pronto quando o coordenador tiver capacidade de pool hidratada:

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

Usar hidratação do GitHub Actions quando o repositório já possui configuração em CI:

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

Use --github-runner apenas quando o workflow precisar de semânticas completas do GitHub Actions, como segredos do repositório, OIDC, contêineres de serviço, contêineres de job ou etapas uses: não suportadas:

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

Sincronização E Checkouts Novos

A sincronização normal transfere arquivos rastreados mais arquivos não rastreados e não ignorados, exclui saída de dependência/build/cache ignorada, honra .crabboxignore e sync.exclude, semeia o checkout remoto a partir de origin quando possível e pula rsync quando a impressão digital de sincronização corresponde.

Use crabbox sync-plan antes de execuções grandes. Contagens inesperadas geralmente significam crescimento local gerado; atualize .crabboxignore ou sync.exclude em vez de forçar uploads enormes.

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

Use checkout de PR novo quando o crescimento local de dependências ou a sincronização suja puderem confundir o resultado:

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

--fresh-pr aceita owner/repo#numero, URLs de PR do GitHub, ou um número de PR da origin atual do GitHub. Hosts que não são GitHub são rejeitados. Checkout de PR novo é um recurso de sincronização executado via SSH; provedores delegados o rejeitam. Destinos Windows SSH nativos são suportados.

Quando uma concessão aquecida parecer obsoleta, prefira --full-resync (alias --fresh-sync) para redefinir o diretório de trabalho remoto, pular o caminho rápido da impressão digital de sincronização, ressembrar o Git quando possível e fazer upload do checkout do zero.

Scripts, Shells E Destinos Windows

Use argv simples após -- para um executável. Use --shell para trechos de shell com várias instruções, pipes ou expansão de shell:

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

Prefira scripts enviados para comandos de várias linhas. Scripts são incluídos em pacotes de falha e evitam strings de shell frágeis com aspas:

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

Destinos Windows nativos usam PowerShell e sincronização de manifesto baseada em tar. Prefira argv simples para um executável como dotnet test; use --shell para PowerShell com várias instruções e --script <arquivo.ps1> para scripts mais longos.

Concessões Windows Hyper-V

hyperv precisa de um VHDX Generation 2, DHCP e uma senha de administrador local conhecida na configuração confiável ou em CRABBOX_HYPERV_GUEST_PASSWORD. Ele instala pacotes OpenSSH e MinGit fixados e verificados quando ausentes, usando PowerShell Direct. Consulte docs/providers/hyperv.md para detalhes do modelo e ciclo de vida.

Para testes de provedor, prefira um executor headless elevado; falhas precoces do PowerShell Direct podem mostrar uma UI de credenciais. Mantenha senhas fora de argumentos e logs, e verifique se a concessão se torna pronta, executa via SSH e é liberada.

Segredos E Encaminhamento De Ambiente

O Crabbox não encaminha todo o ambiente local. O encaminhamento é baseado em nome: apenas nomes na lista de permissões que estão realmente definidos localmente ou em um perfil permitido cruzam a fronteira. Evite colocar nomes com formato de segredo na lista de permissões, a menos que a execução seja um teste de fumaça explícito com segredos vivos.

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 analisa linhas simples export NOME=valor e NOME=valor sem executar o perfil. O Crabbox imprime metadados de presença/comprimento ocultos, não valores. Concessões SSH POSIX podem persistir um auxiliar para comandos posteriores em uma concessão que você controla:

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

O auxiliar gerado e o perfil de segredo correspondente permanecem no diretório de trabalho remoto até a limpeza, redefinição da concessão ou --full-resync; não persista auxiliares em concessões compartilhadas ou não confiáveis.

Perfis, Predefinições, Prova E Resultados

A configuração do repositório pode definir perfis, predefinições, requisitos de diagnóstico, globs de artefatos, artefatos obrigatórios e modelos de prova. Use-os para faixas de validação estáveis em vez de codificar conhecimento do projeto em prompts de agente.

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

Use --preflight para um instantâneo da capacidade alvo antes do comando, não como um instalador. Use --preflight-tools para ajustar as sondas:

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

Anexe resultados estruturados e artefatos de prova quando o comando os emitir:

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 falha na execução se o comando remoto sair com 0, mas o arquivo de prova estiver faltando. Mantenha os artefatos obrigatórios limitados e limpos; não colete conjuntos de dados brutos, segredos, credenciais, URLs assinadas ou linhas de clientes não ocultas.

Identificadores De Execução E Observabilidade

Execuções apoiadas pelo coordenador imprimem um identificador run_... durável antes do início da concessão. Mantenha esse ID de execução em atualizações de status e notas de PR.

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

Use --timing-json em run, warmup e actions hydrate quando um registro de tempo estável e legível por máquina for necessário. Comandos podem marcar subfases imprimindo marcadores em stdout ou stderr:

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

Eventos de saída são visualizações limitadas. Use logs para caudas de saída retidas e results para resumos de teste analisados.

Área De Trabalho, WebVNC E Prova De UI

Crie concessões com área de trabalho/navegador para QA visual, automação de navegador com cabeçalho ou prova de 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 é o seletor de SO Linux portátil padrão onde o catálogo do provedor o suporta. Use --os ubuntu:24.04 apenas quando um teste precisar permanecer no LTS anterior. Sinalizadores de imagem de provedor explícitos ainda ganham de --os.

Para demonstrações humanas, prefira WebVNC em vez de VNC nativo porque crabbox webvnc --open pré-carrega a senha da concessão no fragmento do navegador:

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

Para automação de entrada, use auxiliares de primeira classe em vez de xdotool escrito à mão:

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

Quando a área de trabalho/WebVNC travar, confie primeiro na saída de resgate embutida: linhas problem: e rescue: geralmente nomeiam os próximos comandos exatos, como webvnc status/reset, desktop doctor ou vnc --open nativo.

Use artefatos para prova de UI QA em vez de confirmar capturas de tela ou vídeos em um branch do repositório do produto:

crabbox artifacts collect --id <concessao> --all --output artifacts/<slug>
crabbox artifacts publish --dir artifacts/<slug> --pr <numero>
crabbox artifacts list <url-do-manifesto-de-artefato-ou-dir>
crabbox artifacts pull <url-do-manifesto-de-artefato-ou-dir> --output /tmp/<slug>-proof

artifacts publish usa armazenamento intermediado quando configurado, ou sinalizadores explícitos de hospedagem S3/R2 / Cloudflare/local. Use --dry-run antes de comentários públicos em PR ao revisar Markdown gerado ou comandos de armazenamento.

Limites Do Provedor

Provedores de concessão SSH suportam toda a superfície de sincronização/execução quando o alvo suporta: scripts, checkouts de PR novos, capturas, downloads, hidratação do Actions, SSH, portas, WebVNC, code-server, área de trabalho, navegador, volumes de cache e limpeza.

Provedores de execução delegada possuem o transporte do comando. Espere que eles rejeitem recursos executados via SSH, como --capture-stdout, --capture-stderr, --capture-on-fail, --script, --script-stdin, --fresh-pr, capturas locais, --download, --full-resync e --env-helper, a menos que crabbox providers --json e a documentação do provedor anunciem a capacidade correspondente. --keep-on-failure ainda é útil para provedores delegados de uso único que o Crabbox interromperia após um comando com falha.

Provedores delegados de tempo de execução de módulo, como runners de contêiner sem suporte SSH, rejeitam tudo que não seja argv simples, resultados de saída e códigos de saída. Para esses provedores, use crabbox run -- <comando> com globs de artefatos e listas de permissões de ambiente. Provedores gêmeos que também oferecem concessões SSH hospedadas anunciam capacidades SSH separadamente; verifique a saída JSON do provedor para has_ssh_lease.