Skip to main content
The Internet Computer provides a robust system for verifying that IC-OS update images can be reproduced from source code. This ensures transparency and trustworthiness of the deployed code.

​
Overview

Each release proposal on the Network Nervous System (NNS) includes detailed verification instructions. The verification process builds the IC from the specified commit and compares the locally built artifacts with those published on the CDN.
Build reproducibility ensures that the exact same binary artifacts are produced from the same source code, proving that deployed code matches the public repository.

​
Prerequisites

Before verifying releases, ensure your system meets these requirements:

Operating System

Ubuntu 22.04 or higher

Python

Python 3.x installed

curl

curl utility installed

Disk Space

About 100 GB free in $HOME

​
Installing Dependencies

sudo apt-get update
sudo apt-get install -y curl python3 git podman

​
Quick Start

To verify an IC OS Version Election proposal:
1

Get the Commit ID

Find the commit ID from the release proposal.
2

Run Verification

Execute the repro-check script:
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -p <proposal_number>
Replace {COMMIT_ID} with the actual commit hash and <proposal_number> with the proposal ID.
3

Wait for Completion

The script will:
  • Clone the IC repository
  • Build all IC-OS images
  • Download published artifacts
  • Compare hashes
This process can take 1-2 hours depending on your system.
Always use versioned repro-check URLs (with {COMMIT_ID}) instead of master to ensure compatibility between the script and the build system for that specific commit.

​
Verification Methods

You can verify releases using either a proposal number or a Git commit hash: 
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -p <proposal_number>
The script will:
  • Fetch the proposal data from the NNS
  • Extract the git commit hash
  • Verify the proposal’s release package hash
  • Build and compare artifacts

​
Component-Specific Verification

You can verify individual IC-OS components to save time and resources: 
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --guestos
Verifies:
  • GuestOS update image (update-img.tar.zst)
  • Launch measurements for confidential computing
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --hostos
Verifies:
  • HostOS update image (update-img.tar.zst)
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --setupos
Verifies:
  • SetupOS disk image (disk-img.tar.zst)
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --recovery
Verifies:
  • Recovery GuestOS update image
If no component flags are specified, all components (GuestOS, HostOS, SetupOS, and Recovery) are verified by default.

​
Advanced Options

​
Custom Cache Directory

By default, the script uses ~/.cache/repro-check. You can specify a different location: 
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --cache-dir /path/to/cache

​
Clean Cache Before Running

curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --clean
The --clean flag cannot be used with a manually specified --cache-dir for safety.

​
Download Source Selection

Choose which CDN to download artifacts from: 
# Download from download.dfinity.systems (default)
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --download-source systems

# Download from download.dfinity.network
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --download-source network

# Download from both and compare
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --download-source both

​
Debug Mode

Enable verbose logging and preserve temporary files: 
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --debug

​
Dry Run

Build locally without performing verification: 
curl -fsSL https://raw.githubusercontent.com/dfinity/ic/{COMMIT_ID}/ci/scripts/repro-check | \
    python3 - -c {COMMIT_ID} --dry-run

​
Understanding the Verification Process

The repro-check script performs several steps:
1

Environment Checks

  • Verifies x86-64 architecture
  • Checks Ubuntu 22.04+
  • Validates 16+ GB RAM
  • Ensures 100+ GB free disk space
  • Installs missing dependencies (git, podman)
2

Repository Setup

  • Clones IC repository from GitHub
  • Checks out the specified commit
  • Verifies git integrity
3

Download Remote Artifacts

  • Downloads IC-OS images from CDN
  • Downloads SHA256SUMS files
  • Downloads launch-measurements.json (for GuestOS)
  • Caches downloads for future runs
4

Local Build

  • Builds IC-OS images using ./ci/container/build-ic.sh --icos
  • Extracts built artifacts
5

Verification

  • Computes SHA-256 hashes of local builds
  • Compares with remote CDN artifacts
  • Verifies launch measurements (for GuestOS)
  • Reports results

​
Verification Output

