Install marketplace bundle

Installing a marketplace asset creates org-scoped Passport + constrained delegation records, resolves bundle members in order, and enforces org marketplace policy — not a single SQL insert.

Overview

Step	What happens
Preview (optional)	POST /v1/control-plane/marketplace/install/preview — scopes, presets, member order
Install	POST /v1/control-plane/marketplace/install — agent, bundle, extension, or capability pack
Bundle orchestration	installBundleAsset() in apps/api/src/services/install-bundle.ts

Asset must have review_status: 'approved'. Org marketplace policy (cp_org_policies) can block by asset type, PII handling, or trust tier.

Install preview

const preview = await fetch(
  `${process.env.HUMAN_API_URL}/v1/control-plane/marketplace/install/preview`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.HUMAN_DELEGATION_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      asset_id: process.env.BUNDLE_ASSET_ID,
      org_did: process.env.HUMAN_ORG_DID,
      preset: 'safe', // safe | autopilot | custom
    }),
  },
);
const body = await preview.json();
console.log(body.aggregate_required_scopes, body.members);

Preview returns install_order_groups, per-member delegation previews, and policy footnotes without writing installations.

Install a bundle

What installBundleAsset does

From apps/api/src/services/install-bundle.ts:

1. Validates BundleManifestV1 and policy compatibility.
2. Detects command conflicts across bundle members.
3. Installs each member (connectors, agents, extensions) in declared order.
4. Seeds bundle prompt_contributions (generic — no hardcoded bundle id branches).
5. Records marketplace_installations and emits gate events.

Idempotent re-installs are safe when the asset is already recorded for the org.

List installed assets

human api GET "/v1/control-plane/marketplace/installed?orgDid=$HUMAN_ORG_DID"

Use cases

• Eval org bootstrap — install humanos.bundle.hitl.v1 + first-party connectors.
• Enterprise rollout — preview safe preset scopes before autopilot.
• Companion + cloud split — install connector with companion_integration: true; cloud proposes, desktop executes.

Security considerations

See also

• Publish to marketplace
• Companion integration manifest
• Guide: Building a bundle
• Service: apps/api/src/services/install-bundle.ts