Skip to content

Commit e681646

Browse files
steipetesteipete
authored
feat(cloud-workers): add crabbox worker provider plugin and profile-aware lease lifecycle (#104465)
* feat(cloud-workers): add Crabbox worker provider * docs(cloud-workers): document Crabbox profiles * chore(cloud-workers): drop changelog entry (release-only file) * refactor(plugin-sdk): pass profiles to worker lease lifecycle * docs(plugin-sdk): document worker lifecycle profiles * chore(docs): regenerate plugin inventory, docs map, and sdk baseline after rebase * fix(cloud-workers): state crabbox key-ref gap without warning-comment suppressions
1 parent a66d295 commit e681646

23 files changed

Lines changed: 1670 additions & 92 deletions

‎.github/labeler.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,10 @@
380380
- any-glob-to-any-file:
381381
- "extensions/clawrouter/**"
382382
- "docs/providers/clawrouter.md"
383+
"extensions: crabbox":
384+
- changed-files:
385+
- any-glob-to-any-file:
386+
- "extensions/crabbox/**"
383387
"extensions: deepseek":
384388
- changed-files:
385389
- any-glob-to-any-file:

‎docs/.generated/plugin-sdk-api-baseline.sha256‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
96c016603dd132e8a255554825758330b59669a74e66a940b4f489eeffbddbfd plugin-sdk-api-baseline.json
2-
92494514d548bca63dd95b2b72991ba61fca8cd4c33a779da11d246c0b4b5485 plugin-sdk-api-baseline.jsonl
1+
f2f5f7f14e8ec9be0ce9f59350f5f58f16e1218cd2a2ed61e5175d424649130d plugin-sdk-api-baseline.json
2+
3fe1b2d75bcabff080590b882f3e4055e769bb1dee083a575421bf8c1c8a2f53 plugin-sdk-api-baseline.jsonl

‎docs/.i18n/glossary.zh-CN.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1450,5 +1450,13 @@
14501450
{
14511451
"source": "openclaw nodes approve",
14521452
"target": "openclaw nodes approve"
1453+
},
1454+
{
1455+
"source": "Cloud workers plan",
1456+
"target": "云端工作节点计划"
1457+
},
1458+
{
1459+
"source": "Crabbox plugin",
1460+
"target": "Crabbox 插件"
14531461
}
14541462
]

‎docs/docs_map.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3246,6 +3246,8 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
32463246
- H3: gateway.tls
32473247
- H3: gateway.reload
32483248
- H2: Cloud worker environments
3249+
- H3: Crabbox profile
3250+
- H3: Static SSH development profile
32493251
- H2: Hooks
32503252
- H3: Gmail integration
32513253
- H2: Canvas plugin host
@@ -6018,6 +6020,15 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
60186020
- H2: Surface
60196021
- H2: Related docs
60206022

6023+
## plugins/reference/crabbox.md
6024+
6025+
- Route: /plugins/reference/crabbox
6026+
- Headings:
6027+
- H1: Crabbox plugin
6028+
- H2: Distribution
6029+
- H2: Surface
6030+
- H2: Configure
6031+
60216032
## plugins/reference/deepgram.md
60226033

60236034
- Route: /plugins/reference/deepgram
@@ -6949,6 +6960,14 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
69496960
- H2: Surface
69506961
- H2: Related docs
69516962

6963+
## plugins/reference/workspaces.md
6964+
6965+
- Route: /plugins/reference/workspaces
6966+
- Headings:
6967+
- H1: Workspaces plugin
6968+
- H2: Distribution
6969+
- H2: Surface
6970+
69526971
## plugins/reference/xai.md
69536972

69546973
- Route: /plugins/reference/xai

‎docs/gateway/configuration-reference.md‎

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -736,6 +736,47 @@ See [Multiple Gateways](/gateway/multiple-gateways).
736736

737737
Cloud workers are opt-in. If `cloudWorkers` is absent, or `profiles` is empty, OpenClaw accepts no new worker creation. Durable records created earlier still reconcile and remain visible; the existing gateway/node projection is unchanged.
738738

