feat: first-class Crabbox backend for remote Buzz agents

.agents/skills/buzz-backend-crabbox/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: buzz-backend-crabbox
+description: >
+  Deploy Buzz managed agents onto Crabbox remote boxes from Desktop or the
+  install recipe. Use when the user wants remote agent spin-up, Run on Crabbox,
+  buzz-backend-crabbox, or leased agent compute outside this computer.
+version: 1
+---
+
+# Buzz ↔ Crabbox backend
+
+Crabbox is a **Desktop backend provider** for Buzz managed agents — not an LLM
+provider and not a substitute for the relay. Buzz still owns identity, keys,
+channels, and the agent record. Crabbox only hosts the `buzz-acp` harness on a
+remote lease.
+
+## Product surface (what users see)
+
+1. **Agents → create agent**
+2. **Run on → Crabbox** (appears after the provider is installed on PATH)
+3. Optional config: Crabbox cloud provider, machine class, idle timeout, existing lease
+4. Deploy → Desktop calls `buzz-backend-crabbox` with the standard agent payload
+5. Agent badge shows **Crabbox**; runtime line shows lease id
+6. **Shutdown** sends `!shutdown` (Buzz-native soft stop)
+7. **Delete agent** calls provider `destroy` → releases the Crabbox lease
+
+## Install (dev / OSS)
+
+```bash
+just install-backend-crabbox
+# or: ./examples/buzz-backend-crabbox/install.sh
+brew install openclaw/tap/crabbox
+crabbox login --url <broker-url>
+crabbox doctor
+```
+
+Restart Desktop so PATH discovery picks up `~/.local/bin/buzz-backend-crabbox`.
+
+## Agent / operator rules
+
+- **Relay must be reachable from the box.** Reject loopback `ws://localhost:…`
+  unless the user has a tunnel; prefer the community’s real relay URL.
+- **Do not put model or crabbox secrets in provider config.** Desktop rejects
+  secret-shaped config keys. Crabbox auth is `crabbox login`; model keys go in
+  agent/persona env vars (forwarded via Crabbox env helper).
+- **Trust boundary.** The provider binary receives the agent nsec. Only install
+  `buzz-backend-*` from this repo or a source the owner trusts.
+- **Stop path.** Prefer channel `!shutdown` / Desktop Shutdown. Then
+  `crabbox stop <lease>` so spend stops. There is no protocol `undeploy` in v1.
+- **Reuse a warm box.** Set provider config `lease_id` to a slug/`cbx_…` from
+  `crabbox list` instead of warming a new machine every deploy.
+
+## Probe
+
+```bash
+echo '{"op":"info","request_id":"1"}' | buzz-backend-crabbox
+just test-backend-crabbox
+```
+
+## Docs
+
+- `docs/backend-providers/crabbox.md`
+- `examples/buzz-backend-crabbox/README.md`
+- https://crabbox.sh/

.claude/skills/buzz-backend-crabbox/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: buzz-backend-crabbox
+description: >
+  Deploy Buzz managed agents onto Crabbox remote boxes from Desktop or the
+  install recipe. Use when the user wants remote agent spin-up, Run on Crabbox,
+  buzz-backend-crabbox, or leased agent compute outside this computer.
+version: 1
+---
+
+# Buzz ↔ Crabbox backend
+
+Crabbox is a **Desktop backend provider** for Buzz managed agents — not an LLM
+provider and not a substitute for the relay. Buzz still owns identity, keys,
+channels, and the agent record. Crabbox only hosts the `buzz-acp` harness on a
+remote lease.
+
+## Product surface (what users see)
+
+1. **Agents → create agent**
+2. **Run on → Crabbox** (appears after the provider is installed on PATH)
+3. Optional config: Crabbox cloud provider, machine class, idle timeout, existing lease
+4. Deploy → Desktop calls `buzz-backend-crabbox` with the standard agent payload
+5. Agent badge shows **Crabbox**; runtime line shows lease id
+6. **Shutdown** sends `!shutdown` (Buzz-native soft stop)
+7. **Delete agent** calls provider `destroy` → releases the Crabbox lease
+
+## Install (dev / OSS)
+
+```bash
+just install-backend-crabbox
+# or: ./examples/buzz-backend-crabbox/install.sh
+brew install openclaw/tap/crabbox
+crabbox login --url <broker-url>
+crabbox doctor
+```
+
+Restart Desktop so PATH discovery picks up `~/.local/bin/buzz-backend-crabbox`.
+
+## Agent / operator rules
+
+- **Relay must be reachable from the box.** Reject loopback `ws://localhost:…`
+  unless the user has a tunnel; prefer the community’s real relay URL.
+- **Do not put model or crabbox secrets in provider config.** Desktop rejects
+  secret-shaped config keys. Crabbox auth is `crabbox login`; model keys go in
+  agent/persona env vars (forwarded via Crabbox env helper).
+- **Trust boundary.** The provider binary receives the agent nsec. Only install
+  `buzz-backend-*` from this repo or a source the owner trusts.
+- **Stop path.** Prefer channel `!shutdown` / Desktop Shutdown. Then
+  `crabbox stop <lease>` so spend stops. There is no protocol `undeploy` in v1.
+- **Reuse a warm box.** Set provider config `lease_id` to a slug/`cbx_…` from
+  `crabbox list` instead of warming a new machine every deploy.
+
+## Probe
+
+```bash
+echo '{"op":"info","request_id":"1"}' | buzz-backend-crabbox
+just test-backend-crabbox
+```
+
+## Docs
+
+- `docs/backend-providers/crabbox.md`
+- `examples/buzz-backend-crabbox/README.md`
+- https://crabbox.sh/

