Installing Connectors from the Registry

Beside the built-in connectors shipped with Conduit, standalone connectors are distributed through the Conduit connector registry. You install them with a single command:

conduit connectors install postgres

install resolves the name against the signed registry index, downloads the artifact for your operating system and architecture, verifies it, and places it in your connectors directory. The connector is ready to reference in a pipeline the next time Conduit starts.

note

conduit connectors install runs offline against your connectors directory on disk — it does not need a running Conduit instance. The only network call it makes is to the registry.

Verified by default

Every install is verified before the connector is usable. Conduit checks, in order:

1. The registry index signature. Nothing about which artifact to fetch is trusted until the index itself verifies against Conduit's built-in trust anchors. There is no flag, config value, or environment variable that bypasses index verification.
2. The artifact's signature and SLSA provenance. "Verified" means both — a validly signed artifact with no provenance attestation is refused, not installed.
3. The artifact's sha256 digest, to catch corruption in transit. This check always runs, even when signature verification is skipped (see Installing an unsigned connector).

Verification is fail-closed: if any check cannot be completed — the index is unreachable, tampered, stale, or unsigned; the artifact's signature or provenance is missing or invalid — the install stops and nothing is written to disk. Conduit never installs an unverified connector as a side effect of a network or signature failure.

Already-installed connectors keep being protected after the fact by conduit connectors audit, which re-checks them against the current index for later yanks and publisher revocations.

Selecting a version

The argument is <name>[@version]:

conduit connectors install postgres           # newest compatible version
conduit connectors install [email protected]    # an exact version

• The name is matched exactly against the index.
• When @version is omitted, Conduit selects the newest version compatible with this build. Compatibility is a gate, not a preference: a candidate must satisfy both the connector's minimum Conduit version and its minimum connector-protocol version. Newer versions that require a Conduit you are not running are skipped rather than installed and then failing at runtime.
• Installing a version that is already present is a no-op — the command reports it as already installed. Deprecated versions install with a warning.

Where connectors are installed

Artifacts are written to your connectors directory, resolved exactly like conduit run resolves it:

Source	Value
Flag	--connectors.path
Environment variable	CONDUIT_CONNECTORS_PATH
Default	<basePath>/connectors (the connectors directory relative to where you run Conduit)

conduit connectors install postgres --connectors.path=/opt/conduit/connectors

Because install and run resolve this path the same way, a connector you install here is exactly the one Conduit loads at startup.

Preview without installing

--dry-run resolves the name, selects the platform artifact, and reports what would be installed — without downloading or writing anything:

$ conduit connectors install postgres --dry-run
Would install [email protected] (darwin/arm64) from https://registry.conduitdata.io/...

Installing an unsigned connector

--allow-unsigned skips only the per-artifact signature and provenance check. It never skips index verification, and never skips the sha256 corruption check. It is deliberately hard to trigger by accident — it is not enough on its own to install an unsigned artifact:

• Interactively (a real terminal), Conduit prompts you to type the connector's name to confirm. A y/N-style answer is treated as a decline; only an exact match proceeds.
• Non-interactively (no TTY, CI=true, or an agent-driven call), the flag alone does nothing. You must also set CONDUIT_ALLOW_UNSIGNED_INSTALL=I_UNDERSTAND. Two independent signals are required so that neither a copy-pasted script line nor an agent's tool call can trigger it alone.
• Operators can disable it entirely. If install.allow-unsigned is false in the Conduit configuration (the default), no flag, TTY, or environment variable can turn it back on.

conduit connectors install my-connector --allow-unsigned

warning

An unsigned connector has no verified cryptographic identity or build provenance. Only use --allow-unsigned for connectors you build yourself or otherwise trust out of band.

Other flags

Flag	Description
--index-url	Registry index URL. Default https://registry.conduitdata.io/index.json.
--index-file	Read the index from a local file instead of --index-url (offline).
--lock-timeout	Maximum time to wait for the per-connector install lock. Default 30s.
--dry-run	Report what would be installed without downloading or writing anything.
--bundle	Install fully offline from a bundle tarball. See Offline install.
--json	Emit the result as structured JSON.

For the complete conduit connectors command group, see the Registry CLI reference. To install on a machine with no network access, see Air-gapped / offline install.

Record size limitations

When using standalone connectors, the maximum size of a record is limited by the gRPC Go library grpc/grpc-go to 4 MB by default. If you send a larger record you will see an error like this in the logs:

2022-07-28T14:00:01+00:00 ERR node stopped 
  error="node stopped with error: failed to receive ack: 
         error receiving ack: grpc: received message larger than max (5000117 vs. 4194304)"

Raise the limit with --connectors.max-receive-record-size when starting Conduit. For example, to set the maximum record size to 10 MB:

conduit run --connectors.max-receive-record-size 10485760

This can also be set in the configuration file or with the environment variable CONDUIT_CONNECTORS_MAX_RECEIVE_RECORD_SIZE.

warning

For this configuration to take effect, your standalone connector must be using conduit-connector-sdk >= v0.14.0