SphereIntegrationHub is a workflow-first runtime for orchestrating API calls with versioned OpenAPI catalogs, YAML workflows, reusable child workflows, dry-run validation, and execution reporting.

The runtime stays focused on orchestration. Protocol and channel behavior is delivered through plugins such as HTTP, OpenAI LLM, and secret providers like Vaultwarden.

Start here

Quick install

npm / npx

npm install -g @pinedatec.eu/sphere-integration-hub
sih --version

npx @pinedatec.eu/sphere-integration-hub

dotnet tool

dotnet tool install -g SphereIntegrationHub.Tool
dotnet tool install -g SphereIntegrationHub.Mcp.Tool

NuGet packages: CLI · MCP

Release integrity

When publishing the npm package, the npm semver and the GitHub release tag are intentionally not identical:

npm publishes major.minor.patch
GitHub releases publish major.minor.patch.build
npm/sphere-integration-hub/package.json must persist that four-part release as sihReleaseVersion

Release publication is only valid when all three checks pass:

the GitHub release tag v<sihReleaseVersion> exists before npm publish
the published npm package contains sihReleaseVersion with that exact four-part value
the npm postinstall regression test passes before publication

The canonical release path is ./scripts/release.sh, which enforces these checks before publishing npm.

First run

Validate a workflow without calling endpoints:

sih \
  --workflow ./src/resources/workflows/create-account.workflow \
  --env pre \
  --dry-run \
  --verbose

Execute it with inputs:

sih \
  --workflow ./src/resources/workflows/create-account.workflow \
  --env pre \
  --input username=user \
  --input password=secret \
  --input accountName=Acme

Generate JSON + HTML execution artifacts:

sih \
  --workflow ./src/resources/workflows/create-account.workflow \
  --env pre \
  --report-format both \
  --capture-http bodies

See getting-started.md for install modes, CLI usage, GitHub Action usage, and SDK direction.

The planned language SDK contracts are documented in .doc/sdk-language-hosts.md.

Core concepts

Workflows are plain YAML and remain the single source of truth for orchestration.
API contracts live in versioned api.catalog definitions with cached OpenAPI documents.
Validation can inspect workflows, references, and contract compatibility before runtime.
Workflow stages can call endpoints, invoke child workflows, iterate collections, and expose outputs back to parent flows.
Execution reports persist machine-readable JSON plus a self-contained HTML trace viewer.

Examples

samples/sample-bootstrap.workflow: explicit Http plugin stage with plugin-specific config.
samples/openai-llm/sample-openai-llm.workflow: OpenAI plugin with kind: LLM, structured output, limits, timeout, and token usage.
samples/workflows.config: explicit plugin activation and reporting defaults.
samples/api.catalog: catalog definition with plugin binding.
samples/vaultwarden-secrets: Vaultwarden secret provider feeding {{env:...}} tokens.

More examples and usage patterns live in getting-started.md and the sample files under samples/.

Documentation map

Product and adoption

Authoring and execution

Integrations

Community

If you use SphereIntegrationHub in your company or project, we would like to hear about it.

Give the repository a star on GitHub.
Share your use case on LinkedIn with #SphereIntegrationHub.
Contact [email protected].