.codex/skills/buzz-backend-crabbox/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: buzz-backend-crabbox
+description: >
+  Deploy Buzz managed agents onto Crabbox remote boxes from Desktop or the
+  install recipe. Use when the user wants remote agent spin-up, Run on Crabbox,
+  buzz-backend-crabbox, or leased agent compute outside this computer.
+version: 1
+---
+
+# Buzz ↔ Crabbox backend
+
+Crabbox is a **Desktop backend provider** for Buzz managed agents — not an LLM
+provider and not a substitute for the relay. Buzz still owns identity, keys,
+channels, and the agent record. Crabbox only hosts the `buzz-acp` harness on a
+remote lease.
+
+## Product surface (what users see)
+
+1. **Agents → create agent**
+2. **Run on → Crabbox** (appears after the provider is installed on PATH)
+3. Optional config: Crabbox cloud provider, machine class, idle timeout, existing lease
+4. Deploy → Desktop calls `buzz-backend-crabbox` with the standard agent payload
+5. Agent badge shows **Crabbox**; runtime line shows lease id
+6. **Shutdown** sends `!shutdown` (Buzz-native soft stop)
+7. **Delete agent** calls provider `destroy` → releases the Crabbox lease
+
+## Install (dev / OSS)
+
+```bash
+just install-backend-crabbox
+# or: ./examples/buzz-backend-crabbox/install.sh
+brew install openclaw/tap/crabbox
+crabbox login --url <broker-url>
+crabbox doctor
+```
+
+Restart Desktop so PATH discovery picks up `~/.local/bin/buzz-backend-crabbox`.
+
+## Agent / operator rules
+
+- **Relay must be reachable from the box.** Reject loopback `ws://localhost:…`
+  unless the user has a tunnel; prefer the community’s real relay URL.
+- **Do not put model or crabbox secrets in provider config.** Desktop rejects
+  secret-shaped config keys. Crabbox auth is `crabbox login`; model keys go in
+  agent/persona env vars (forwarded via Crabbox env helper).
+- **Trust boundary.** The provider binary receives the agent nsec. Only install
+  `buzz-backend-*` from this repo or a source the owner trusts.
+- **Stop path.** Prefer channel `!shutdown` / Desktop Shutdown. Then
+  `crabbox stop <lease>` so spend stops. There is no protocol `undeploy` in v1.
+- **Reuse a warm box.** Set provider config `lease_id` to a slug/`cbx_…` from
+  `crabbox list` instead of warming a new machine every deploy.
+
+## Probe
+
+```bash
+echo '{"op":"info","request_id":"1"}' | buzz-backend-crabbox
+just test-backend-crabbox
+```
+
+## Docs
+
+- `docs/backend-providers/crabbox.md`
+- `examples/buzz-backend-crabbox/README.md`
+- https://crabbox.sh/

.goose/skills/buzz-backend-crabbox/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: buzz-backend-crabbox
+description: >
+  Deploy Buzz managed agents onto Crabbox remote boxes from Desktop or the
+  install recipe. Use when the user wants remote agent spin-up, Run on Crabbox,
+  buzz-backend-crabbox, or leased agent compute outside this computer.
+version: 1
+---
+
+# Buzz ↔ Crabbox backend
+
+Crabbox is a **Desktop backend provider** for Buzz managed agents — not an LLM
+provider and not a substitute for the relay. Buzz still owns identity, keys,
+channels, and the agent record. Crabbox only hosts the `buzz-acp` harness on a
+remote lease.
+
+## Product surface (what users see)
+
+1. **Agents → create agent**
+2. **Run on → Crabbox** (appears after the provider is installed on PATH)
+3. Optional config: Crabbox cloud provider, machine class, idle timeout, existing lease
+4. Deploy → Desktop calls `buzz-backend-crabbox` with the standard agent payload
+5. Agent badge shows **Crabbox**; runtime line shows lease id
+6. **Shutdown** sends `!shutdown` (Buzz-native soft stop)
+7. **Delete agent** calls provider `destroy` → releases the Crabbox lease
+
+## Install (dev / OSS)
+
+```bash
+just install-backend-crabbox
+# or: ./examples/buzz-backend-crabbox/install.sh
+brew install openclaw/tap/crabbox
+crabbox login --url <broker-url>
+crabbox doctor
+```
+
+Restart Desktop so PATH discovery picks up `~/.local/bin/buzz-backend-crabbox`.
+
+## Agent / operator rules
+
+- **Relay must be reachable from the box.** Reject loopback `ws://localhost:…`
+  unless the user has a tunnel; prefer the community’s real relay URL.
+- **Do not put model or crabbox secrets in provider config.** Desktop rejects
+  secret-shaped config keys. Crabbox auth is `crabbox login`; model keys go in
+  agent/persona env vars (forwarded via Crabbox env helper).
+- **Trust boundary.** The provider binary receives the agent nsec. Only install
+  `buzz-backend-*` from this repo or a source the owner trusts.
+- **Stop path.** Prefer channel `!shutdown` / Desktop Shutdown. Then
+  `crabbox stop <lease>` so spend stops. There is no protocol `undeploy` in v1.
+- **Reuse a warm box.** Set provider config `lease_id` to a slug/`cbx_…` from
+  `crabbox list` instead of warming a new machine every deploy.
+
+## Probe
+
+```bash
+echo '{"op":"info","request_id":"1"}' | buzz-backend-crabbox
+just test-backend-crabbox
+```
+
+## Docs
+
+- `docs/backend-providers/crabbox.md`
+- `examples/buzz-backend-crabbox/README.md`
+- https://crabbox.sh/

