OpenClaw Plugin

Read when:

enabling Crabbox as a plugin inside OpenClaw;
changing the plugin tools, schema, or wrapper behavior;
understanding why some Crabbox surfaces are CLI-only and not plugin tools.

The Crabbox repository root is also a native OpenClaw plugin package. When OpenClaw loads the plugin, it exposes a small set of agent tools that shell out to the user's installed crabbox binary. The plugin does not embed the CLI or duplicate any of its logic - it is a thin contract for safe, allowlisted invocations.

#Plugin Manifest

openclaw.plugin.json declares the plugin id, the tools it owns, and the config schema:

{
  "id": "crabbox",
  "name": "Crabbox",
  "description": "Run Crabbox remote testbox checks from OpenClaw.",
  "activation": { "onStartup": true },
  "contracts": {
    "tools": [
      "crabbox_run",
      "crabbox_warmup",
      "crabbox_status",
      "crabbox_list",
      "crabbox_stop"
    ]
  },
  "configSchema": { ... }
}

The runtime entrypoint is index.js. Tests in index.test.js lock the tool schemas, argv shapes, output trimming, and config validation so a future refactor cannot silently change the agent-facing contract.

#Tools

crabbox_run      run a command on a leased remote box
crabbox_warmup   acquire a warm box for repeated commands
crabbox_status   query a lease's state
crabbox_list     list visible leases for the current owner/org
crabbox_stop     stop a lease and release its provider resources

Each tool accepts an argv array of string plus an optional env object of string values. The plugin enforces these as JSON schema before invoking the binary, so an agent cannot pass arbitrary shell commands or non-string env values.

crabbox_run, crabbox_warmup, and crabbox_stop can be disabled per install by setting allowRun, allowWarmup, or allowStop to false in plugin config. crabbox_status and crabbox_list are read-only and always allowed.

#Config

The plugin accepts only four config keys, all optional:

{
  "binary": "crabbox",
  "maxOutputBytes": 60000,
  "timeoutSeconds": 1800,
  "allowRun": true,
  "allowWarmup": true,
  "allowStop": true
}

Key	Default	Effect
`binary`	`crabbox`	Path to the Crabbox binary. Set when the binary is not on PATH.
`maxOutputBytes`	60000	Max captured stdout/stderr returned to the model per call.
`timeoutSeconds`	1800	Default wrapper timeout for a Crabbox CLI invocation.
`allowRun`	true	Gate `crabbox_run`.
`allowWarmup`	true	Gate `crabbox_warmup`.
`allowStop`	true	Gate `crabbox_stop`.

Crabbox config (broker URL, provider, token, profile, class) lives in the user/repo config files. The plugin does not duplicate those keys; it inherits them from whatever crabbox config show would return for the agent's working directory.

#Output Handling

The plugin captures stdout and stderr separately, trims each to maxOutputBytes, and reports the exit code, the trimmed bytes, and a truncation flag back to the model. Truncated output gets a tail marker so agents know they did not get the full transcript:

... [output truncated; 12345 of 87654 bytes shown]

Long-running tools still respect timeoutSeconds. When the wrapper times out, the plugin sends SIGTERM, waits a short grace period, then escalates to SIGKILL. The exit code in the response reflects the wrapper outcome, not the inner remote command.

#What Belongs In The CLI Instead

History, log inspection, attach, results, usage, and admin operations are intentionally not plugin tools. They are best run from a shell-capable agent:

crabbox history --lease cbx_...
crabbox events run_... --after 0 --limit 50
crabbox attach run_...
crabbox logs run_...
crabbox results run_...
crabbox usage --scope user
crabbox admin leases --state active
crabbox cleanup --dry-run

Reasons for keeping these out of the plugin:

they often produce more output than maxOutputBytes can usefully capture;
agents tend to want raw logs they can grep, not trimmed model output;
admin tools are easier to gate at the shell level (env, allowlists) than

through plugin config;

crabbox attach is interactive by design.

#Provider Allowlist

The plugin schema constrains the provider argument to the providers Crabbox actually supports:

aws | hetzner | ssh | blacksmith-testbox | blacksmith | namespace-devbox | namespace | semaphore | sprites | daytona | islo | e2b

Adding a provider to the CLI requires updating this list in index.js and the test fixture in index.test.js. The schema is the agent-facing contract; without the update, the new provider would be rejected by JSON validation before reaching the binary.

#When To Update

Edit the plugin when you:

add or remove a provider;
add a new agent-safe tool (read-only, owner-scoped, bounded output);
change argv conventions across all crabbox commands (rare);
update default timeouts or output budgets.

Run node --test index.test.js after every change. The tests exercise the schema, argv handling, and output trimming end-to-end.

Related docs:

docs/README.md - top-level overview includes the plugin.
Source map - package.json, openclaw.plugin.json,

index.js, index.test.js.

run command - what crabbox_run ultimately invokes.
warmup command - what crabbox_warmup invokes.
stop command - what crabbox_stop invokes.