Installing a Connector

This guide is for users installing a connector binary on its own, separate from any action that depends on it. It walks through aileron keyring trust, aileron connector install, the preview-and-consent flow, where the binary lands on disk, and the binding step that follows. By the end you will have a verified, sandboxed connector under ~/.aileron/store/connectors/sha256/<hash>/ and a credential bound (or queued for binding) against it.

If you have not read it yet, start with Connectors for the model. The companion authoring guide is Authoring a Connector, and Publishing a Connector covers the publisher side of the contract this guide consumes.

When to install a connector standalone

Most users don’t run this command directly. aileron action add <action-FQN> walks the action’s connector dependencies and installs every missing connector transitively, in the same atomic flow. The standalone command exists for three cases:

You want the connector but no actions yet. You’re building your own actions against it, or you want to drive the binding setup before any action template lands.
You’re pinning a specific connector hash. --hash=sha256:<hex> aborts the install if the computed hash doesn’t match, useful for reproducible deployments.
You’re scripting against a connector check. aileron connector check reports newer versions; aileron connector install is how you upgrade.

If you’re starting from an action template, Installing an Action is the more direct path.

Trust the publisher first

Connector install verifies the binary’s signature against keys registered for the FQN’s authority. Without an entry, the install fails closed with signature_failure before anything reaches disk.

aileron keyring trust github://ALRubinger/aileron-connector-google

The CLI fetches keys/publisher.pub from the publisher’s default branch on raw.githubusercontent.com, parses the ed25519 public key, and adds it under the authority github://ALRubinger/aileron-connector-google in ~/.aileron/keyring.json. Output looks like:

✓ Trusted publisher github://ALRubinger/aileron-connector-google
  Fingerprint: sha256:nXKt8AfDQH5jL2pM1RvB9w
  Keyring: /Users/you/.aileron/keyring.json

Re-running the command after the publisher rotates their key adds the new key alongside the old (rotation support, per ADR-0002). Re-running with no rotation reports the existing fingerprint and exits zero.

The keyring is fail-closed by default. There are no pre-trusted publishers shipped with Aileron; every publisher you install from has to be explicitly added.

Note on auto-trust: aileron action add auto-prompts to trust an action’s publisher (and any new connector dep publishers) before the install. aileron connector install also auto-prompts when the FQN is published to the Connector Hub (ADR-0013): the daemon renders a y/N/d=details decision with the publisher’s key fingerprint, trust state, and risk indicators, and on confirm writes the publisher key to the keyring before installing. For an FQN not listed in the Hub (private repos), run aileron keyring trust first.

Preview and install

aileron connector install github://ALRubinger/[email protected]

The version is required. Either suffix the FQN with @<version> or pass --version=<v> separately.

The CLI runs a two-phase flow per ADR-0007:

Preview. The server fetches the tarball, verifies the signature against your keyring, parses the manifest, and returns the metadata. Signature failure or hash mismatch aborts here, before any prompt.

Render the preview for you to review:

Connector install preview

  FQN:        github://ALRubinger/aileron-connector-google
  Version:    0.0.6
  Hash:       sha256:a1b2c3d4e5f6…
  Publisher:  Andrew Lee Rubinger
  Signature:  verified

  Network access:
    - gmail.googleapis.com:443
    - www.googleapis.com:443

  Credential required:
    kind:  oauth2
    scope: Read your Gmail messages and Calendar events; create drafts and calendar events

The capabilities section is the closed list of hosts the connector can reach plus the credential kind it needs. Anything not on the list is denied at the sandbox boundary at runtime.

Consent prompt (Install? [y/N]:). On y, the server runs the install pipeline a second time and writes the verified tarball to disk:

Installed: github://ALRubinger/[email protected]
  hash: sha256:a1b2c3d4e5f6…
  path: /Users/you/.aileron/store/connectors/sha256/a1b2c3d4e5f6…

The store is content-addressed. Two installs that resolve to the same binary || manifest hash share the same on-disk directory, regardless of FQN or version label.

Already-installed short-circuit

