crabbox-cli

Recipe card from the charly-tools plugin (Images — the deployable catalog).

crabbox-cli

Candy Properties

Property	Value
Binary	`/usr/local/bin/crabbox`
Source	pinned `opencharly/crabbox` COMMIT (`CRABBOX_COMMIT` var), built with `go build -trimpath ./cmd/crabbox`
Version	the pinned commit, injected with `-X github.com/openclaw/crabbox/internal/cli.version=<commit>`
Install	ONE `command:` step: curl the commit’s tarball → extract → `go build` (CGO disabled) → discard the tree in the same RUN
Requires	`layer-golang` (the Go toolchain), `layer-gh` (git), `layer-ssh-client` (ssh/ssh-keygen), rsync + curl packages
Alias	`crabbox` (wrapper runs in-box via `charly alias`)
Config sibling	`crabbox-containerd-config` — `provider: containerd` + `containerd.image`

What it installs

A single static Go binary BUILT from the opencharly/crabbox commit pinned in CRABBOX_COMMIT. The fetch and the build are ONE command: step: the tarball is downloaded, extracted to a temp dir, compiled, and the temp dir is removed by a trap in the same RUN — the source never becomes image content. The source build is not an optimization: no openclaw/crabbox release carries the containerd SSH-lease provider, so a downloaded 0.79.0 asserts a CLI that cannot lease on containerd. The version string IS the commit, so crabbox --version names the source the binary came from. Prerequisites for the CLI’s lease/sync machinery (git, ssh, ssh-keygen, rsync, curl) come from composed candies/packages — never re-shipped.

Verification

The candy’s plan: ships deterministic check: steps: the binary lands at /usr/local/bin/crabbox, crabbox --version reports the pinned commit, crabbox providers lists the containerd provider, crabbox providers describe containerd succeeds, and the config candy’s rendered file is read back by crabbox config show. The repo’s bed check-crabbox-cli runs all of them in a disposable container. crabbox doctor is deliberately not an image check: it judges the LIVE provider’s prerequisites (daemon/broker), which a build container does not have — a venue’s readiness belongs to a live bed (the crabbox: verb’s containerd-preflight).

Provider surface (no cloud credentials)

Provider	Notes
`containerd` (alias `nerdctl`)	SSH leases as containers on a local or remote containerd daemon (crun/krun/runc runtimes, overlayfs/native/fuse-overlayfs/btrfs snapshotters)
`local-container` (aliases `docker`/`container`/`local-docker`)	SSH leases as a local container (Podman/Docker); sync/run/logs/artifacts + `--desktop`/`--browser` capabilities
`ssh` (`static`/`static-ssh`)	existing machines
`external` (`exec-provider`)	an executable implementing the crabbox provider protocol
cloud (aws/azure/gcp/hetzner/daytona/…)	direct modes with operator credentials; documented-only

Opt out of the explicit lease hostname for runtimes that share the host UTS namespace via localContainer.noHostname: true in ~/.config/crabbox/config.yaml (or CRABBOX_LOCAL_CONTAINER_NO_HOSTNAME=1) — a fixed lease ID conflicts when the setting changes between acquisitions.

The containerd config candy

crabbox-containerd-config is a SEPARATE candy, referenced by path (@github.com/opencharly/layer-crabbox/crabbox-containerd-config:<tag>). The root ref’s STRING is unchanged, but the resolved candy is named layer-crabbox (the ref leaf), so a consumer that composes it by NAME follows the rename. It renders ~/.config/crabbox/config.yaml through the config: verb, validated against plugin-egress’s crabbox-yaml schema:

provider: containerd
containerd:
    image: ghcr.io/opencharly/pod-crabbox:2026.293.1655

CRABBOX_CONTAINERD_IMAGE is the lease image. A host that does not have it fails the lease with that exact ref; the crabbox: verb’s containerd-preflight reports it as a visible SKIP before anything is leased.

Install on a dev host / box

charly deploy add crabbox crabbox --target local   # installs /usr/local/bin/crabbox
charly alias install <box>                        # alias wrapper
crabbox providers describe containerd             # the source build's provider
crabbox doctor --provider containerd              # provider selection + host prerequisites

Cross-References

/charly-check:crabbox — the crabbox: verb’s methods, including describe and containerd-preflight.
/charly-image:layer — the candy authoring surface.
/charly-check:check — plan authoring + ADE.
Upstream Crabbox + its own skills/crabbox agent skill (referenced, not duplicated — R3).

When to Use This Skill

Invoke when composing the crabbox CLI into a box, selecting the containerd provider and its lease image, or verifying a crabbox installation.