openclaw/crabbox

Que fait crabbox ?

Utilisez Crabbox lorsqu'un projet a besoin d'une preuve distante, d'une capacité cloud plus importante, d'un checkout frais de PR, d'une box réutilisable préchauffée, d'une configuration de type GitHub Actions, de logs/ résultats durables, d'artefacts de preuve d'interface utilisateur, ou d'une synchronisation à partir d'un checkout local non commité.

Détecter Crabbox

• Traitez le fichier crabbox.yaml ou .crabbox.yaml à la racine du dépôt comme un signal intentionnel d'utiliser cette compétence pour le travail de validation. .crabbox.yml n'est pas un nom de fichier de configuration pris en charge.
• Si aucun des fichiers de configuration n'existe, command -v crabbox identifie toujours une CLI installée. Exécutez crabbox doctor avant de dépendre de l'outil pour un travail distant.
• Inspectez la configuration avant de l'exécuter. La détection n'implique pas l'autorisation d'exposer des secrets, de contourner l'approbation des commandes ou de démarrer une infrastructure payante.

Source de vérité

• Exécutez Crabbox depuis la racine du dépôt ; la synchronisation reflète le checkout actuel.
• Traitez le fichier crabbox.yaml ou .crabbox.yaml local du dépôt comme une automatisation de projet exécutable. Examinez-le avant les exécutions distantes, en particulier provider, actions, jobs, profiles, env.allow, les artefacts et la politique de nettoyage.
• Vérifiez le binaire installé avant de vous fier aux exemples : command -v crabbox && crabbox --version && crabbox --help | sed -n '1,120p'.
• Utilisez crabbox providers ou crabbox providers --json pour la matrice actuelle des fournisseurs/capacités ; la documentation du fournisseur peut être en retard par rapport au binaire compilé.
• Utilisez crabbox doctor pour les vérifications de disponibilité en direct et crabbox config show pour inspecter la configuration fusionnée sans afficher les secrets.
• Préférez les tests locaux ciblés pour les boucles d'édition serrées. Passez à Crabbox pour les suites larges, les vérifications lourdes en termes de paquets, les preuves Docker/E2E/fournisseur en direct, les preuves multiplateformes, les preuves d'interface utilisateur, ou les commandes qui ralentissent la machine locale.

Authentification et configuration

Une opération négociée (brokered) nécessite une URL de coordinateur et un jeton. La première connexion nécessite généralement une URL de courtier explicite :

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

Après que broker.url est configuré, crabbox login peut le réutiliser. L'automatisation d'un opérateur de confiance peut stocker un jeton partagé sans le mettre sur argv :

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

La priorité de configuration est flags > env > configuration du dépôt > configuration utilisateur > valeurs par défaut. La configuration utilisateur par défaut est ~/Library/Application Support/crabbox/config.yaml sur macOS, ~/.config/crabbox/config.yaml sur Linux, ou $XDG_CONFIG_HOME/crabbox/config.yaml lorsqu'elle est définie. crabbox config path affiche le chemin actif de la configuration utilisateur.

Gardez les jetons de fournisseur et de courtier en dehors de la configuration du dépôt et des arguments de commande. Utilisez des variables d'environnement, un magasin d'informations d'identification, des secrets gérés par le coordinateur, ou une commande de jeton à courte durée de vie.

Choisir la surface distante

• crabbox run -- <commande> : une commande sur une box fraîche ou réutilisée.
• crabbox warmup : crée un bail réutilisable et exécute des commandes plus tard avec --id.
• crabbox prewarm : chauffe un bail réutilisable et l'hydrate à partir de GitHub Actions configuré.
• crabbox job run <nom> : utilise un flux nommé local au dépôt qui se développe en warmup, hydratation optionnelle, exécution et arrêt.
• crabbox run --pool <clé> : emprunte un bail hydraté d'un pool prêt du courtier, exécute, puis retourne/draine/libère selon --pool-return.
• crabbox run --fresh-pr ... : ignore la synchronisation locale et extrait une PR GitHub sur le distant ; ajoutez --apply-local-patch pour tester les modifications locales non commitées en plus de cette PR.
• crabbox run --provider ssh : utilise un hôte macOS, Linux ou Windows existant.
• crabbox warmup --desktop --browser : provisionne un bureau/navigateur visible pour les tests d'interface utilisateur, WebVNC, captures d'écran et artefacts.

Si la preuve distante est bloquée, nommez précisément la capacité manquante : authentification, coordinateur, capacité, support du fournisseur, OS cible, hydratation, accès aux secrets, stockage d'artefacts, support du bureau, ou une limitation du fournisseur délégué.

