Agent Capabilities

Capability commands update the tools and runtime requirements Spinup keeps with an agent. Capabilities cover skills, MCP servers, tools, plugins, CLIs, and runtime requirements. See Capabilities for the concept.

The CLI can mark a capability as declared or disabled. Runtime fulfillment is recorded later when Spinup projects, materializes, or validates supported capability types inside the agent environment.

The CLI saves declarations; runtime evidence records what Spinup actually projected, installed, materialized, or validated later. Today, runtime evidence can show MCP projection, skill materialization, supported JavaScript/Python CLI and tool installs allowed by RuntimePolicy, bounded remote-script installers, baseline CLI/runtime validation, and OpenClaw plugin materialization. Hermes plugin fulfillment and agent-authored skill promotion remain limited or deferred until Spinup records explicit runtime support for them.

Supported capability kinds today:

• skill
• mcp_server
• tool
• plugin
• cli
• runtime_requirement

List capabilities

spinup agents capabilities list agent_01hxyz...

Use the slug directly when you already have it:

spinup agents capabilities list support-agent

Add a capability

spinup agents capabilities add agent_01hxyz... \
  --kind cli \
  --name ffmpeg \
  --source spinup-runtime

Add a capability that references existing secret binding IDs:

spinup agents capabilities add support-agent \
  --kind mcp_server \
  --name firecrawl \
  --source firecrawl-mcp \
  --secret-binding-ids secret_binding_01hxyz...

Secret values are never passed through this command. The IDs only declare which existing secret bindings the capability requires.

For Spinup-owned runtime tools such as ffmpeg, save a runtime capability with installPlan.strategy: "none" and an executable validation plan. Spinup materializes the verified pinned Worker Host artifact on demand before validation; it does not run a guest package install. For install-backed CLI capabilities, include a supported installPlan with --install-plan-json or --install-plan-file. Examples include js_global_package for Firecrawl CLI, python_tool for Python CLIs, and remote_script for a Loops-style installer. Loops should use a remote script URL such as https://cli.loops.so, interpreter bash, executable loops, and a LOOPS_API_KEY secret binding. Spinup downloads the script and runs bash <downloaded-script> as argv; do not pass pasted shell such as curl ... | bash.

spinup agents capabilities add support-agent \
  --kind cli \
  --name firecrawl \
  --source firecrawl \
  --install-plan-json '{"strategy":"js_global_package","manager":"npm","packageName":"firecrawl","executable":"firecrawl"}' \
  --validation-plan-json '{"strategy":"command","command":"firecrawl --version"}'

Use file flags for longer plans:

spinup agents capabilities add support-agent \
  --kind cli \
  --name loops \
  --source loops \
  --install-plan-file ./loops-install-plan.json \
  --validation-plan-file ./loops-validation-plan.json

Structured fields accepted by add and update are --install-plan-json or --install-plan-file, --validation-plan-json or --validation-plan-file, --credential-policy-json or --credential-policy-file, and --projection-hints-json or --projection-hints-file. Each value must be a JSON object or null; the *-file variants read the same JSON from disk.

Set the package installation policy before relying on install-backed capabilities:

spinup agents runtime-policy set support-agent --install-mode declared

The default declared mode allows supported user-declared package and remote-script install plans. Use curated to restrict installs to the small installer set Spinup recognizes today, including Firecrawl CLI and the Loops installer, or none to block install-backed capabilities. ffmpeg is runtime-owned and should be declared with installPlan.strategy: "none"; Spinup exposes the pinned runtime-tool artifact and then validates it.

Update a capability

spinup agents capabilities update agent_01hxyz... capability_01hxyz... \
  --status disabled

Use --status declared to re-enable a disabled capability.

You can update bounded control-plane fields such as name, source, status, version, and secret binding IDs:

spinup agents capabilities update support-agent capability_01hxyz... \
  --name ffmpeg \
  --source spinup-runtime \
  --version 7

Update can also replace structured plans:

spinup agents capabilities update support-agent capability_01hxyz... \
  --install-plan-file ./firecrawl-install-plan.json \
  --validation-plan-json '{"strategy":"command","command":"firecrawl --version"}'

Remove a capability

spinup agents capabilities remove agent_01hxyz... capability_01hxyz...

Remove deletes the capability binding from the agent state. Use update --status disabled when you want a reversible disable that keeps the binding available for re-enable.

JSON output

spinup agents capabilities list agent_01hxyz... --json
spinup agents capabilities add agent_01hxyz... --kind cli --name ffmpeg --source spinup-runtime --json
spinup agents capabilities update agent_01hxyz... capability_01hxyz... --status disabled --json
spinup agents capabilities remove agent_01hxyz... capability_01hxyz... --json

The JSON response includes the saved state version, the current runtime policy, the current capability list, and any missing secret requirements. Spinup projects, materializes, or validates supported capability kinds asynchronously when the agent environment is reconciled or used for a run.

Review proposed changes

Agents can propose durable changes through Spinup state tools. Public surfaces call these proposed changes. Internally they are StateCandidates, but CLI, SDK, API, and dashboard copy use proposed-change language.

List actionable pending changes:

spinup agents changes list support-agent

Inspect one proposed change before review:

spinup agents changes get support-agent statecandidate_01hxyz...

Approve with the current base state version and payload hash from the get/list response:

spinup agents changes approve support-agent statecandidate_01hxyz... \
  --expected-base-state-version state_version_01hxyz... \
  --expected-payload-hash sha256:...

Reject with a bounded reason:

spinup agents changes reject support-agent statecandidate_01hxyz... \
  --reason "Not needed for this agent"

Approval saves durable intent into AgentState. It does not mean a CLI, plugin, MCP server, or runtime requirement has already materialized in a live runtime. RuntimePolicy, package availability, validation, and later reconciliation still decide fulfillment and record support-safe evidence.

Proposed-change responses include status, reviewability, base state version, payload hash, promoted state version, and a bounded summary. They do not include raw prompts, raw model output, raw stdout/stderr, secret values, callback credentials, or unbounded candidate payloads.