Install a marketplace connector

A marketplace connector (item kind node) is a WebAssembly component that adds a reusable node type to the workflow builder. Once installed, it appears in the node palette and can be wired into any workflow in your workspace — with network egress limited to the resource credentials you map at install time.

Browse the catalog

Open the Marketplace page in the sidebar. Use the filter bar to narrow by:

• Kind — select Connector to see node items only.
• Search — substring search across an item’s name and summary.
• Verified — tick to show only items that passed the automated review gate.

Each listing shows its current price (free or one-time purchase), publisher, install count, and average buyer rating.

Note

All paid and central (official) connectors must pass a mandatory automated review before they carry the Verified badge. Free community listings use post-publish moderation.

Before you install: what must be true outside SupaCloud

A connector talks to a system you run. The install wires up the SupaCloud side — the resource, the credentials, the sandbox — and it cannot change what that other system requires. If a prerequisite there is unmet, the connector fails at run time with an error that looks like a SupaCloud problem and is not.

SupaCloud does not leave this to a footnote. An item can declare its prerequisite as a field on the published version (Markdown, English and German), and where it is declared it is shown twice:

• on the item detail page, above the tabs — so the decision can be made before a purchase;
• as the first block of the install wizard, above the resource mapping — never collapsed, never under “details”.

Where the violation fails silently — Seafile/WebDAV is exactly that case — the publisher marks the prerequisite as requiring confirmation. The wizard then shows an I have read this and set it up checkbox and holds Continue until it is ticked. The confirmation is not cosmetic: the install API refuses an unconfirmed install, so a direct API or CLI call cannot skip it either.

Three that come up in practice:

• Seafile (seafile_webdav) — WebDAV authenticates against the account’s local password. An account created through single sign-on does not have one, so WebDAV rejects it, unless the Seafile administrator enables ENABLE_WEBDAV_SECRET (which in turn needs the pycryptodome package in the Seafile image, or the setting has no effect). Symptom: 401 on every request, with the cause sitting on the Seafile server.
• FinTS (fints_bank) — most banks require a registered product ID in addition to the account credentials, and issue it on request.
• IMAP — a mailbox with two-factor authentication generally needs an app-specific password; the account password is refused.

Caution

Create the resource under Resources first and confirm the credentials actually reach the system, before you run the install wizard. A failure at that point points you at the other system. The same failure after installing looks like a connector defect, and the search starts in the wrong place.

Pick storage folders instead of typing them

A Seafile (seafile_webdav) resource no longer needs a library path typed from memory. Save the connection with its base URL, user and password, then browse it from the resource form:

• Library path is now optional. Left empty, the connection points at the WebDAV root, and the folder browser starts there.
• The folder browser lists the folders one level below the current one. Open a folder to drill in, use Up one level / Root to walk back, and Use as library path to write the browsed folder into the connection.
• Archive targets records several destinations on one connection. Four archive folders no longer need four resources with the same credentials — a workflow picks the target it writes to.

Browsing needs a saved resource: the stored password is resolved on the server and never reaches the browser, so the order is create → save → browse. Before the first save the manual path field is the way in, and it stays available afterwards for a folder the browser cannot list.

Caution

Picking a folder is convenience, not an access boundary. Seafile WebDAV has no scoped tokens: the stored account credential reaches everything that account reaches, whichever folder is selected. If a connector must not see a library, give it an account that cannot see that library.

Install a connector

1. Open the item page. Click a connector in the catalog to see its detail page: port schema, declared resource requirements, capabilities, and changelog.

2. Open the install wizard. Click Install on the item. The first step is the Install Preview, where SupaCloud resolves transitive dependencies (other marketplace items the connector relies on) and lists every resource kind it needs (for example, seafile_webdav).

3. Read the prerequisites. If the item declares a prerequisite outside SupaCloud, it is the first block on that step. Where the publisher marked it as requiring confirmation, tick the checkbox — Continue stays disabled until you do, and the server rejects an unconfirmed install.

