Discovering on the Hub

This guide is for users who want to find and install community-published suites, actions, and connectors. The Aileron Hub is a public discovery index — a catalog that publishers opt into so users can find them. Discovery is decoupled from trust. Appearing in the Hub is not an Aileron endorsement. You still confirm the publisher’s signing key fingerprint before installing.

The Hub itself is the GitHub repo aileron-hub ↗. It catalogs three entry types, each one YAML pointer to a canonical FQN:

suites/*.yaml — bundles of related actions (e.g. “Gmail + Calendar”).
actions/*.yaml — individual action templates (e.g. “draft a Gmail”).
connectors/*.yaml — the binaries those actions and suites depend on.

The Hub holds no binaries. Install artifacts still come from the publisher’s source repository. The intent-first default browse leads with Suites, then Actions, then Providers (connectors) — see ADR-0013.

For the install pipeline that runs under all this, see Installing a Connector or Installing an Action. The Hub layers discovery and a per-FQN trust prompt on top of those pipelines.

Quick tour

# Default browse: all three catalogs grouped by type, Suites first.
aileron hub list

# Per-catalog browse.
aileron hub list suites
aileron hub list actions
aileron hub list connectors

# Cross-catalog search (matches FQN and description in all three).
aileron hub search calendar

# Restrict search to one catalog.
aileron hub search calendar --type suites

# Show a single entry (dispatches by entry type).
aileron hub show github://ALRubinger/aileron-connector-google/actions/draft-email

The same data is browseable in the webapp: under aileron launch, visit /hub for a tabbed shell (Suites / Actions / Providers) with per-card detail pages and a composite install modal.

How the daemon talks to the Hub

The daemon shallow-clones aileron-hub on every query and parses the entries on the fly. There is no persisted cache and no GitHub API call (per ADR-0013 and the resolution of issue #486). Each aileron hub invocation pays one shallow git clone of a small repo. The CLI is the same shape as any other Aileron subcommand: it talks to the local daemon over /v1/hub/*, the daemon does the work.

The webapp’s /hub page reads the same endpoints. CLI and webapp render the same data in different shapes.

`aileron hub` CLI

`list [<catalog>]`

With no argument, prints all three catalogs grouped by type:

── SUITES ──
FQN                                                 PUBLISHER             ACTIONS  DESCRIPTION
github://ALRubinger/aileron-connector-google/suite  ALRubinger            5        Read and draft Gmail; read and create calendar events

── ACTIONS ──
FQN                                                              PUBLISHER             DESCRIPTION
github://ALRubinger/aileron-connector-google/actions/draft-email ALRubinger            Draft a Gmail message with subject, recipients, and body
...

── PROVIDERS ──
FQN                                                 PUBLISHER             DESCRIPTION
github://ALRubinger/aileron-connector-google        ALRubinger            Google Workspace connector (Calendar, Drive, Gmail)

With an explicit catalog (suites / actions / connectors), prints just that one. Pass --json for NDJSON (single-catalog) or a single grouped JSON object (default mode) when scripting.

`search <query> [--type <catalog>]`

Case-insensitive substring match on FQN and description across all three catalogs by default. --type narrows to one catalog when you already know what you want. Server-side filter, so the daemon handles the matching rules.

aileron hub search slack
aileron hub search draft --type actions

`show <fqn> [--type <catalog>]`

Tries each catalog in order (connector → action → suite) and prints the first match. --type skips dispatch and queries the named catalog directly. The rendering shape depends on entry type — connector entries show key URL + release pattern, actions show the required connector + intents, suites show member actions + the closure of connectors they depend on.

Kind:           action
FQN:            github://ALRubinger/aileron-connector-google/actions/draft-email
Description:    Draft a Gmail message with subject, recipients, and body
Publisher:      ALRubinger
Connector:      github://ALRubinger/aileron-connector-google
Intents:        draft email, compose gmail
Category:       communication

The install-decision prompt (connectors)

When you run aileron connector install <FQN> on a Hub-listed connector, the CLI does not jump straight to the preview flow. It first fetches an install-decision payload from the daemon, which:

Looks up the Hub entry.
Fetches the publisher’s current public key from key_url.
Computes the key’s fingerprint.
Compares against your local keyring to determine trust state.

You see something like this:

Hub install-decision

  FQN:         github://ALRubinger/aileron-connector-google
  Description: Google Workspace connector (Calendar, Drive, Gmail)
  Publisher:   ALRubinger
  Fingerprint: sha256:nXKt8AfDQH5jL2pM1RvB9w
  Trust:       unknown (first install)

  Risk indicators:
    • First connector by this publisher you've installed

Install? [y/N/d=details]:

Three answers are accepted:

y confirms. The daemon writes the publisher key to your keyring under this FQN, then runs the install pipeline. Trust persists on disk even if the install pipeline later fails. Re-running the install does not re-prompt.
N (or any unrecognized answer) cancels. Nothing is written. The daemon does not run the install pipeline.
d shows full details: the complete list of risk indicators, every other connector the same publisher has listed in the Hub. The prompt then asks again with y/N.

Trust states and colors

The Trust: line picks one of three labels, color-coded so the unusual states stand out:

State	Color	Meaning
`already trusted`	green	The publisher’s current key is already on your keyring at this FQN. The install proceeds without trust-write work.
`unknown (first install)`	yellow	The keyring has no trusted key for this FQN. Confirming will register the publisher’s current key.
`conflict — key differs from a trusted sibling repo`	red	A different connector by the same publisher (per `publisher_github`) carries a key you trust, and the key at this FQN’s `key_url` doesn’t match. Possible explanations are key rotation, MITM, or impersonation. Worth a closer look before confirming.

The conflict state is rare and intentional. v0.x trust is strictly per-repo (per FQN), so one publisher with two connectors can carry two different keys without anything being wrong. The conflict surface flags the case so you notice. Run aileron keyring list to see what’s currently trusted, compare fingerprints with the publisher’s release notes or commits to keys/publisher.pub in their repo, then make a call.

The composite install-decision (actions and suites)

When you run aileron action add <ACTION-FQN> or aileron action add-suite <SUITE-URL> on a Hub-listed action or suite, the CLI fetches a composite install-decision payload. It walks the dependency closure and groups by unique connector authority, surfacing one trust panel per authority — even if a suite bundles five actions that all depend on the same connector, you see one trust gate, not five.

Hub install-decision (suite)

  Suite:     github://ALRubinger/aileron-connector-google/suite
  Summary:   Read and draft Gmail; read and create calendar events
  Publisher: ALRubinger
  Actions:   5
    - github://ALRubinger/aileron-connector-google/actions/list-recent-emails
    - github://ALRubinger/aileron-connector-google/actions/draft-email
    ...

  Trust gate(s): 1 connector authority

  ● github://ALRubinger/aileron-connector-google
      Publisher:   ALRubinger
      Fingerprint: sha256:i4l2kuD8q++d5b9v8/LLI1
      Trust:       unknown (first install)
      Risk:        • First connector by this publisher you've installed

Trust these publishers and continue? [y/N/d=details]:

A single y covers every authority surfaced in the panel. The daemon writes per-FQN trust to your keyring for each before the install pipeline runs. Per-authority y/N prompts that the legacy flow would have fired are suppressed — trustState records them as already accepted.

For a cross-publisher suite (one whose member actions depend on connectors from multiple publishers), the panel renders one section per unique authority and the same single confirm covers them all.

Fall-through: if the action or suite isn’t Hub-listed (404), the composite endpoint returns nothing useful and the CLI falls through to the legacy per-authority trust prompts unchanged. Local-file suite installs (aileron action add-suite ./my-suite.toml) never carry a Hub FQN and always use the legacy flow.

The webapp’s Hub page

Under aileron launch, the daemon serves a static webapp at http://127.0.0.1:<port>/. The /hub page renders a tabbed shell with the three catalogs:

Suites (default tab) — bundled action sets, grouped by intent.
Actions — atomic action templates, with the required connector visible per card.
Providers — connector entries; the same view as the pre-amendment page.

Each card has a per-entry Install button and a clickable FQN linking to a detail page at /hub/suites/[fqn] or /hub/actions/[fqn]. The detail page renders the full entry record (publisher, dependencies, member actions, intents, category) and its own Install button.

Clicking Install on a connector opens the connector-level install modal — same install-decision payload the CLI renders (FQN, publisher, fingerprint, trust-state badge, risk indicators, publisher footprint). A version input (required) and an optional expected-hash input let you pin the install. On confirm, the modal POSTs to /v1/connectors/install with the confirmed_fingerprint payload. Daemon-side behavior is identical to the CLI flow.

Clicking Install on an action or suite opens the composite install modal — the per-authority trust panel grouped exactly like the CLI’s Trust these publishers and continue? prompt. The modal surfaces the CLI command (aileron action add ...@latest or aileron action add-suite ...@latest) for completing the install today; webapp-driven install execution for actions and suites is a follow-up (tracked in #739 ↗).

Neither modal exposes a “Trust this publisher” button. v0.x trust is per-repo, and the design is deliberately careful not to invite users into a wider trust grant.

What the Hub does not do

What	Why not
Vet publishers	Anyone with a GitHub account can open a PR adding their connector to the Hub. Aileron does not review submissions for quality, security, or claims made in the description. The Hub is a discovery surface, not an editorial one.
Host binaries	Install artifacts live at `github://owner/repo`. The Hub entry is one YAML file pointing at the canonical FQN. If a publisher takes their repo down, the Hub entry breaks; Aileron stores nothing on the publisher’s behalf.
Show popularity signals	No stars, no last-commit timestamps, no download counts in v0.x. Surfacing those would force every user’s daemon to call `api.github.com` (60/hr unauthenticated ceiling) on every Hub page load. A server-side metadata service that amortizes those calls is tracked in issue #614 ↗.
Phone home	No telemetry. The daemon does not report which connectors you browsed, which you installed, or which Hub entries you opened. The discovery surface and the install pipeline both run locally.

Common errors

hub_unreachable: the daemon couldn’t clone the Hub repo. Check that the daemon has network access to github.com. The same error wraps any non-404 git clone failure.
not_found at install time: you supplied a confirmed_fingerprint (i.e. you went through the install-decision flow), but the FQN is not in the Hub. The daemon and the CLI are out of sync on what’s installable, probably because the Hub PR for the entry hasn’t merged yet. Workaround: install with pre-established trust via aileron keyring trust <FQN> followed by aileron connector install <FQN>@<version>, which uses the legacy flow.
fingerprint_mismatch: between rendering the install-decision and confirming, the publisher’s key at key_url changed. The daemon refuses to install rather than silently trusting a different key. Re-run the install command to see the new fingerprint, compare against the publisher’s release notes, and decide.