Using Hub Nodes

This chapter is the consumer side: finding a node, wiring it into a dataflow, and understanding how the version you wrote resolves to the version you run. To author a node, see Writing a Node Manifest.

Referencing a node

Add a hub: field to a node instead of path: or git::

nodes:
  - id: detector
    hub: dora-yolo@^0.5
    inputs:
      image: camera/image
    outputs:
      - bbox

  - id: camera
    hub: opencv-video-capture@^0.3
    outputs:
      - image

hub: is mutually exclusive with path:, git:, build:, and the branch/tag/rev fields on the same node — the Hub provides all of those. You still write the node’s inputs/outputs wiring as usual; the types of those ports come from the published manifest.

The reference syntax

[<namespace>/]<name>@<version-requirement>

A bare name (no namespace/) means the official dora-rs namespace. A namespace maps to a GitHub org or user and resolves against exactly one index (see Custom & Enterprise Indexes).

Version requirements

The part after @ is a standard semver/Cargo version requirement:

Resolution picks the highest non-yanked version that satisfies the requirement. Pre-release versions (e.g. 0.6.0-rc1) are only matched by a requirement that itself names a pre-release, following the Cargo convention.

Pin your requirement, then lock it for reproducibility — see Reproducible Builds. Without a lockfile, each dora build re-resolves to the latest matching version.

Finding nodes

Search the catalog

dora hub search yolo                    # name / description / keyword match
dora hub search --category ml-inference # browse a category
dora hub search lidar --platform linux-x86_64
dora hub search                         # list everything

Search spans every configured index and prints namespace/name version — description (categories), using each package’s latest version.

Inspect a package

dora hub info shows a package’s typed contracts, configuration, and a ready-to- paste example — read this before wiring a node so you know its ports and types:

dora hub info dora-yolo            # latest version
dora hub info dora-yolo@0.5.2      # a specific version
dora hub info acme/lidar@^2        # a requirement

It prints the version (and a (yanked) marker if applicable), description, categories, supported platforms, runtime, the typed inputs and outputs, env vars, and the example snippet.

Add --offline to any of these to use only the local cache without hitting the network.

Building and validating

Resolution happens at dora build / dora validate / dora run time — there is no separate fetch step:

dora validate dataflow.yml   # resolve hub nodes, check wiring + types, no build
dora build dataflow.yml      # resolve, pin, and build every node
dora run dataflow.yml        # build + run (local)

Because a published node ships its input/output types in its manifest, the normal type-checking pipeline applies to it: wiring a BoundingBox output into an input that expects an Image fails at compose time with the producer/consumer URNs, before any process starts. Your own annotations in the dataflow always take precedence over the manifest’s.

What gets built

A hub: node desugars to a pinned git: node: the resolver clones the node’s source at the exact published commit and runs its build command (e.g. pip install ., cargo build --release) on the machine that builds it. For a node that ships a prebuilt binary for your platform, the resolver downloads and sha256-verifies that artifact instead of cloning — see Binary distribution.

Heavy builds run wherever the node runs, so on constrained devices prefer build-on-a-host-and-ship (see the manifest chapter’s build-location guidance and dora hub fetch for mirroring sources).

Overriding a node locally

While iterating on a node you consume, point a single package at a local checkout without editing the YAML or publishing anything:

dora build dataflow.yml --hub-override dora-yolo=../my-fork/dora-yolo

This is a local-build-only inner-loop tool (it cannot combine with --write-lockfile or distributed builds). See Reproducible Builds for the lockfile interactions.