Installation
Get your machine ready to run Interchain Kit's Foundry harness and live local network
This guide gets your machine ready for Interchain Kit's two flows: the Foundry harness and the live local network. The live network's AvalancheGo + subnet-evm binaries are downloaded automatically on your first pnpm run up, so there's no AvalancheGo build to do and no AVALANCHEGO_PATH to set.
Prerequisites
| Requirement | Version | Used by |
|---|---|---|
| Node.js | 20+ | Both flows |
| pnpm | 9+ | Both flows |
Foundry (forge) | latest | Harness + contract builds |
No AvalancheGo setup required
The live-network flow auto-installs a pinned, checksum-verified AvalancheGo + subnet-evm release on first pnpm run up (cached under .interchain-kit/bin/). You only need an AvalancheGo build of your own if you want to override that — see the optional step at the end.
Step 1: Install Node.js and pnpm
Interchain Kit is a pnpm workspace pinned to [email protected]. Confirm Node 20+:
node --version # v20.x or laterIf you don't already have pnpm 9+, enable it via Corepack (ships with Node). On macOS where Node was installed in a root-owned location, corepack enable may need sudo or --install-directory <dir on PATH> — or just install pnpm directly:
corepack enable
corepack prepare pnpm@9 --activate
pnpm --version # 9.x or laterStep 2: Install Foundry
Foundry provides forge, used by the harness tests and contract builds:
curl -L https://foundry.paradigm.xyz | bash
foundryup
forge --versionStep 3: Clone Interchain Kit and Install
git clone https://github.com/ava-labs/interchain-kit
cd interchain-kit
pnpm installStep 4: Install the Contract Dependencies
The Solidity contracts depend on forge-std, OpenZeppelin, and icm-contracts, which live under contracts/lib/. They are not included in the clone and pnpm install does not fetch them, so install them before running the harness or building contracts:
cd contracts
forge install foundry-rs/forge-std
forge install ava-labs/[email protected]
forge install OpenZeppelin/[email protected]
cd ..Pin OpenZeppelin to v5.0.2
icm-contracts v1.0.9 imports OpenZeppelin upgradeable as @5.0.2. Installing a newer major (e.g. the current v5.x) makes the harness fail to compile (ReentrancyGuardUpgradeable.sol not found). Keep the @v5.0.2 pin above.
Verify Your Setup
With Node, pnpm, Foundry, and the contract dependencies installed, run the Foundry harness — no AvalancheGo needed:
pnpm test:harness # forge test --root contracts -vvA green run (18 tests across the example suites — icm-basics, ictt-erc20, ictt-native, and teleporter-patterns) means the contracts compile and the harness is wired up. To exercise the live network, continue to Local Network and run pnpm run up — it downloads the pinned AvalancheGo on first use.
Hitting a setup error? See Troubleshooting.
Optional: Use Your Own AvalancheGo Build
By default pnpm run up installs and runs a pinned AvalancheGo release. To run your own build instead — for example to test a local AvalancheGo change — build it from source and point AVALANCHEGO_PATH at the binary:
git clone https://github.com/ava-labs/avalanchego
cd avalanchego
./scripts/build.sh # builds build/avalanchego
cd graft/subnet-evm && ./scripts/build.sh # builds the subnet-evm plugin
export AVALANCHEGO_PATH=$HOME/avalanchego/build/avalanchegoUse a tagged release, not a dev branch
Point AVALANCHEGO_PATH at a build from a tagged release. A development branch (e.g. helicon-devnet) runs a C-Chain VM that won't produce blocks under tmpnet and silently stalls the boot. If up hangs after "deploying Teleporter," unset AVALANCHEGO_PATH to fall back to the pinned release.
Next Steps
Is this guide helpful?