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

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)

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

Tag: Create a release tag or commit, ideally a canonical reference. Push it to your Radicle remote (git push rad); see the note below.
Build: Build your release artifacts.
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.
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>).
Download: Download artifacts to disk with rad-artifact download, or fetch them into the local store without writing a file using rad-artifact fetch.
Attest: Other delegates check out the release version, build the artifacts independently and attest the CIDs match.
Redact: If an artifact is found to be compromised or fails reproducibility checks, redact it with a reason.

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.

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).

These global options apply to every command:

--repository <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).

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 --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 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.

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>.

`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

Name		Name	Last commit message	Last commit date
Latest commit History 366 Commits
.buildkite		.buildkite
.radicle		.radicle
crates		crates
docs		docs
public		public
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTEXT.md		CONTEXT.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Makefile		Makefile
README.md		README.md
RELEASE.md		RELEASE.md
cliff.toml		cliff.toml
install.sh		install.sh
release.toml		release.toml

Navigation Menu

Repository files navigation

radicle-artifact

Principles

Why

Installation

Workflow

How it works

Data model

Relationship to the Radicle node

Collaboration and trust model

Artifact types

Actions

COB type

CLI usage

COB-facing commands

Node control

Reconciling

Seeding via the local node

`radiroh://` location format

How the COB is implemented

Cutting a release

License

About

Releases

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

radicle-artifact

Principles

Why

Installation

Workflow

How it works

Data model

Relationship to the Radicle node

Collaboration and trust model

Artifact types

Actions

COB type

CLI usage

COB-facing commands

Node control

Reconciling

Seeding via the local node

radiroh:// location format

How the COB is implemented

Cutting a release

License

About

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages

`radiroh://` location format