radicle-artifact

Secure artifact distribution for Radicle.

radicle-artifact helps you securely publish large files bound to git commits and tags, without bloating your repo.

The project is split into focused crates:

Crate	What it is
radicle-artifact	COB types/operations + the rad-artifact CLI.
radicle-artifact-node	The seeding daemon: iroh endpoint, iroh-blobs store + blob serving.
radicle-artifact-core	Shared substrate: wire protocol, CID helpers, endpoint identity. For library consumers.
radicle-artifact-client	Control-socket client for interaction with radicle-artifact-node

Note: COB operations with radicle-artifact (creating releases, registering artifacts, attesting, and adding locations) never touch the iroh stack; the radicle-artifact-node crate is needed to seed or fetch artifacts.

Principles

• Signed and verifiable — every artifact is content-addressed via a CID (with a BLAKE3 hash) and bound to the exact commit it was built from. Every interaction is signed by the user's Ed25519 key.
• Decentralized — artifacts can be seeded by multiple users and fetched in a peer-to-peer fashion, allowing for redundancy and resilience.
• Multi-party — signing, attesting, and redacting are open to independent parties by design, aggregating trust while reducing the attack surface.
• Transport-agnostic — an artifact can have many locations and travel over HTTP, iroh, IPFS, magnet links, rasl://, or any URL scheme. The rad-artifact CLI ships with iroh-blobs for reliable peer-to-peer seeding and fetching, plus HTTP fetching.

Trust is anchored in the repository's delegates, its maintainers as named in the Radicle repository identity; by default you see only the releases and artifacts they or you authored.

radicle-artifact is useful for distributing any data tied to code: binaries, static sites, model weights, and scientific datasets.

Why

Git was never built to distribute large files and binaries.

Existing solutions like Git LFS are designed around a server-client centric model, resolving through a single blessed endpoint; if that host moves, dies, or rate-limits you, the pointers still exist in git but the bytes are unreachable. There's no built-in fallback or multi-source resolution.

Moreover, existing solutions have no signing model of their own; the only option is signing the enclosing Git commit or tag, which carries a single signature and can't express independent, multi-party attestation. With radicle-artifact, signing, attestation, and redaction are multi-party by design, built on Radicle's key-based identity, giving you verifiable assurances about artifact provenance.

For a more elaborate comparison to Git LFS, git-annex, and Git's upcoming Large Object Promisor, see the comparison document.

Installation

Install a prebuilt binary:

curl -sSf https://files.radicle.dev/releases/radicle-artifact/install | sh

The installer also links rad-art to rad-artifact, so you can use the short name, or rad art <command> as a rad subcommand.

Or build from source via crates.io:

cargo install radicle-artifact        # the rad-artifact CLI (COB operations)
cargo install radicle-artifact-node   # the seeding daemon (optional, for iroh seeding)
ln -s rad-artifact ~/.cargo/bin/rad-art   # optional: the rad-art / rad art alias

Or depend on the cargo crate straight from the Radicle git remote:

[dependencies]
radicle-artifact = { git = "https://radicle.norman.life/z4VYyJ9KuwMNkXGQnmKuGPGKw3inv.git" }

Note: The radicle-artifact cli requires Radicle installed.

Workflow

