Skip to content

README.md

Latest commit

 

History

History
111 lines (75 loc) · 5.04 KB

README.md

File metadata and controls

111 lines (75 loc) · 5.04 KB
Raw

Crabbox for Zed

Use Zed as the local control surface for Crabbox remote execution.

Crabbox is a provider layer across managed VMs, local and remote containers, microVMs, delegated sandboxes, self-hosted virtualization, and existing SSH hosts. This extension brings that provider-neutral execution surface into Zed while keeping Zed itself local.

It does not run Zed inside a Crabbox and does not use MCP. Every action invokes the installed crabbox CLI from the current repository, so provider selection, authentication, synchronization, lease accounting, evidence, and cleanup remain owned by Crabbox.

What it provides

When crabbox.yaml or .crabbox.yaml is active, Zed's task picker includes:

  • Crabbox: Doctor — validate configuration, credentials, and provider readiness.
  • Crabbox: Spawn reusable box — provision or claim a reusable execution environment with crabbox warmup.
  • Crabbox: Run selected command — synchronize the repository and execute selected text remotely.
  • Crabbox: Run detected project job — execute the workflow generated by crabbox init --detect.
  • Crabbox: List boxes — show current leases and sandboxes.
  • Interactive status, remote-command, SSH, inspect, and stop tasks that first display available leases and then ask for an id or slug.

The extension also adds Crabbox YAML highlighting and snippets for project configuration, jobs, capacity, synchronization, and cache volumes.

Capabilities vary by provider. Use crabbox providers, crabbox providers recommend <workflow>, and crabbox doctor --provider <name> to choose and validate the appropriate isolation and runtime contract.

Requirements

Install the Crabbox CLI and verify it is available to Zed's terminal environment:

brew install openclaw/tap/crabbox
crabbox --version

Initialize the repository if needed:

crabbox init --detect

Install from the Zed extension registry

No Crabbox submission exists in the Zed extension registry yet. After a submission is accepted, open zed: extensions, search for Crabbox, and select Install. The registry entry will point at the integrations/zed package in the Crabbox repository. Publication is tracked in #1157.

Until then, install the exact package as a development extension:

  1. Clone openclaw/crabbox.
  2. In Zed, run zed: extensions.
  3. Choose Install Dev Extension.
  4. Select integrations/zed from the checkout.
  5. Open the target repository's .crabbox.yaml and run task: spawn.

Make tasks available from every file

Zed language-extension tasks are associated with the active Crabbox configuration language. To expose the same checked task pack regardless of the active file, copy it into the project:

mkdir -p .zed
cp /path/to/crabbox/integrations/zed/project-tasks.json .zed/tasks.json

If .zed/tasks.json already exists, merge the task objects instead of overwriting it.

Typical workflow

  1. Run Crabbox: Doctor.
  2. Run Crabbox: Spawn reusable box and note the returned friendly slug.
  3. Select go test ./..., pnpm test, or another repository command and run Crabbox: Run selected command for an isolated one-shot execution.
  4. For repeated work on the warm environment, use Crabbox: Run command on box… and enter the slug.
  5. Use Crabbox: Inspect box… or Crabbox: SSH into box… when a failure needs live investigation.
  6. Run Crabbox: Stop box… when finished.

Security model

The extension stores no provider credentials, broker tokens, SSH keys, or lease state. It does not modify SSH configuration and does not call provider APIs directly. Interactive tasks pass the selected lease and command to the local Crabbox CLI, which remains the authoritative security, cost, and lifecycle boundary.

Zed launches every task through the user's login shell. Direct task definitions keep the crabbox command and its arguments separate instead of adding another inline shell program. Interactive helpers intentionally start Bash and therefore target macOS and Linux.

Registry publication

Zed publishes extensions from zed-industries/extensions. The registry PR adds the Crabbox repository URL to .gitmodules:

[submodule "extensions/crabbox"]
    path = extensions/crabbox
    url = https://github.com/openclaw/crabbox.git

The checked-out submodule path is then registered in extensions.toml:

[crabbox]
submodule = "extensions/crabbox"
version = "0.1.0"
path = "integrations/zed"

The registry submodule must pin the merged Crabbox commit. Future releases update both version in extension.toml and the registry entry.

Validation

From the repository root:

node scripts/check-zed-extension.mjs
node scripts/test-zed-extension-e2e.mjs

The dedicated Zed Extension E2E workflow packages the extension with Zed's pinned official zed-extension CLI, verifies archive.tar.gz and manifest.json, and executes every task against a controlled Crabbox CLI boundary, including interactive status, run, connect, inspect, and stop flows.