739+
### Crabbox profile
740+
741+
The bundled `crabbox` provider provisions an SSH-capable lease through the local Crabbox CLI. The inner `settings.provider` selects the Crabbox backend; it is separate from the outer OpenClaw provider id.
742+
743+
```json5
744+
{
745+
cloudWorkers: {
746+
profiles: {
747+
production: {
748+
provider: "crabbox",
749+
settings: {
750+
provider: "aws",
751+
class: "standard",
752+
ttl: "24h",
753+
idleTimeout: "60m",
754+
// Optional absolute path. Default: sibling ../crabbox/bin/crabbox, then PATH.
755+
binary: "/usr/local/bin/crabbox",
756+
},
757+
lifetime: {
758+
idleTimeoutMinutes: 60,
759+
maxLifetimeMinutes: 1440,
760+
},
761+
},
762+
},
763+
},
764+
}
765+
```
766+
767+
- `settings.provider` (required): Crabbox backend passed through `--provider`. Use a backend whose inspect output includes an SSH endpoint; `aws` selects the direct AWS backend.
768+
- `settings.class` (required): Crabbox machine class passed to `--class`.
769+
- `settings.ttl` and `settings.idleTimeout` (required): positive Go duration strings passed to `--ttl` and `--idle-timeout`. These provider-side failsafes are distinct from OpenClaw's stored `lifetime` policy below.
770+
- `settings.binary`: optional absolute Crabbox executable path. Without it, OpenClaw checks the sibling Crabbox checkout, then executable entries on `PATH`, and finally invokes `crabbox` so a missing CLI remains a visible provider error.
771+
772+
Unknown settings are rejected. Crabbox credentials and backend-specific account configuration remain owned by Crabbox; do not place them in `settings`. OpenClaw invokes only the local CLI and makes no provider network calls from this plugin. Provisioning always passes `--keep=true`; OpenClaw owns the external lifecycle and destroys the lease with `crabbox stop`.
773+
774+
<Warning>
775+
This milestone surfaces the SSH endpoint and a file `SecretRef`, but the current generic file-secret contract does not resolve Crabbox's dynamic key path, and Crabbox `inspect` does not expose host-key material. The later tunnel milestone must define direct-file key resolution and host-key pinning before connecting; this profile alone is not yet a complete SSH trust boundary.
776+
</Warning>
777+
778+
### Static SSH development profile
779+
739780
```json5
740781
{
741782
cloudWorkers: {
@@ -763,12 +804,14 @@ Cloud workers are opt-in. If `cloudWorkers` is absent, or `profiles` is empty, O
763804
```
764805

765806
- `profiles`: named worker profiles with non-empty, whitespace-trimmed ids. Each profile selects a provider registered by a plugin.
766-
- `provider`: non-empty worker provider id. The example uses the `static-ssh` provider from the QA Lab plugin.
767-
- Bundled provider plugins are enabled automatically when selected. External provider plugins must be installed and explicitly enabled (and included in `plugins.allow` when that allowlist is set).
807+
- `provider`: non-empty worker provider id. The examples use the bundled `crabbox` provider and the QA Lab `static-ssh` provider.
808+
- Bundled provider plugins are selected automatically when configured, but explicit disables and `plugins.allow` still apply. Include the provider id (for example, `crabbox`) when an allowlist is configured. External provider plugins must also be installed and explicitly enabled.
768809
- `settings`: provider-owned bounded JSON. The selected plugin defines and validates its keys; use [SecretRef objects](/gateway/secrets) for secret-bearing values. The static SSH provider requires `host`, `user`, and `keyRef`; `port` defaults to `22`.
769810
- `lifetime.idleTimeoutMinutes`: positive integer minutes stored for later idle-reclamation policy.
770811
- `lifetime.maxLifetimeMinutes`: positive integer minutes stored for later lifecycle policy.
771812

813+
Each durable environment record retains its validated provider settings snapshot for later inspection and destruction. Changing or removing a named profile affects new creates; existing records continue lifecycle reconciliation with their creation-time settings, provided the owning plugin remains available.
814+
772815
Lifetime values are data only in the first cloud-worker release; automatic enforcement lands with later lifecycle work. Profile changes require a gateway restart.
773816

774817
<Warning>

‎docs/plan/cloud-workers.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,9 +75,9 @@ Provider contract (plugin-implemented; no provider names or policy in core):
7575
type WorkerProvider = {
7676
id: string;
7777
provision(profile: WorkerProfile, opId: string): Promise<WorkerLease>; // → ssh host/port/user/key material
78-
inspect(leaseId: string): Promise<LeaseStatus>; // adopt/health/orphan sweep
78+
inspect(lease: { leaseId: string; profile: WorkerProfile }): Promise<LeaseStatus>; // adopt/health/orphan sweep
7979
renew?(leaseId: string): Promise<void>; // long-lived sessions vs provider TTLs
80-
destroy(leaseId: string): Promise<void>; // idempotent, returns only on proof of teardown
80+
destroy(lease: { leaseId: string; profile: WorkerProfile }): Promise<void>; // idempotent, returns only on proof of teardown
8181
};
8282
```
8383

0 commit comments

Comments
 (0)