Successful verification output: 
[ℹ️] Verification successful for GuestOS!
[ℹ️] The sha256 sum for GuestOS from the artifact built locally and the one fetched from remote match:
	Local = abc123...
	Remote = abc123...

[ℹ️] Verification successful for HostOS!
[ℹ️] The sha256 sum for HostOS from the artifact built locally and the one fetched from remote match:
	Local = def456...
	Remote = def456...

[ℹ️] Total time: 1h 23m 45s
Failed verification output: 
[❌] Error! The sha256 sum from the remote does not match the one we just built for GuestOS.
Local:   abc123...
Remote:  xyz789...
If verification fails, this indicates a potential issue with build reproducibility or the published artifacts. Report such issues to the DFINITY Foundation.

​
Verifying Proposals

When verifying a proposal, additional checks are performed:
The script verifies that the release package URLs in the proposal point to artifacts with the correct SHA-256 hash.
[ℹ️] The proposal's artifact and hash match.
Compares the proposal’s release package hash with the artifact stored on the CDN:
[ℹ️] The GuestOS sha256sum from the proposal and remote match.
For GuestOS, verifies the confidential computing launch measurements:
[ℹ️] The GuestOS measurements from the proposal and remote match.

​
Cache Management

The repro-check script uses caching to speed up repeated verifications:

​
Cache Location

Default: ~/.cache/repro-check/

​
Cache Structure

~/.cache/repro-check/
├── <git-hash-1>/
│   ├── download.dfinity.systems/
│   │   ├── guest-os/
│   │   ├── host-os/
│   │   └── setup-os/
│   └── download.dfinity.network/
├── <git-hash-2>/
├── repo/  # Git repository cache
└── tmp-*/  # Temporary build directories

​
Cache Cleanup

The script automatically keeps the 2 most recent commit caches and removes older ones. Manual cleanup: 
rm -rf ~/.cache/repro-check

​
Troubleshooting

The build and verification process requires an x86-64 system.
[❌] Please run this script on x86_64 architecture.
Use a compatible system or cloud instance.
Ensure you have at least 100 GB free:
df -h $HOME
Consider using --cache-dir to specify a volume with more space:
python3 repro-check -c {COMMIT_ID} --cache-dir /mnt/large-volume/cache
If fetching the commit fails:
[❌] Could not fetch commit {COMMIT_ID} from the remote repository.
  • Verify the commit hash is correct
  • Check your internet connection
  • Ensure you have access to github.com/dfinity/ic
If artifact downloads fail:
[❌] Could not download URL. Error: ...
  • Check your internet connection
  • Try a different download source with --download-source
  • Verify the commit has been published to the CDN
If the local build fails:
  • Ensure all dependencies are installed
  • Check build logs for specific errors
  • Verify you have enough RAM and disk space
  • Try running in debug mode: --debug

​
System Requirements Summary

Recommended System

For optimal verification performance:
  • CPU: 8+ cores
  • RAM: 32 GB+
  • Disk: 200 GB+ free space
  • Network: High-speed internet connection
  • OS: Ubuntu 22.04 LTS

​
Best Practices

Use Versioned URLs

Always use the commit-specific repro-check URL, not master.

Verify Critical Releases

Verify releases before voting on NNS proposals.

Cache Results

Keep the cache directory to speed up re-verification.

Monitor Progress

Use debug mode for long-running verifications to see detailed progress.

​
Example: Complete Verification Workflow

Here’s a complete example verifying a specific release: 
# 1. Check system requirements
df -h $HOME  # Ensure 100+ GB free
free -h      # Ensure 16+ GB RAM

# 2. Install dependencies
sudo apt-get update
sudo apt-get install -y curl python3 git podman

# 3. Verify a proposal (example: proposal #123456)
export COMMIT_ID="a1b2c3d4e5f6..."
export PROPOSAL_NUM="123456"

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

# 4. Check results
echo $?  # Should be 0 for success

​
Next Steps

System Requirements

Review detailed system requirements

Building the IC

Learn how to build IC components

IC-OS Overview

Understand IC-OS architecture

Release Dashboard

View current and past releases

Build docs developers (and LLMs) love

Get started for freeTalk to us