Skip to main content
The Internet Computer Protocol (ICP) replica is the blockchain node software that runs the Internet Computer. This guide walks you through building and running the replica on your local machine.
Target Audience: This guide is for systems engineers, security engineers, and cryptographers who want to build and run the replica from source. If you’re an app developer looking to deploy canisters, use the Canister SDK instead.

​
Prerequisites

Before building the replica, ensure your system meets these requirements:

​
System Requirements

Hardware

  • x86-64 based system
  • Minimum 16 GB RAM/SWAP
  • 100 GB available disk space

Software

  • Ubuntu 22.04 or newer
  • Podman installed and configured
  • Git for cloning the repository

​
Install Podman

Podman is required for the containerized build environment: 
sudo apt update
sudo apt install -y podman
Verify Podman is working: 
podman info

​
Clone the Repository

1

Clone the IC repository

git clone https://github.com/dfinity/ic.git
cd ic
2

Verify the repository structure

ls -la
# You should see directories like: rs/, ic-os/, ci/, bazel/, etc.

​
Building the Replica

The IC repository uses Bazel as its build system, with a containerized build environment for reproducibility.

​
Build Environment

The repository provides a containerized development environment that includes all necessary dependencies:
1

Enter the development container

The container-run.sh script automatically pulls or builds the container image and drops you into a shell:
./ci/container/container-run.sh
This command will:
  • Check for Podman installation
  • Pull the ic-dev container image from GitHub Container Registry
  • Mount your repository and cache directories
  • Start an interactive shell inside the container
The first run will download a container image (~2-4 GB). Subsequent runs will reuse the cached image.
2

Build the replica binary

Inside the container, use Bazel to build the replica:
bazel build //rs/replica:replica
The replica binary will be available at:
bazel-bin/rs/replica/replica
You can also build specific subsets of the IC:Build only binaries:
bazel build //publish/binaries:bundle
Build only canisters:
bazel build //publish/canisters:bundle
Build IC-OS images:
bazel build //ic-os/guestos/envs/prod:bundle-update
bazel build //ic-os/hostos/envs/prod:bundle-update
bazel build //ic-os/setupos/envs/prod:bundle
3

Alternative: Build using the build script

For a complete build with artifacts organized for you, exit the container and use the build script:
# Build binaries only
./ci/container/build-ic.sh -b

# Build canisters only
./ci/container/build-ic.sh -c

# Build IC-OS images (includes binaries and canisters)
./ci/container/build-ic.sh -i

# Build both binaries and canisters
./ci/container/build-ic.sh -b -c
All artifacts will be organized in the artifacts/ directory:
artifacts/
├── release/        # Binaries and SHA256SUMS
├── canisters/      # Canister WASMs and SHA256SUMS
└── icos/           # IC-OS disk images
    ├── guestos/
    ├── hostos/
    └── setupos/

​
Verifying the Build

1

Check the replica binary

Verify the replica binary was built successfully:
./ci/container/container-run.sh
ls -lh bazel-bin/rs/replica/replica
You should see the binary with a size of several hundred MB.
2

Verify binary hash

Check the integrity of built binaries using SHA256 checksums:
# If you used build-ic.sh -b
cat artifacts/release/SHA256SUMS

a1b2c3d4e5f6... replica
f6e5d4c3b2a1... canister_sandbox
1a2b3c4d5e6f... ic-starter
...
3

Run a basic test

Verify the build environment by running some tests:
./ci/container/container-run.sh

# Run a specific test
bazel test //rs/types/types:types_test

# Run all non-system tests (recommended for local development)
bazel test //... --test_tag_filters=-system_test
Don’t run system_test tagged tests locally - they require infrastructure only available in the DFINITY network.

​
Running the Replica

Running a standalone replica locally requires additional configuration and is primarily used for development and testing. For deploying canisters to a local environment, use the Canister SDK’s dfx tool which includes a pre-configured local replica.
The replica binary (bazel-bin/rs/replica/replica) is the core Internet Computer node software. It requires:
  • A valid configuration file specifying network topology
  • Cryptographic keys for the node
  • State directories for blockchain data
  • Connection to other replicas (or specific test configuration)

​
Development Testing

For development and testing purposes, you can:
Run individual component tests:
./ci/container/container-run.sh
bazel test //rs/replica:replica_test

​
Code Quality Checks

Before submitting changes, run the linting and formatting checks: 
./ci/container/container-run.sh

# Rust linting
./ci/scripts/rust-lint.sh

# Or run individual checks
cargo clippy --all-targets --all-features
cargo fmt --all -- --check

​
Next Steps

Architecture

Understand the replica’s internal architecture

Development

Learn about contributing to the codebase

Testing

Explore the testing infrastructure

IC-OS

Deep dive into the operating system images

​
Troubleshooting

If podman info fails, ensure the Podman service is running:
systemctl --user status podman.socket
systemctl --user start podman.socket
For rootless Podman issues, check:
podman system migrate
The build process requires significant disk space. Check available space:
df -h $HOME
If running low, clean up Bazel cache:
./ci/container/container-run.sh
bazel clean --expunge
If the container image pull fails, you can build it locally:
./ci/container/build-image.sh --image ic-dev
This will build the container image from the Dockerfile in ci/container/.
The build script requires a clean Git working directory:
git status
# Commit or stash your changes
git stash
./ci/container/build-ic.sh -b
git stash pop

​
System Architecture Notes

The replica is a complex distributed system with multiple components:
  • Consensus Layer: Implements the Internet Computer consensus protocol
  • Execution Environment: Runs WebAssembly canisters
  • Message Routing: Handles cross-subnet communication (XNet)
  • Crypto Layer: Provides threshold cryptography and signatures
  • Networking: P2P communication between replicas
  • State Manager: Manages blockchain state and checkpoints
The binary uses multiple Tokio runtimes for isolation between components and runs sandboxed processes for security-critical operations like cryptography and canister execution.

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us