dfinity/ic: building the replica, and verifying a mainnet upgrade

The README tells four of its five audiences to leave

The Getting Started section is unusual in being mostly a set of referrals away from the code. Application developers are pointed at the Canister SDK, which the README says is optimised for the job and gets a local replica running in under two minutes without systems code. Blockchain enthusiasts wanting to understand the protocol rather than an implementation are sent to the consensus write-up and the Interface Specification. Engineers building an SDK, oracle or wallet are sent to the Interface Specification for low-level interaction.

The fifth audience is the one the repository is for: systems engineers, security engineers and cryptographers who want to see what happens under the hood by reading source and building locally.

There is a fourth persona mentioned for completeness, the miner, and the README is careful to correct expectations. The Internet Computer Protocol is a blockchain, but it has no traditional mining or validation, using cryptography that does not require it. It does require independent node providers; the repository offers both its source code and the Internet Computer wiki as a potentially better resource.

So the scope is narrow by design: this is the replica, described in the README as the client in some blockchains, the software compiled and run by the machines that together make up the Internet Computer.

What is actually in the tree, and it is not one language

The primary language is Rust, and `Cargo.toml` is a workspace with a long member list. Under `packages/` sit the Rust libraries the rest of the system depends on: `ic-ed25519`, `ic-secp256k1`, `ic-secp256r1`, `ic-sha3`, `ic-hpke`, `ic-pub-key`, `ic-signature-verification`, `ic-error-types`, `ic-http-types`, `ic-management-canister-types`, `ic-heap-bytes` and its derive macro, plus ICRC ledger crates and `pocket-ic`, which is a testing harness for canisters.

Under `rs/` are the binaries and services, and the directory names describe the components: `artifact_pool`, `backup`, `canister_client`, `canister_sandbox`, `canonical_state` with its `tree_hash` and `certification_version` submodules, `boundary_node` with rate limiting and salt sharing, and a large `bitcoin/` subtree covering an adapter, checker, ckbtc minter and agent, client, consensus, mock, replica types, service and validation.

The presence of `go.mod` and `cpp/` alongside `rs/` and `packages/` is the useful signal. The repository is not a single Rust program; it is a system assembled from several languages plus `ic-os/` for the operating system images, `ci/` for continuous integration, `bazel/` and `MODULE.bazel` for the build, and `toolchains/`. The Go module declares `go 1.19` and depends on cobra, testify, go-cmp, fatih/color and schollz/closestmatch, which is a command line tool set rather than node software.

Building: a containerised script, 100 GB of disk

System requirements are stated before anything else: an x86-64 based system with a minimum of 16 GB of memory or swap, 100 GB of available disk space, Ubuntu 22.04 or newer, and Podman.

The build is driven by a script in `ci/container/`. To build all IC-OS images in a containerised environment, run `build-ic.sh` with the `-i` flag, and to build only the binaries or only the canisters, use `-b` and `-c`:

./ci/container/build-ic.sh -b -c

Everything the script produces lands in a top-level `artifacts/` directory. For details on the IC-OS images themselves, the README points to `ic-os/README.adoc`.

The size requirement is not a formality. This is a build of a node operating system image plus a multi-language workspace, and the README also asks for 100 GB of free space just for the verification step below, in `$HOME` or another volume chosen with the `--cache-dir` option. Plan the disk before you plan the build.

Verifying an upgrade proposal before it goes live

This is the part of the repository with the clearest external use, and it is not widely known. Each release proposal on the dashboard includes verification instructions, and the README describes a reproducible build check for IC-OS update images.

Prerequisites are Ubuntu 22.04 or higher, Python 3.10 or higher, curl installed with `sudo apt install curl`, about 100 GB of free disk in `$HOME` or a volume set through `--cache-dir`, and internet access.

The script is fetched from GitHub raw and piped to Python, and it accepts either a proposal number or a commit hash:

curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -p <proposal_number>

The same URL with `-c {COMMIT_ID}` verifies by git commit instead. The README marks one instruction as IMPORTANT and it deserves attention: always use a versioned repro-check URL with the actual commit hash rather than `master`, because the script and the build system have to match the specific commit being checked. Using `master` gives you a verifier that may not correspond to the code it is verifying.

The script does more than rebuild. Alongside the rebuild it checks that the `SHA256SUMS` files it downloads from the CDN are covered by something, and the README begins describing build provenance in terms of GitHub Actions security guarantees before the text is truncated.

Release cadence, licensing and the honest limits of this repository

Release tags carry the date and a build identifier, so recent ones read like `release-2026-10-08_03-33--all-in-one` and `release-2026-10-08_03-33-base`, alongside `release-2026-10-02_03-31--all-in-one`. The distinction between the all-in-one and base artefacts is visible in the names alone: one bundles everything, the other does not. The repository was pushed to on 2026-10-16, so anyone pinning a commit for verification should use that exact version.

Licensing is the awkward part and the README does not smooth it over. The licence is listed as Other, a custom licence GitHub cannot classify, with a LICENSE file at the root. For a repository under the DFINITY Foundation, a Swiss not-for-profit organisation based in Zurich with research centres in Palo Alto, San Francisco and Zurich, that means you should read the LICENSE file rather than assume a standard permissive grant. This is not legal advice, but it is the one file you should open before reusing any of `packages/`.

The final limit is the practical one. This code base assumes you can run a container build that consumes a hundred gigabytes and then reproduce a node image. That is a real barrier to contribution, and it is the reason the verification path takes curl plus Python rather than a local clone and a build.

Against the SDK, and against reading the specification instead

For anyone building on the Internet Computer, the honest comparison is with not using this repository at all, which is exactly what the README recommends for four of its five audiences.

Against the Canister SDK: the SDK is the right tool for deploying code, and the README's stated reason is that it is lighter and gets you running in under two minutes. Nothing in this repository changes that. The SDK builds a local replica for you; this repository contains the code that replica is built from.

Against the Interface Specification and the research write-ups: if your question is what the protocol requires rather than what the node does, the specification is shorter, more authoritative and language neutral. The replica source is the answer to what the implementation actually does.

There is one comparison this repository wins outright, and it is the one its verification tooling exists for. A vendor-supplied binary upgrade for a chain you hold tokens on is exactly the situation where independent reproduction matters, and a script that rebuilds the image and checks the CDN checksums gives you something to point at. Nothing in the SDK or the specification does that.

Editorial conclusion

Use this repository if you are a systems or security engineer who needs to build the replica from source or independently verify an IC-OS upgrade proposal. Do not use it to deploy a canister, because the README itself redirects application developers to the Canister SDK and blockchain enthusiasts to the consensus write-ups. Verify first that your machine has an x86-64 CPU, at least 16 GB of memory or swap and 100 GB of free disk, since the build will not fit on a small instance.

Frequently asked questions

Official sources

1. dfinity/ic on GitHub
2. Issues
3. Project website
4. README
5. Releases