1. Tag: Create a release tag or commit, ideally a canonical reference. Push it to your Radicle remote (git push rad); see the note below.
2. Build: Build your release artifacts.
3. Register: Register artifacts in a release with the rad-artifact register <PATH> command, which creates the release if it doesn't exist and records the artifact CID. This is signed discovery metadata in the COB, synced over the Radicle protocol, not the bytes.
4. Seed: Upload artifacts to an HTTP server and add the location with rad-artifact location add, or seed directly over iroh-blobs by starting the local seeder node (rad-artifact node start) and seeding the file (rad-artifact seed <PATH>).
5. Download: Download artifacts to disk with rad-artifact download, or fetch them into the local store without writing a file using rad-artifact fetch.
6. Verify: Check a file you downloaded or rebuilt against the COB with rad-artifact verify <PATH>. It hashes the file and looks for an artifact with that CID, honouring the same delegate and redaction rules as list/show. Reads local storage only: no daemon, no network, no signer.
7. Attest: Other delegates check out the release version, build the artifacts independently, verify the CIDs match, and attest. Note that attest records a signed claim and rehashes nothing itself, so run verify first.
8. Redact: If an artifact is found to be compromised or fails reproducibility checks, redact it with a reason. A redaction by a delegate makes verify fail, so it withdraws a published artifact without touching wherever the bytes are hosted.

Note: A release is bound to a revision in your Radicle storage, not your working copy. Release operations resolve <REVISION> against Radicle storage, so the commit (or annotated tag) must already be there before you can register against it. Push it first with git push rad (and git push rad --tags for an annotated tag). If the revision is missing, the command fails to resolve it.

See CONTEXT.md for a glossary of the project's terminology: Register, Seed, Add, Announce, and the drift states they produce.

How it works

A Release is a Radicle COB (Collaborative Object) identified by a Release ID linked to a Git commit and optionally an annotated tag.

Releases contain one or more Artifacts, each identified by a content identifier (CID) and a name string. Each artifact tracks the DID that originally added it (the artifact author), and only that DID can update the artifact's name. Users can help seed artifacts by adding location URLs for any artifact, enabling decentralized seeding.

Users can also attest to an artifact, recording that they independently verified the CID matches a build from the same commit. They can also redact an artifact with a reason, signaling that it should not be used (e.g. due to a supply chain compromise or build reproducibility failure). Redaction is permanent: it supersedes any prior attestation from the same DID and prevents that DID from attesting again.

The artifact author and repository delegates can attach free-form metadata entries to an artifact, e.g. a build-environment note or an SBOM URL. Keys are strings; values are arbitrary JSON. The keyspace is shared (last-writer-wins). Per-entry attribution is not stored on the entry itself, but every write is a signed COB op, so the writer's DID is recoverable from the log.

Each user is identified by a DID that is currently mapped 1:1 to the Radicle NodeID, an Ed25519 public key. This could change in the future — there are ongoing discussions to decouple DIDs from NodeIDs as part of a broader effort to support multiple devices and agents, but for now the two are practically equivalent.

This COB is build-system agnostic. It works with any toolchain or build process that produces addressable artifacts. Ideally your builds are deterministic (reproducible), which lets other delegates independently verify artifacts and record attestations. However, deterministic builds are not a requirement; you can use radicle-artifact purely for publishing and discovering release artifacts without attestation.

Data model

Release
├── id: Oid                           # release ID
├── oid: Oid                          # git commit ID the release is linked to
├── tag: Option<Oid>                  # optional annotated tag OID linked to the commit
├── creator: Did                      # user that created the release
└── artifacts: Map<CID, Artifact>
    └── Artifact
        ├── author: Did               # user that added this artifact
        ├── name: String              # human-readable description (only author can update)
        ├── locations: Map<Did, Set<Url>>
        ├── attestations: Set<Did>      # users that verified the CID
        ├── redactions: Map<Did, String> # users that flagged the artifact, with reason
        └── metadata: Map<String, JsonValue> # free-form annotations (author/delegate writes)