Preuve distante courante

Commande unique :

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

Chauffer et réutiliser un bail :

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>

Utiliser un job local au dépôt lorsqu'il est configuré :

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

Utiliser un bail d'un pool prêt lorsque le coordinateur dispose d'une capacité de pool hydratée :

crabbox pool ready
crabbox run --pool <clé-du-pool> -- pnpm test
crabbox run --pool <clé-du-pool> --pool-return drain -- pnpm test:flaky

Utiliser l'hydratation GitHub Actions lorsque le dépôt possède déjà une configuration dans CI :

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

Utilisez --github-runner uniquement lorsque le workflow a besoin de la sémantique complète de GitHub Actions, telle que les secrets du dépôt, OIDC, les conteneurs de service, les conteneurs de job, ou les étapes uses: non prises en charge :

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

Synchronisation et checkouts frais

La synchronisation normale transfère les fichiers suivis ainsi que les fichiers non suivis non ignorés, exclut les sorties de dépendances/construction/cache ignorées, respecte .crabboxignore et sync.exclude, amorce le checkout distant à partir de origin lorsque c'est possible, et saute rsync lorsque l'empreinte de synchronisation correspond.

Utilisez crabbox sync-plan avant les grandes exécutions. Des comptes inattendus signifient généralement un changement généré localement ; mettez à jour .crabboxignore ou sync.exclude au lieu de forcer des téléchargements volumineux.

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

Utilisez un checkout de PR frais lorsque le changement local des dépendances ou une synchronisation sale perturberait le résultat :

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

--fresh-pr accepte propriétaire/dépôt#numéro, les URL de PR GitHub, ou un numéro de PR provenant de l'origine GitHub actuelle. Les hôtes non GitHub sont rejetés. Le checkout de PR frais est une fonctionnalité de synchronisation exécutée via SSH ; les fournisseurs délégués le rejettent. Les cibles SSH Windows natives sont prises en charge.

Lorsqu'un bail chaud sent le rance, préférez --full-resync (alias --fresh-sync) pour réinitialiser le répertoire de travail distant, sauter le chemin rapide de l'empreinte de synchronisation, réamorcer Git lorsque c'est possible, et télécharger le checkout à partir de zéro.

Scripts, shells et cibles Windows

Utilisez argv simple après -- pour un seul exécutable. Utilisez --shell pour des extraits de shell multi-instructions, des pipes, ou l'expansion du shell :

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

Préférez les scripts téléchargés pour les commandes multi-lignes. Les scripts sont inclus dans les bundles d'échec et évitent les chaînes shell entre guillemets fragiles :

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

Les cibles Windows natives utilisent PowerShell et la synchronisation de manifeste basée sur tar. Préférez argv simple pour un seul exécutable tel que dotnet test ; utilisez --shell pour PowerShell multi-instructions et --script <fichier.ps1> pour les scripts plus longs.

Baux Windows Hyper-V

hyperv a besoin d'un VHDX de génération 2, DHCP et d'un mot de passe d'administrateur local connu dans la configuration de confiance ou CRABBOX_HYPERV_GUEST_PASSWORD. Il installe des paquets OpenSSH et MinGit épinglés et vérifiés lorsqu'ils sont manquants, en utilisant PowerShell Direct. Voir docs/providers/hyperv.md pour le modèle et les détails du cycle de vie.

Pour les tests de fournisseur, préférez un exécuteur sans tête élevé ; les échecs précoces de PowerShell Direct peuvent afficher l'interface utilisateur des informations d'identification. Gardez les mots de passe hors des arguments et des logs, et vérifiez que le bail devient prêt, s'exécute via SSH et se libère.

Transfert de secrets et d'environnement

Crabbox ne transfère pas tout l'environnement local. Le transfert est basé sur le nom : seuls les noms autorisés qui sont réellement définis localement ou dans un profil autorisé traversent la frontière. Évitez d'autoriser des noms en forme de secret à moins que l'exécution ne soit un test de fumée de secret en direct explicite.

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 analyse les lignes simples export NOM=valeur et NOM=valeur sans exécuter le profil. Crabbox imprime les métadonnées de présence/longueur masquées, pas les valeurs. Les baux SSH POSIX peuvent conserver un assistant pour des commandes ultérieures sur un bail que vous contrôlez :

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

L'assistant généré et le profil secret correspondant restent dans le répertoire de travail distant jusqu'au nettoyage, à la réinitialisation du bail, ou à --full-resync ; ne persistez pas les assistants sur des baux partagés ou non fiables.