4. Map resources. For each required resource kind, select an existing workspace resource of that kind from the dropdown. (Create the resource beforehand under Resources if you do not yet have one, and check its prerequisites first.) The connector can only reach the hosts declared by the resources you map here — no ambient network access is granted.

5. Accept the capability surface. Read the connector’s declared capabilities and confirm. This step is mandatory; the install does not proceed until you confirm.

6. Complete the install. Click Install on the final confirm step. (A paid item has to be bought first, from the preview step — on an instance with a payment provider that is the provider’s checkout; on an instance without one you land on a Dev checkout page that activates the purchase with a single explicit click, for evaluation and staging use. A paid item your own organization published is exempt — see the note below.) SupaCloud registers the connector in your workspace’s node-type registry.

Note

You never buy your own listing. A paid item published by your own organization installs without a licence: the preview reports it as installable and offers no Buy button, and the checkout refuses a purchase you do not need. The same applies to the operator’s own organization for listings sold by SupaCloud itself. For everyone else a paid listing stays paid, and an item whose publisher cannot be established still requires a licence.

Tip

An item you have installed shows an “update available” chip on its catalog card and an update banner on its detail page when a newer version is published.

Install a package that ships a database schema

Some marketplace items — a workflow or script that needs its own tables, not only a connector — ship a shared database schema (ADR 0057). When an item declares one, the install applies that schema’s migrations onto a PostgreSQL resource you map, so the item’s flows have their tables on first run.

• The install requires a postgresql resource mapping. The Install Preview lists postgresql among the required resources; map an existing PostgreSQL resource (or create one under Resources first). Without it the install is refused — the schema is never skipped silently.
• The preview discloses the database footprint: the schema name, its tenant isolation, and each migration’s name with a SHA-256 fingerprint of its SQL, so you can review exactly what runs before you confirm.
• The apply is all-or-nothing: if the schema cannot be applied, the install is rejected and nothing is left behind. Re-installing resumes cleanly.

Caution

A package’s migrations run on the database you map, with that resource’s privileges. Only signed, verified central catalog items can ship a schema — map a least-privileged PostgreSQL role scoped to the target schema rather than a superuser.

Use the connector in a workflow

After installation the connector node type is available in the workflow builder:

1. Open or create a workflow in Workflows.
2. Click the + button on the canvas to open the node palette.
3. Find the connector under its category or search by name.
4. Drag it onto the canvas and wire its input and output ports to other nodes.
5. In the node’s settings panel, the resource bindings you mapped at install are pre-filled — you can change the binding per-node if your workspace has multiple resources of the same kind.

Note

Connector execution is sandboxed: outbound HTTP is limited to the allowlisted egress authorities of the mapped resource, and every request is SSRF-vetted before it leaves the host.

Ratings and updates

Leaving a rating. Once you have installed the connector, the rating form on the item detail page lets you leave a star rating (1–5) and a short comment. Ratings are install-gated — only a workspace that has installed the item can rate it.

Update-available signal. When the publisher releases a new version, an Update available badge appears on the item’s catalog card and an update banner on its detail page. Click Update now to apply the latest version in one step; your existing resource mappings are kept.

An update replaces the connector’s installed component in place, so the new version takes effect on the next workflow run — no server restart, and every workflow node that references the connector keeps working, because the node type keeps its identity. Your own edits are never overwritten: Apps, scripts and workflows the package installed are your working copies, so an update only adds members the new version newly declares and removes nothing.

What the update brings. The banner lists the changelog of every version between the one you have installed and the latest — not just the newest entry — because Update now jumps straight to the latest release, which may be several versions ahead. The item’s Changelog tab shows the full history.

Automatic updates. Switch Update automatically on for an install and new versions are pulled in for you. It is off by default and takes the same route as the button, so it applies the identical signature, review-gate and licence checks — it can never install something you could not install by hand. If an automatic attempt is blocked (a pending review, a lapsed licence), the reason is shown next to the switch rather than failing silently.

See also

• Your first agent run
• Web terminal command reference
• ADR 0034 — Marketplace: workflows, scripts, and connector nodes