Delivering & Managing Custom Integrations

Custom Integration Scopes

Integration identities reserve three scopes. Organization uploads are the currently supported custom-integration path:

Delivering via a pack source

What Happens on Install

When a pack carrying an integration entry is installed, the platform runs the same bundle pipeline it always has:

00_organization/integration-bundles/{vendorId}/{version}/bundle.tar.gz

Managing Installed Custom Integrations

Statuses

Enable / Disable

Enable or disable a custom integration's products from the vendor detail dialog under Settings > Platform > Integrations. Disabling removes it from the workflow editor but does not delete the stored files.

Versioning

Publish a new pack version to update the integration. The platform stores each version by {vendorId}/{version}/, so multiple versions can coexist; the live version is the semver-max active one (or the pinned version if your org pinned one — see Pack version management).

Catalog and Execution Sequence

When the platform starts:

1. Scan first-party bundles — parse manifest.json from /app/bundles/ (Docker image)
2. Scan platform bundles — parse manifests from platform storage
3. Scan org bundles — parse manifests from each organization's storage
4. Populate Manifest Catalog — metadata only, no vendor code loaded
5. Publish dynamic readiness — the Runtime Plane reports whether the exact digest-pinned vendor profile has current candidate and deployment proof
6. Admit on demand — the compiler exposes a custom Agent tool only when its verified SHA-256 source and exact backend pass the security floor
7. Execute once — the trusted broker revalidates tenant, environment, connection, source, policy, and binding revisions, then starts a fresh vendor_bundle microVM

Agent tool readiness

For an isolated Agent, a non-Scrydon tool is available only when all of these are true:

• the active archive has a verified SHA-256 identity and still matches the compiled source revision;
• the authenticated Runtime Plane supports the vendor_bundle contract;
• runner, broker, and enforcer images are digest-pinned;
• a schedulable Kata/KVM substrate is observed;
• signed exact-candidate and deployment proofs match the configured images, profile, and evidence digests;
• actual-request egress, outbound DLP, and audit are ready; and
• the encrypted one-use grant store is ready.

Any missing condition produces a typed remediation error. The platform never degrades an organization-installed Agent tool to a Worker Thread.

Organization Policies

Organization policies (configured by admins) govern custom integration behavior:

Execution Policy

{
  "maxConcurrentExecutions": 10,
  "maxTimeoutSeconds": 30,
  "allowedCapabilities": ["llm", "stt", "tools"]
}

Governance Policy

{
  "allowedVendorScopes": ["scrydon", "platform"],
  "blockedVendorIds": []
}

• blockedVendorIds — vendor IDs blocked from installing (enforced on pack install)
• allowedCapabilities — which capability types are permitted

Package Format

Every custom integration is packaged as a .tar.gz archive with this structure:

{vendorId}-{version}.bundle.tar.gz
├── manifest.json           (vendor metadata, JSON Schemas, UI definitions)
├── dist/
│   └── index.js            (compiled, minified ESM; all dependencies inlined)
├── meta/                   (automatically generated)
│   ├── sbom.cdx.json       (CycloneDX 1.6 SBOM)
│   └── metafile.json       (esbuild dependency graph)
└── assets/                 (optional)
    └── icon.svg, icon.png  (vendor/product icons)

SBOM Generation

Every custom integration artifact automatically includes a CycloneDX 1.6 Software Bill of Materials (SBOM) at meta/sbom.cdx.json. The SBOM is generated during sdk-authoring integrations build with no additional tools or configuration required.

What's in the SBOM

The SBOM lists every NPM package that esbuild bundled into dist/index.js:

• Package name and version — exactly what's in the bundle
• License — SPDX license identifier from package.json
• Package URL (purl) — machine-readable identifier (pkg:npm/zod@3.24.0)
• Evidence — file paths proving the package is actually bundled (tree-shaken code is excluded)

How it's generated

During sdk-authoring integrations build, the CLI:

1. Runs esbuild with metafile: true to capture all input files
2. Extracts unique NPM packages from node_modules/ paths in the metafile
3. Reads each package's package.json for name, version, license, and description
4. Serializes everything to CycloneDX 1.6 JSON
5. Writes the result to meta/sbom.cdx.json alongside the esbuild metafile

No external tools or dependencies are required — the generation is built into the CLI.

How admins use it

After installing a custom integration, the Dependencies tab in the vendor detail dialog shows the SBOM component count in the tab header and lists all auto-detected packages alongside declared dependencies. See Custom Integration Review Before Activation for the full review workflow.

Compliance

The CycloneDX format is widely supported by compliance tools. For environments that require SPDX, convert using:

cyclonedx-cli convert --input-file meta/sbom.cdx.json --output-file sbom.spdx.json --output-format spdxjson

The raw esbuild dependency graph is also available at meta/metafile.json for debugging. You can visualize it at esbuild.github.io/analyze.

Custom Integration Review Before Activation

After a custom integration is installed, administrators can review its contents before enabling it for the organization. The vendor detail dialog provides a structured review experience across multiple tabs.

Capabilities Tab

Shows all products, tools, triggers, and runtime capabilities the custom integration provides. Administrators can enable or disable individual blocks from this tab. Intelligence capabilities (LLM, STT, TTS, Embedding) display model counts and support allowlist-mode policy configuration. See Capabilities for details.

Dependencies Tab

The Dependencies tab displays two complementary views of the custom integration's dependency tree:

• Declared dependencies — Hand-authored entries from defineProduct({ dependencies: [...] }) that include a human-readable reason for each dependency.
• Auto-detected dependencies (SBOM) — The full set of NPM packages that esbuild bundled into dist/index.js, extracted from meta/sbom.cdx.json. Each entry shows the package name, version, license, and a machine-readable package URL (purl).

The tab header shows the total SBOM component count so administrators can quickly gauge the custom integration's dependency footprint. Organization dependency policies (risk levels, blocklists, post-install script blocking) are evaluated against both declared and auto-detected dependencies.

Setup Tab

Shows the vendor's authentication configuration (OAuth, API Key, Bot Token, or None) and allows administrators to configure credentials before enabling the vendor's capabilities.

Storage Layout

First-party (baked into Docker image):
  /app/bundles/{vendorId}/dist/index.js

Platform uploads:
  {platformPrefix}/integration-bundles/{vendorId}/{version}/bundle.tar.gz

Org uploads:
  {storageKeyPrefix}/00_organization/integration-bundles/{vendorId}/{version}/bundle.tar.gz

Troubleshooting

Install fails with "Invalid manifest"

Run the CLI validator locally before publishing the pack to see detailed errors:

bunx @scrydon/sdk-authoring integrations test --level static

Common issues:

• Vendor ID contains uppercase or special characters
• Tool ID doesn't start with the vendor ID prefix
• Missing required fields (id, name, version, icon, auth)
• Zod schema uses unsupported types (the extractor converts Zod → JSON Schema)

Custom integration status shows "Failed"

Check the error message in the vendor detail dialog (and server logs). Common causes:

• dist/index.js has a syntax error
• Default export is not a defineVendor() result
• Missing export default statement
• Runtime import fails (ensure all deps are bundled — esbuild should inline them)

Tool doesn't appear in the workflow editor

1. Verify the pack that carries the integration is installed (Settings > Platform > Packs) and its version is active
2. Verify the product is enabled for your organization in Settings > Platform > Integrations
3. Check the block's category — it must be "tools", "blocks", or "triggers" to appear in the correct palette section

Build warns that block tool configuration will be omitted

tools.config.tool and tools.config.params are functions, so they cannot be represented in manifest.json. Replace dynamic routing with tools.toolSelector, expose direct parameters as block inputs, and move any remaining parameter coercion into the tool's execute() function. Do not ignore this warning: an installed workflow block only has the JSON-safe manifest definition at serialization time.