Skip to content

Routing

Routing (content routing) is a core Directory component that maps agent skills to record identifiers and to the directory servers that host those records. It builds on a Distributed Hash Table (DHT) so discovery scales across a decentralized network of peers.

Announce and discover

Publishing a record to the network is a two-step process:

  1. Store — push the record to local storage and obtain its CID.
  2. Announce — call routing publish so the server advertises the CID and its skill taxonomy in the DHT. Announcements are processed asynchronously and have a TTL; republish periodically to keep routing data fresh.

Discovery uses:

  • routing list — records indexed on the local peer only.
  • routing search — records announced by remote peers (cached network view).

Skill matching supports exact and hierarchical prefix matching. Network search results reflect cached announcements and may be stale or incomplete until peers replicate records.

ADS uses libp2p Kad-DHT for server and content discovery.

Publication and discovery flow

sequenceDiagram
    participant User
    participant DHT
    participant ServerA
    participant ServerB

    Note over ServerA,ServerB: Publication Phase
    ServerA->>ServerA: Generate CID, store record, extract labels
    ServerA->>DHT: Announce CID + labels
    ServerB->>ServerB: Generate CID, store record, extract labels
    ServerB->>DHT: Announce CID + labels
    DHT->>DHT: Update routing tables<br/>(labels→CIDs→servers)

    Note over User,ServerB: Discovery Phase
    User->>DHT: Query by labels
    DHT->>User: Return matching CIDs<br/>+ server addresses
    User->>ServerA: Sync record 1
    User->>ServerB: Sync record 2

Synchronization

Discovery identifies where records live; synchronization (sync) replicates them locally. After routing search surfaces records hosted on a remote peer, those records can be synced into the local node for offline access, backup, and cross-network collaboration. Sync is one-way: content flows from a remote Directory instance to the local node.

How sync works

Directory uses regsync (from regclient) as the synchronization engine for all registry types. When a sync operation is created, the reconciler generates a regsync configuration and runs regsync once to pull content from remote registries. Objects are stored as OCI artifacts (manifests, blobs, and tags), enabling container-native synchronization with secure credential exchange between Directory nodes.

Sync operations are managed asynchronously by a reconciler. Creating, listing, checking the status of, and deleting a sync are all recorded as desired state that the reconciler processes in the background.

Because sync pairs naturally with discovery, routing search results can drive selective replication: feeding routing search output into a sync operation creates separate sync operations for each remote peer found, syncing only the CIDs that matched the search.