AGENTS.md

@@ -17,6 +17,7 @@ Buzz spans five repos. This one (`block/buzz`) is the OSS source for the relay,
 | [squareup/sprout-oss](https://github.com/squareup/sprout-oss) | CI pipeline building the relay Docker image and pushing to internal ECR |
 | [squareup/block-coder-tf-stacks](https://github.com/squareup/block-coder-tf-stacks) | Terraform + ArgoCD deploying the relay to the staging Kubernetes cluster |
 | [squareup/sprout-backend-blox](https://github.com/squareup/sprout-backend-blox) | Desktop backend provider script connecting Blox workstation agents to the relay |
+| OSS: [`examples/buzz-backend-crabbox`](examples/buzz-backend-crabbox) · `just install-backend-crabbox` | First-class Desktop **Run on → Crabbox** backend ([docs](docs/backend-providers/crabbox.md)) |
 
 ```
 block/buzz (source)

Justfile

@@ -898,6 +898,34 @@ _release-pr lane version:
 
 # ─── Agent Harness ────────────────────────────────────────────────────────────
 
+# Install the Crabbox Desktop backend provider so agents can Run on → Crabbox.
+# Builds release agent binaries, puts the provider on PATH (~/.local/bin), and
+# prints the Desktop setup steps. Requires the crabbox CLI separately:
+#   brew install openclaw/tap/crabbox && crabbox login --url <broker>
+install-backend-crabbox:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    export PATH="{{justfile_directory()}}/bin:$PATH"
+    echo "→ building buzz-acp / buzz-agent / buzz-cli / buzz-dev-mcp (release)…"
+    cargo build --release -p buzz-acp -p buzz-agent -p buzz-cli -p buzz-dev-mcp -p git-credential-nostr
+    release="{{justfile_directory()}}/target/release"
+    export PATH="$release:$PATH"
+    "{{justfile_directory()}}/examples/buzz-backend-crabbox/install.sh"
+    echo
+    if command -v crabbox >/dev/null 2>&1; then
+        echo "✓ crabbox CLI: $(command -v crabbox) ($(crabbox --version 2>/dev/null || echo present))"
+    else
+        echo "! crabbox CLI not found. Install: brew install openclaw/tap/crabbox"
+        echo "  then: crabbox login --url <broker-url> && crabbox doctor"
+    fi
+    echo
+    echo "Desktop: restart Buzz, create/start an agent, choose Run on → Crabbox."
+    echo "Docs: docs/backend-providers/crabbox.md"
+
+# Offline unit tests for the Crabbox backend provider (no live Crabbox required)
+test-backend-crabbox:
+    python3 "{{justfile_directory()}}/examples/buzz-backend-crabbox/test_provider.py"
+
 # Run a goose agent connected to a Buzz relay (foreground)
 goose relay="ws://localhost:3000" agents="1" heartbeat="0" prompt="" key="$BUZZ_PRIVATE_KEY":
     #!/usr/bin/env bash

desktop/src-tauri/src/commands/agent_providers.rs

@@ -1,13 +1,24 @@
-use crate::managed_agents::{discover_provider_candidates, invoke_provider, BackendProviderInfo};
+use crate::managed_agents::{
+    discover_provider_candidates, invoke_provider, probe_provider_info, BackendProviderInfo,
+};
 
 #[tauri::command]
 pub async fn discover_backend_providers() -> Result<Vec<BackendProviderInfo>, String> {
+    // Best-effort `info` probe per candidate so the Desktop "Run on" picker can
+    // show friendly names (e.g. "Crabbox") instead of raw ids. Probe failures
+    // never drop a candidate — they fall back to the id as the label.
     tokio::task::spawn_blocking(|| {
         discover_provider_candidates()
             .into_iter()
-            .map(|(id, path)| BackendProviderInfo {
-                id,
-                binary_path: path.display().to_string(),
+            .map(|(id, path)| {
+                let (name, description, version) = probe_provider_info(&path);
+                BackendProviderInfo {
+                    id,
+                    binary_path: path.display().to_string(),
+                    name,
+                    description,
+                    version,
+                }
             })
             .collect()
     })