Uploading & Managing Custom Integrations

Custom Integration Scopes

Custom integrations exist at three scopes, all running through the same sandboxed execution path:

Uploading via the Settings UI

Uploading via the API

Use a POST request with multipart form data:

curl -X POST https://your-instance.example.com/api/bundle-upload \
  -F "bundle=@dist/my-vendor-1.0.0.bundle.tar.gz" \
  -b "better-auth.session_token=<your-session-token>"

Response

{
  "vendorId": "my-vendor",
  "version": "1.0.0",
  "toolCount": 3,
  "productCount": 1
}

Error Responses

What Happens on Upload

The upload pipeline performs these steps:

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

Managing Installed Custom Integrations

Statuses

Enable / Disable

Toggle a custom integration's status from the Custom tab. Disabling a custom integration removes it from the workflow editor but does not delete the stored files.

Delete

Deleting a custom integration removes the database record. The stored blob can be cleaned up separately.

Versioning

Upload a new version of the same vendor to update it. The platform stores custom integrations by {vendorId}/{version}/, so multiple versions can coexist. The most recently uploaded active version is the one used at runtime.

Boot 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. Register SandboxActor type with the Dapr runtime
6. Ready to serve — actors activate on demand (first tool execution)

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"],
  "allowOrgUploads": true,
  "requireApprovalForUploads": false,
  "blockedVendorIds": []
}

• allowOrgUploads — whether org admins can upload custom integrations
• requireApprovalForUploads — whether uploads need platform admin approval
• blockedVendorIds — explicitly blocked vendor IDs
• 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 uploading 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 uploaded, 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

Upload fails with "Invalid manifest"

Run the CLI validator locally 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 Custom integrations table. 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 custom integration status is Active in Settings > Platform > Integrations > Custom
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