Skip to main content

Discover a data estate and carry it across a gap

An Edge Agent can act as a discovery leaf: it scans sources on its side of a boundary, normalises what it finds into one canonical semantic model, and ships a signed inventory bundle home, including across an air gap where there is no link at all. This tutorial runs that flow with real commands.

What you will prove​

The device will scan a source in place, map every discovered object to the vendor-neutral Universal Semantic Model, persist a signed, restart-safe inventory, export it as a sneakernet bundle, and let you browse the catalog from a local, offline frontend, all without copying the source data out.

Prerequisites​

  • A device with s9 on its PATH (Quickstart working).
  • A source to scan, for a first run, a local file share or directory (e.g. /mnt/share).
  • A workspace id to scope the scan to (e.g. ws-acme).
  • To register the leaf with a trunk, a reachable cell endpoint (one-time). The scan and bundle-export steps themselves run offline.

The flow​

Figure: the discovery-leaf flow. The leaf scans a source in place, normalises it to the canonical model, and persists a signed inventory; that inventory both feeds an offline browser and exports as a sneakernet bundle (amber, dashed) carried to a trunk. Live cross-cell convergence is not part of this flow.

Table equivalent

StageCommandRuns
Register the leafs9 discovery-mapping registerNeeds a cell endpoint (once)
Scan in places9 discovery-mapping scanOffline
Inspects9 discovery-mapping status --detailedOffline
Export bundles9 discovery-mapping export-bundleOffline
Browses9 discovery-mapping frontendOffline (local HTTP)
Carry to trunks9 discovery-mapping ingest-canonical-bundleOn the trunk side

Step 1: Register the device as a discovery leaf​

s9 discovery-mapping register \
    --workspace-id ws-acme \
    --node-endpoint https://node-a.system9.local

This registers the device with the trunk as a scanning leaf. (For a device that will only ever export bundles by courier, this one-time registration is how the trunk learns to expect the leaf's signed deltas.)

Step 2: Scan a source in place​

Run a scan, authoring the result as a signed leaf inventory delta by passing --leaf-id:

s9 discovery-mapping scan \
    --workspace-id ws-acme \
    --source /mnt/share \
    --policy edge_summary \
    --leaf-id leaf-gateway-07

Scan policy (--policy) is one of edge_full, edge_summary (default), edge_sample (with --one-in-n), or central_only. With --leaf-id, every discovered object is mapped to the vendor-neutral model, signed with the device's persisted authoring key, and sequenced from the device's own durable watermark, so it keeps counting across reboots and couriers. The source data is read where it lives, not copied out.

Step 3: Inspect what was catalogued​

s9 discovery-mapping status --detailed

--detailed gives the full row-count breakdown by object kind. The inventory is a signed projection, so a restart rebuilds the catalogue without re-walking the sources.

Step 4: Export a signed bundle for the trip home​

s9 discovery-mapping export-bundle \
    --workspace-id ws-acme \
    --leaf-id leaf-gateway-07 \
    --out /media/usb/leaf.tar.zst

This exports the leaf's outbound queue as a sneakernet bundle (.tar.zst), the air-gapped route home. Carry it to a machine that can reach the trunk.

Step 5: Browse the catalog offline​

You do not need a link to explore what you found. Start the local, offline catalog browser:

s9 discovery-mapping frontend --bind 127.0.0.1:9090

Open http://127.0.0.1:9090 to browse the discovered estate, entirely on-device.

Step 6: Carry it to the trunk​

On the trunk side (or a machine that can reach it), ingest the couriered bundle:

s9 discovery-mapping ingest-canonical-bundle --bundle /media/usb/leaf.tar.zst

What you proved​

  • A device discovered a source in place and mapped it to one canonical semantic model, stamping classification and provenance at the point of discovery, without creating a second copy of the estate.
  • The inventory is a signed, restart-safe projection that survives reboots and couriers by counting from its own durable watermark.
  • The estate crossed an air gap as a signed bundle, and was browsable offline the whole time, the deliberate answer to the no-link case, in place of live cross-cell convergence.