• Cid — a string newtype for any content-addressing scheme (CIDv1, sha256, etc.)
• Locations — plain URLs (https://, radiroh://, ipfs://, magnet:, and rasl:// with the first two supported natively).
• Each user can contribute multiple URLs per artifact; duplicate URLs are deduplicated automatically

Relationship to the Radicle node

radicle-artifact is a companion to Radicle, not a replacement for it. It links the radicle crate as a library (it never shells out to the rad CLI) and borrows two things from your local Radicle installation:

• Identity — your Ed25519 keystore. The same secret signs every COB op and derives the iroh seeder's endpoint id, so an encrypted keystore needs RAD_PASSPHRASE (or an interactive prompt). Your DID is your Radicle NodeID.
• Storage — your Radicle profile home and git storage, where releases are read and written as COBs.

A COB write (register, attest, location add, ...) is a local git operation. By default the CLI then announces the change to the network by calling the running Radicle node over its control socket; this is the only step that needs the node up. Pass --no-announce to skip it and announce later with rad sync -a.

For other peers to actually discover an artifact, they also need to fetch the COB refs from your node, which typically happens after receiving the announcement.

Everything else works without the Radicle node running: computing CIDs, reading releases, seeding, and fetching artifacts. The artifact seeder node is a separate process (the rad-artifact-node binary, spawned by rad-artifact node start) from the Radicle node with its own control socket; it shares only your Ed25519 identity and does not talk to the Radicle node. Fetching resolves locations (iroh or HTTP) directly and never consults it.

Collaboration and trust model

All actions on a release are signed by the acting user's DID. Most actions — creating a release, adding an artifact, attesting, redacting, registering a location — are open to any user. The exceptions are renaming an artifact (constrained to the artifact's original author) and writing metadata (constrained to the artifact's author or a repository delegate).

Trust is inherited from the repository's delegate set. By default, commands consider only releases and artifacts authored by a delegate or by the local user. Contributions from other users are hidden. Pass --all-authors to widen the view. Targeting a specific release with --release <id> always works regardless of who authored it.

Artifact types

radicle-artifact supports two artifact types: blobs and collections, both encoded as a CID.

Kind	CID multicodec	Hash	Contents	Transports
Blob	raw (0x55)	blake3 (0x1e)	a single file	HTTP, iroh-blobs
Collection	blake3-hashseq (0x80)	blake3 (0x1e)	a collection of files, i.e. folder	iroh-blobs only

Blobs are the common case: one binary, archive, or model file. Collections derive a hash from a collection of files, i.e. directory, and are useful when the collection represents a single artifact, e.g. static frontend builds.

A folder can register either way. rad-artifact register <DIR> asks which you want: one collection artifact for the whole tree, or one blob artifact for each file directly inside the folder (--each, which does not recurse). Register each file when the folder only holds artifacts that stand alone, e.g. the binaries from a build — peers can then fetch, verify, and attest one binary without the rest.

Other URL schemes (ipfs://, magnet://, rasl://, …) can be recorded as locations and resolved by external tools, but the CLI itself only fetches HTTP and iroh.

Actions

Action	Description
Create	Initialize a release for a git OID (internal, auto-created by RegisterArtifact)
RegisterArtifact	Add an artifact (CID + name), or update name if author re-sends
AddLocation	Add a discovery URL for an artifact
RemoveLocation	Retract a previously added URL
Attest	Record independent verification of a CID
Redact	Flag an artifact as compromised/withdrawn
SetMetadata	Attach a free-form key/value entry (author/delegate only)
RemoveMetadata	Remove a metadata entry (author/delegate only)

COB type

dev.radicle.artifact

CLI usage

<REVISION> accepts a full OID, abbreviated hash, or tag name of a commit or annotated tag. It is resolved against Radicle storage, so push it first (git push rad, or git push rad --tags for an annotated tag).

Every command accepts these global options, before or after the subcommand:

• --repo <RID> (or -r) targets a specific repo (defaults to cwd).
• --no-announce skips the network announcement after writes.
• --no-input disables interactive prompts (for scripts and CI).

Commands that do not read or write a repository ignore them: --repo has no effect on cid, locate, node and watch, and --no-announce has no effect on read-only commands such as list and show.

--repo only needs the repository to be in local storage, so commands work from any directory:

rad-artifact list --repo rad:z4VYyJ9KuwMNkXGQnmKuGPGKw3inv

COB-facing commands

rad-artifact register <PATH> [--revision <REVISION>] [-n <NAME>] # register artifact (creates release if needed; records a sizeBytes hint, skip with --no-size)
rad-artifact register <DIR> [--each|--collection]                # a folder asks which; --no-input or -n makes one collection
rad-artifact register --cid <CID> --revision <REVISION> -n <NAME>  # register a precomputed CID without local bytes
rad-artifact location add --revision <REVISION> --cid <CID> <URL>    # add discovery URL
rad-artifact location remove --revision <REVISION> --cid <CID> <URL> # remove discovery URL
rad-artifact attest <REVISION> --cid <CID>                       # attest to an artifact
rad-artifact redact <REVISION> --cid <CID> -m <REASON>           # redact an artifact
rad-artifact metadata set --revision <REVISION> --cid <CID> [--json] <KEY> <VALUE>  # attach metadata
rad-artifact metadata unset --revision <REVISION> --cid <CID> <KEY>                 # remove metadata
rad-artifact show <REVISION> [--pretty] [--all-authors]          # show release
rad-artifact list [--pretty] [--all-authors]                     # list releases (default: delegate- or local-authored)
rad-artifact cid <PATH>                                          # compute BLAKE3 CID
rad-artifact verify <PATH> [--all-authors]                       # check a local file against the registered artifacts
rad-artifact fetch [<REVISION> --cid <CID>]                      # fetch artifact into the store (interactive without args)
rad-artifact download [<REVISION> --cid <CID>] [-o <PATH>]       # download artifact to disk (interactive without args)

Node control

rad-artifact node start [--foreground] [--force]                 # start the seeder daemon
rad-artifact node stop                                           # graceful shutdown
rad-artifact node status [--json]                                # endpoint id, seeded count, disk, traffic
rad-artifact node list [--json]                                  # list CIDs the node is seeding for this repo
rad-artifact node seed <PATH> [--release <ID>] [--reference] [--no-location]  # compute CID from PATH, seed, add location
rad-artifact node unseed --cid <CID> [--release <ID>]            # stop seeding + retract our radiroh:// locations
rad-artifact node logs [--follow] [-n <LINES>]                   # tail <home>/artifacts/node.log

rad-artifact seed and rad-artifact unseed are top-level aliases for rad-artifact node seed / node unseed.

Watching

rad-artifact watch [RID...] [--budget <SIZE>] [--sweep <SECS>] [--dry-run]  # seed trusted artifacts as peers publish them

Reconciling

rad-artifact reconcile [--all-repos] [--remove-orphaned <CID>] [--remove-orphaned-self]  # fix COB drift

Seeding via the local node

Seeding involves running a daemon that holds a persistent iroh-blobs store that serves the files over iroh connection. Start it once and it survives shell exits and terminal closes:

$ rad-artifact node start
Node started (socket: /Users/you/.radicle/artifacts/control.sock)

$ rad-artifact seed ./dist/linux-amd64.tar.gz
Seeded baf...abc (12.4 MiB, new tagged)
Added radiroh location to release abc1234

The daemon stores blobs under <home>/artifacts/store/ (persistent iroh-blobs FsStore), tracks what to seed via seeded/{rid}/{release}/{cid} tags, and writes a JSON log to <home>/artifacts/node.log (rotated on each start). The control socket lives at <home>/artifacts/control.sock (mode 0600); set RAD_ARTIFACT_SOCKET to override.

Log verbosity is controlled via RUST_LOG, which covers both this crate and iroh — e.g. RUST_LOG=iroh_blobs=debug rad-artifact node start. Default filter: warn,iroh=warn,iroh_blobs=warn,radicle_artifact=info.

The node never writes COB ops — every signed location write (add_location, remove_location) happens client-side. The daemon's identity (the iroh endpoint id) currently derives from the same Ed25519 secret as your Radicle DID, so RAD_PASSPHRASE is required on start when the keystore is encrypted (or the parent CLI will prompt).

rad-artifact reconcile compares the node's seeded set to the COB locations under your DID. It auto-adds missing radiroh://{endpoint_id} URLs for artifacts you're seeding, and flags drift in the other direction (URLs we left behind, stale endpoint ids) without auto-removing — pass --remove-orphaned <CID> or --remove-orphaned-self explicitly when you want it gone. It also reports dangling tags — CIDs the node is seeding that no release references at all (so no location can anchor to them); reclaim them with rad-artifact unseed --cid <CID>.

Watching for new artifacts

rad-artifact seed seeds one artifact you name. rad-artifact watch keeps seeding whatever your trusted peers publish, so you can run a mirror: a machine that holds a copy of every artifact a repository's delegates release, and keeps the bytes reachable when the original seeder goes away.

$ rad-artifact watch --budget 50G
Watching for trusted artifacts (budget 50.0 GiB)
Now seeding bafkr4ig6iu...wvva; added location to release 3f2a91c

It runs until you interrupt it, so supervise it with launchd or systemd. It needs both nodes up: the Radicle node for the COBs and the event stream, and the artifact node for the bytes.

Two things decide what it seeds:

• Which repositories — every repository your Radicle node seeds (rad seed <RID>). Name one or more RIDs to narrow it to those. A named repository your node does not seed is an error, because its COBs would never arrive.
• Which artifacts — the same trust rules as verify: an artifact registered by a delegate (or by you) in a release a delegate created, and redacted by nobody who counts. Everything else is ignored.

It notices new artifacts two ways. The Radicle node's event stream reports which repositories' refs moved, so an artifact registered by a peer is picked up within seconds of the COB arriving. A full sweep every --sweep seconds (15 minutes by default) covers anything that landed while either process was down.

For each artifact it fetches the bytes through your artifact node, tags them as seeded, then adds your radiroh:// location to the release with a signed COB write and announces it — the same steps as rad-artifact fetch --seed followed by a location add.

--budget <SIZE> caps the total the node seeds, e.g. 50G. Once the store reaches it, the watcher reports what it is holding back and stops fetching. Without a budget it seeds everything it trusts, which on a busy repository is a lot; --dry-run reports what it would seed and fetches nothing.

The watcher only ever adds. If a delegate redacts an artifact you already seed, drop it with rad-artifact unseed --cid <CID>.

radiroh:// location format

Seeded artifacts get a radiroh://<endpoint-id> location, where <endpoint-id> is the iroh endpoint id encoded as lowercase base32. See docs/uri-scheme.md for the full grammar.

How the COB is implemented

Note: this COB is still in early development and the API is subject to change. Feedback and contributions are very welcome!

The COB is implemented using the radicle crate's COB framework.

The Release type implements three traits that plug into the framework:

• CobWithType — registers the type name dev.radicle.artifact
• Cob — defines how to build initial state from the first operation (from_root) and how to apply subsequent operations (op)
• Evaluate — deserializes git entries into typed operations and feeds them through the state machine

Each mutation (create, add artifact, attest, redact, etc.) is an Action that implements CobAction. Actions are written to git as signed entries via Transaction, and state is reconstructed on read by replaying the operation DAG.

What the COB does	Module	Key types
Define and evaluate the state machine	radicle::cob	Evaluate, Op, Entry
Persist and transact operations as git objects	radicle::cob::store	Store, Transaction, Cob, CobAction
Read from and write to the git repository	radicle::storage	ReadRepository, WriteRepository, SignRepository
Sign entries with the user's Ed25519 key	radicle::crypto	Signer, Signature, Device
Announce changes to the network	radicle::node	Node, Announcer

Cutting a release

See RELEASE.md for the full process — drafting the changelog, cutting the crate release with cargo release, and building and uploading cross-platform binaries alongside the install script.

License

MIT OR Apache-2.0