plugin-crabbox

Placement	runtime (out-of-process over gRPC)
Source	github.com/opencharly/plugin-crabbox/candy/plugin-crabbox
Version	2026.250.0100
Candy	plugin-crabbox

This plugin is not listed in charly/charly.yml’s compiled_plugins:. It is not part of the shipped binary: charly builds and loads it out-of-process over gRPC when a plan references one of its words (the coexist path).

Providers

The reserved words this plugin serves:

• crabbox — verb class

What it does

OUT-OF-TREE charly plugin serving the crabbox check verb — a standalone Go module (go.mod + main.go) that probes the Crabbox CLI and its optional local coordinator, served OUT-OF-PROCESS over go-plugin gRPC via the charly plugin SDK (github.com/opencharly/sdk). charly’s loader fetches this candy’s repo, go-builds the provider binary on the HOST, and serves it via LocalTransport — so an authored crabbox: step dispatches through the provider registry exactly like a built-in.

The verb has THREE method classes. In-venue CLI methods (version/providers/ config/doctor — credential-free — and leases/usage/events/logs — broker-backed, requiring a crabbox login in the venue) run the crabbox binary INSIDE the venue over the reverse channel (cc.Exec). Coordinator HTTP probe methods (health/ready) hit the Node.js/PostgreSQL coordinator’s /v1/health and /v1/ready endpoints — the container-probe surface the coordinator exposes — from the charly host against the resolved endpoint (cc.ResolveEndpoint + cc.HTTPDo, one authored step works unchanged against a pod’s published port and a VM’s forwarded one). All methods are read-only; there are no mutating methods in this first cut.

It is NOT a re-skin of the generic command:/http: verbs: this plugin exists for what those structurally cannot do — ENDPOINT RESOLUTION (cc.ResolveEndpoint for the coordinator probes) and DOMAIN SEMANTICS (methods map to the crabbox CLI’s real surface and return real verdicts, with json_path: to assert one field; the in-venue CLI methods reach the binary where it is installed, which http: cannot).

The R10 consumers are the crabbox-bearing beds (check-crabbox-pod and check-crabbox-e2e-pod) whose checks compose this plugin alongside the crabbox CLI candy from opencharly/layer-crabbox and the coordinator candy from opencharly/pod-crabbox.

Parameter schema

The CUE schema below is the authoritative grammar for this plugin’s input. It is the same single source that generates the plugin’s Go parameter types and answers the runtime Describe RPC, so this page cannot disagree with either.

schema/crabbox.cue

// The `crabbox` plugin's OWN CUE schema — the typed plugin_input for the
// `crabbox` check verb, which probes the Crabbox CLI and its optional local
// Node.js/PostgreSQL coordinator: in-venue CLI methods (credential-free
// version/providers/config/doctor; broker-backed leases/usage/events/logs) and
// coordinator HTTP probe methods (health/ready).
//
// SELF-CONTAINED by contract: it references NO base def, so it compiles standalone
// (both `cue exp gengotypes` and the host's load-gate compile) AND splices onto the
// base as `base ++ plugin`.
//
// Single source, used two ways:
//  1. GENERATE ../params/cue_types_gen.go via `cue exp gengotypes`, so the provider
//     decodes plugin_input into a TYPED struct rather than a hand-parsed map.
//  2. VALIDATE authored input AT RUNTIME — served over Describe, spliced by the host,
//     and every authored `crabbox:` step's plugin_input checked against #CrabboxInput.
#CrabboxInput: {
  // method — the operation (also the scalar-sugar primary, so `crabbox: version`
  // desugars to {method: "version"}).
  //
  // In-venue CLI methods (version/providers/config/doctor/leases/usage/events/logs)
  // run inside the venue where the `crabbox` binary is installed; coordinator HTTP
  // probe methods (health/ready) are issued from the charly HOST against the
  // resolved coordinator endpoint. All are read-only — there are no mutating
  // methods in this first cut.
  method: "version" | "providers" | "config" | "doctor" | "health" | "ready" | "leases" | "usage" | "events" | "logs"

  // port — the coordinator port to probe for health/ready. Default 8080 (the
  // crabbox-coordinator candy's published port).
  port?: int & >0 & <65536

  // timeout — the HTTP probe timeout. Default 10s.
  timeout?: string & =~"^[0-9]+s$"

  // json_path — a dotted path into the JSON response; when set, the verb's stdout is
  // the value at that path rather than the whole document, so a `stdout:` matcher can
  // assert one field without pattern-matching a blob.
  json_path?: string @go(JSONPath)

  // run_id — run identifier required by the events/logs methods.
  run_id?: string
}

---

See also the candy reference for this candy’s install surface.