| name | extending-capabilities |
| description | Write and extend VM provisioning capabilities for clawctl. Use when adding new tools to the VM, modifying the provisioning pipeline, writing CapabilityDef modules, or working with lifecycle hooks and CapabilityContext SDK. |
Extending Capabilities
Capabilities are the extension mechanism for VM provisioning. Each
capability is a CapabilityDef module that declares what it installs,
when it runs (lifecycle phase + hook timing), and what health checks it
provides.
Key concepts
- CapabilityDef — a declarative constant with
name, version,
hooks (keyed by lifecycle phase), optional dependsOn, and optional
migrations.
- Lifecycle phases —
provision-system, provision-tools,
provision-openclaw, provision-workspace, bootstrap. Each phase
supports pre:, main, and post: timing slots.
- CapabilityContext SDK — sandboxed interface (
ctx.exec(),
ctx.fs, ctx.apt, ctx.systemd, ctx.net, ctx.profile,
ctx.agentsMd) that capabilities use for system access. Never import
vm-cli internals directly.
- Steps return
ProvisionResult (installed / unchanged /
failed) and must be idempotent.
- Doctor checks are declared via
doctorChecks on hooks, using
availableAfter for lifecycle-aware warnings.
- State tracking —
capability-state.json records installed
versions; version changes trigger migrations or re-provision.
Adding a new capability
- Create a module in
packages/capabilities/src/capabilities/
- Export a
CapabilityDef constant
- Export it from
packages/capabilities/src/index.ts
- Register it in
packages/vm-cli/src/capabilities/registry.ts
Full reference
See references/capabilities.md for the
complete documentation including hook timing, runner mechanics, state
tracking, migrations, core vs optional capabilities, and AGENTS.md
managed sections.
