Components

Components are self-contained packages that add functionality to a WarmHub repo. A component declares the shapes, subscriptions, credentials, and seed data it needs, and installation applies the manifest-provisioned resources in one operation. Registered components can also delegate selected resources to a setup callback.

What a component does

When you install a component, WarmHub:

1. Reads the component’s manifest (warmhub/manifest.json) to learn what resources it needs
2. Creates manifest-provisioned shapes for the data types the component works with
3. Sets up manifest-provisioned subscriptions that deliver to your webhook endpoints when data changes or on a schedule
4. Seeds initial data the component needs to operate
5. Creates manifest-provisioned credential sets for any external API keys the component requires
6. Calls the setup endpoint for registered components that declare setup-provisioned resources

All resources are tracked under a ComponentInstall record so the CLI can manage, diagnose, and tear down the component later.

Key concepts

Manifest-driven: Components use a declarative JSON manifest rather than imperative scripts. The manifest describes what resources the component needs, and the CLI handles creation, reconciliation, and teardown.

Ownership: Resources created by a component are tagged with the component’s ID. This prevents accidental modification and enables clean teardown. Users can still create things under component-owned shapes — ownership protects schema, not data.

State tracking: Each installed component has a state that reflects its health:

State	Meaning
ready	All resources exist, all credentials populated
credentials-required	Resources created, but one or more credential keys need values
degraded	One or more declared resources are missing or inactive
paused	All subscriptions paused (via teardown)
installing	Install in progress
error	Install failed

Registered components

Registered components are org-owned component identities installed with wh component install <org/name>. They are useful when the component source should be resolved through WarmHub, when private GitHub source should be downloaded by the backend, or when install needs a setup callback to create external service state.

Authors enable this model by registering the component identity with wh component register, providing a GitHub sourceUrl, and optionally adding a setupUrl. Manifest resources marked provisioning: "setup" are skipped by the local installer and must be created by that setup service.

See Manifest Reference for provisioning and runtimeAccess, CLI Commands for registration commands, and the client.component API reference for the registry methods.

Bundled system components

WarmHub also ships reserved system components that install by id from the backend. The current installable bundled component is:

wh component install com.warmhub.identity --repo myorg/myrepo

This path does not require wh component register, does not create a registry entry, and does not use a local or GitHub component package. The backend resolves the bundled manifest and installs the component into the target repo. Lowercase system ids are reserved for WarmHub; third-party component id validation is unchanged.

CLI commands

# Install WarmHub's bundled Identity system component
wh component install com.warmhub.identity --repo myorg/myrepo

# Install a component from GitHub
wh component install https://github.com/org/my-component --repo myorg/myrepo

# Install a registered component
wh component install org/component-name --repo myorg/myrepo

# Install from a local path (for development; best for components without subscriptions)
wh component install ./my-component --repo myorg/myrepo

# List installed components
wh component list --repo myorg/myrepo

# View component details
wh component view my-component --repo myorg/myrepo

# Run health checks
wh component doctor my-component --repo myorg/myrepo

# Pause all component subscriptions
wh component teardown my-component --repo myorg/myrepo

# Validate a component package offline (no repo needed)
wh component validate ./my-component

Example

A component that watches for new Paper things and summarizes them:

my-summarizer/
  warmhub/
    component.json          # Identity: id, name, version
    manifest.json           # Resources: shapes, subscriptions, credentials, seeds

Installing it:

wh component install https://github.com/myorg/my-summarizer --repo myorg/research
# Installed my-summarizer v1.0.0 [credentials-required]

# Set the required API key
wh credential set summarizer-creds api_key --value sk-...

# Verify health
wh component doctor my-summarizer --repo myorg/research

Next steps:

• Manifest Reference — full manifest format
• Component Lifecycle — install, update, doctor, teardown
• Authoring Components — build your own
• Testing Components — validation workflow