Profils, préréglages, preuves et résultats

La configuration du dépôt peut définir des profils, des préréglages, des exigences de doctor, des globs d'artefacts, des artefacts requis et des modèles de preuve. Utilisez-les pour des voies de validation stables au lieu de coder les connaissances du projet dans les invites de l'agent.

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

Utilisez --preflight pour un instantané des capacités cibles avant la commande, pas comme un installateur. Utilisez --preflight-tools pour affiner les sondes :

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

Attachez des résultats structurés et des artefacts de preuve lorsque la commande les émet :

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 échoue l'exécution si la commande distante se termine avec le code 0 mais que le fichier de preuve est manquant. Gardez les artefacts requis limités et nettoyés ; ne collectez pas de jeux de données bruts, de secrets, d'informations d'identification, d'URL signées ou de lignes client non masquées.

Identifiants d'exécution et observabilité

Les exécutions soutenues par le coordinateur impriment un identifiant run_... durable avant le début du bail. Gardez cet ID d'exécution dans les mises à jour de statut et les notes de PR.

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>

Utilisez --timing-json sur run, warmup et actions hydrate lorsqu'un enregistrement de synchronisation stable et lisible par machine est nécessaire. Les commandes peuvent marquer des sous-phases en imprimant des marqueurs sur stdout ou stderr :

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

Les événements de sortie sont des aperçus plafonnés. Utilisez logs pour les queues de sortie conservées et results pour les résumés de test parsés.

Bureau, WebVNC et preuve d'interface utilisateur

Créez des baux de bureau/navigateur pour l'assurance qualité visuelle, l'automatisation du navigateur avec tête, ou la preuve d'interface utilisateur :

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 est le sélecteur d'OS Linux portable par défaut lorsque le catalogue du fournisseur le prend en charge. Utilisez --os ubuntu:24.04 uniquement lorsqu'un test doit rester sur l'ancienne LTS. Les indicateurs d'image de fournisseur explicites l'emportent toujours sur --os.

Pour les démonstrations humaines, préférez WebVNC au VNC natif car crabbox webvnc --open précharge le mot de passe du bail dans le fragment du navigateur :

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

Pour l'automatisation des entrées, utilisez des assistants de première classe au lieu de xdotool écrit à la main :

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

Lorsque le bureau/WebVNC se bloque, fiez-vous d'abord à la sortie de sauvetage en ligne : les lignes problem: et rescue: nomment généralement les prochaines commandes exactes telles que webvnc status/reset, desktop doctor, ou vnc --open natif.

Utilisez des artefacts pour la preuve de l'assurance qualité de l'interface utilisateur au lieu de valider des captures d'écran ou des vidéos dans une branche du dépôt de produit :

crabbox artifacts collect --id <bail> --all --output artifacts/<slug>
crabbox artifacts publish --dir artifacts/<slug> --pr <numéro>
crabbox artifacts list <url-ou-dossier-du-manifeste-d-artefact>
crabbox artifacts pull <url-ou-dossier-du-manifeste-d-artefact> --output /tmp/<slug>-preuve

artifacts publish utilise le stockage négocié lorsqu'il est configuré, ou des indicateurs explicites S3/R2 / Cloudflare/hébergement local. Utilisez --dry-run avant les commentaires publics de PR lors de l'examen du Markdown généré ou des commandes de stockage.

Limites des fournisseurs

Les fournisseurs de baux SSH prennent en charge toute la surface de synchronisation/exécution lorsque la cible le permet : scripts, checkouts de PR frais, captures, téléchargements, hydratation Actions, SSH, ports, WebVNC, code-server, bureau, navigateur, volumes de cache et nettoyage.

Les fournisseurs d'exécution déléguée possèdent le transport de commandes. Attendez-vous à ce qu'ils rejettent les fonctionnalités d'exécution SSH telles que --capture-stdout, --capture-stderr, --capture-on-fail, --script, --script-stdin, --fresh-pr, les captures locales, --download, --full-resync et --env-helper à moins que crabbox providers --json et la documentation du fournisseur n'annoncent la capacité correspondante. --keep-on-failure est toujours utile pour les fournisseurs délégués uniques que Crabbox arrêterait autrement après une commande ayant échoué.

Les fournisseurs délégués de runtime de module, en fonction du fournisseur, peuvent avoir des limites supplémentaires concernant l'accès au réseau, les systèmes de fichiers, ou les permissions de l'utilisateur exécutant. Consultez la documentation spécifique du fournisseur pour plus de détails.