.nornir/agent-guide.md

The agent — guide

Class: guide · Function: agent. Architecture: agent-design.md. How to pull artifacts internet-side and pack them into a .znippy to carry across the airgap.

Build the agent

cargo build -p holger-agent-cli      # → target/debug/holger-agent

Pull a source into a `.znippy`

The agent moves artifacts from a source connector to a target connector. The common airgap job is "pull an upstream registry, pack to a znippy archive":

# pull crates.io (the world connector) → an immutable .znippy
holger-agent pack --from crates.io --to znippy --repo rust-mirror --out rust-mirror.znippy

# pull a Nexus repo (Basic auth) → a .znippy
holger-agent pack --from nexus --base-url https://nexus.corp --repo maven-releases \
  --to znippy --out maven-releases.znippy

The output is one content-addressed (blake3), immutable archive — the tamper-evident "shipping crate". Carry it across the boundary on USB/optical.

Serve it on the secure side

On the secure-side server, point a read-only repository at the archive (no egress needed):

Repository(
    ron_name: "rust-mirror",
    ron_repo_type: "rust",                 // znippy-rust backend, read-only
    ron_archive_path: Some("/var/lib/holger/rust-mirror.znippy"),
    ron_out: Some(RepositoryIO( ron_storage_endpoint: "znippy", ron_exposed_endpoint: "default" )),
)

Now a stock cargo inside the zone resolves the whole mirror from the sealed archive over the real sparse protocol — see serve-guide.

Keep the connector base URL correct

Because the connectors are SSRF-guarded (see auth-guide §D.5), a wrong base URL makes legitimate downloads get rejected as cross-origin. Set the connector's base URL to the exact scheme+host the upstream serves downloads from.

Round-trip test (the release gate uses this)

The release gate runs an agent push → store → pull round-trip for rust, jar, and wheel. Reproduce it locally against a mannequin-mocked world — see testing-guide.