If the preview reports the same FQN + version + hash as an existing entry, the CLI prints Already installed: <FQN>@<version> and exits zero without prompting. There is no work to do.

Flags

Flag	Effect
`--version=<v>`	Strict SemVer version to install. Required if the FQN has no `@<version>` suffix.
`--hash=sha256:<hex>`	Expected content hash. The install aborts if the computed hash doesn’t match. Use this when you want byte-level reproducibility, e.g. in deployment scripts.
`--yes`	Skip the consent prompt. Does not bypass signature verification (the server still checks the keyring).

Bind the credential

Most connectors need a credential to do anything useful. After the connector installs, drop into the binding setup:

aileron binding setup github://ALRubinger/aileron-connector-google

The CLI prompts for an identity (work, personal, etc. — a label so you can have multiple bindings against the same connector), then dispatches by the connector’s declared credential kind:

OAuth2. The CLI POSTs to /v1/bindings/setup/oauth2/init, opens your browser to the publisher’s authorize_url, listens on a loopback port for the redirect, and exchanges the code for tokens. The publisher’s app name appears on the consent screen, not Aileron’s. The bound {access_token, refresh_token} envelope is encrypted at rest in your vault; tokens are refreshed transparently when they near expiry.
API key. The CLI prompts for the key value inline, encrypts it, and stores it in the vault.

Until at least one binding exists for a connector’s credential capability, actions that need it fail with binding_required at invocation time. aileron binding list shows the metadata for every binding (no secret bytes, ever).

Checking for updates

aileron connector check

Walks every installed connector, queries the publisher’s source for newer versions per ADR-0004, and reports a per-connector status:

  github://ALRubinger/[email protected] → 0.0.6 (update available)
  github://OtherPub/[email protected] (up to date)

1 update(s) available; 2 connector(s) checked.

Pass --include-prerelease to surface non-stable releases. Pass --json for NDJSON output (one connector per line) for scripting.

To install the new version, run aileron connector install <FQN>@<new-version>. There is no automatic upgrade in v1; the install consent prompt fires for every upgrade so you see the new capability surface before agreeing to it.

What lands on disk

~/.aileron/
├── store/
│   └── connectors/
│       └── sha256/
│           ├── a1b2c3d4e5f6…/                  # one connector tarball, content-addressed
│           │   ├── connector.wasm
│           │   ├── manifest.toml
│           │   └── signature.sig
│           └── …
├── keyring.json                                # trusted publisher keys
└── secrets.json                                # encrypted vault — bindings live here

The connector binary is sandboxed at runtime. Per the manifest’s declared capabilities, it can reach only the hosts on its allow-list and request only the credential kind it declared at install time. The capability gates fire at every outbound call; nothing the binary does at runtime can widen the surface you reviewed at install.

What you can’t do yet

There are no aileron connector list / show / remove subcommands in v1. aileron status reports the installed-connector count, and aileron connector check enumerates each one. To remove a connector, delete its directory under ~/.aileron/store/connectors/sha256/ (only safe if no installed action pins that hash — verify with aileron sync first).

Common errors

signature_failure — the connector’s authority isn’t in your keyring, or the publisher rotated their key. Run aileron keyring trust <authority> to fetch the current key. Without a trusted key, no install proceeds.
hash mismatch — --hash=... was supplied and the computed hash doesn’t match. Either the publisher republished under the same version (which they shouldn’t do), or you have the wrong expected hash.
version is required — neither the FQN nor --version carried a SemVer. Add @<version> to the FQN or pass --version=<v>.
binding_required (at action runtime) — the connector installed fine but no binding exists for its credential capability. Run aileron binding setup <connector-FQN>.

Companion reading

Installing an Action — the more common entry point; action add walks connector deps for you.
Authoring a Connector — write the WASM binary this guide installs.
Publishing a Connector — sign and release a connector users can install.
ADR-0002: Connector Model — sandboxing, signing, and the trust model.
ADR-0004: Dependency Resolution — how FQNs map to release artifacts.
ADR-0006: Capability Binding UX — the design behind aileron binding setup.
ADR-0007: Install Consent — why the preview/prompt flow looks the way it does.