icp-cli-network-launcher

Launches a local ICP test network powered by PocketIC. Designed as the network backend for icp-cli, but can also be used standalone.

# Start a local network with default settings (application + NNS subnets)
icp-cli-network-launcher --gateway-port=4943

# Start with Bitcoin integration (implicitly enables Internet Identity)
icp-cli-network-launcher --gateway-port=4943 --bitcoind-addr=127.0.0.1:18444

The CLI interface is stable across releases of PocketIC (see SPEC.md), and the primary way pocket-ic is installed for use with icp-cli is by installing icp-cli-network-launcher. The downloadable package contains both the launcher and the pocket-ic binary it supports.

One launcher version is tied to one PocketIC version — if the PocketIC version is a published release, the launcher version matches (e.g. 10.0.0); if it's a git hash, it's added as a tag (e.g. 10.0.0+97ad9167). The launcher expects the pocket-ic binary in the same directory.

CLI Reference

Flags

Flag	Type	Description
--gateway-port	integer	Port for the HTTP gateway (ICP API). Random if not set.
--config-port	integer	Port for the PocketIC admin interface. Random if not set.
--bind	IP address	Network interface to bind the HTTP gateway on.
--pocketic-config-bind	IP address	Network interface to bind the PocketIC config API (also called the admin API) on
--domain	string	Domain for the gateway to respond to
--custom-domains-file	path	Path to a file for custom domain to canister ID mappings (domain:principal, one per line)
--state-dir	path	Directory to persist PocketIC state across restarts. Ephemeral if not set.
--artificial-delay-ms	integer	Artificial delay for update call execution (ms).
--subnet	enum	Subnet to add. Can be specified multiple times. See Subnet Configuration.
--bitcoind-addr	host:port	Bitcoin P2P node address. Can be specified multiple times. See Bitcoin/Dogecoin.
--dogecoind-addr	host:port	Dogecoin P2P node address. Can be specified multiple times. See Bitcoin/Dogecoin.
--ii	flag	Enable Internet Identity. See Internet Identity.
--nns	flag	Enable NNS and SNS. See NNS.
--interface-version	semver	Expected CLI interface version. Also read from ICP_CLI_NETWORK_LAUNCHER_INTERFACE_VERSION env var. Used by automated setups.
--status-dir	path	Directory to write the status file to. Used by automated setups.
--verbose	flag	Enable verbose logging from PocketIC.

Subnet Configuration

Subnets fall into two independent categories:

Always-on base topology — created unconditionally, not affected by --subnet:

• NNS — required for system operations.
• fiduciary — mirrors the mainnet topology.
• test-threshold-keys — provides test_key_1 and dfx_test_key for all threshold algorithms (ECDSA, Schnorr, and VetKd).

Workload subnets — selected with the --subnet flag. Available types: application, system, verified-application, bitcoin, sns.

Default behavior:

• With no --subnet flags: one application subnet is created (in addition to the base topology).
• With any --subnet flag: the default application subnet is not created; only the workload subnets you specify are added.

--subnet=nns and --subnet=fiduciary are still accepted for backward compatibility but have no effect, since those subnets are always created. --subnet=test-threshold-keys is not a valid value.

Examples:

# Default: NNS + fiduciary + TestThresholdKeys + application
icp-cli-network-launcher

# Two application subnets (NNS + fiduciary + TestThresholdKeys always included)
icp-cli-network-launcher --subnet=application --subnet=application

# System + application (NNS + fiduciary + TestThresholdKeys always included)
icp-cli-network-launcher --subnet=system --subnet=application

# Only system (no application subnet!) + NNS + fiduciary + TestThresholdKeys
icp-cli-network-launcher --subnet=system

Internet Identity

The --ii flag creates an II subnet and installs the Internet Identity canister.

The II subnet and canister are also implicitly enabled when any of the following are used:

• --nns

NNS

The --nns flag installs the NNS (Network Nervous System) and SNS (Service Nervous System). It has the following effects:

• Creates an SNS subnet
• Creates an II subnet (implies --ii)
• Enables NNS governance, NNS UI, SNS, and canister migration features

Bitcoin and Dogecoin Integration

The --bitcoind-addr and --dogecoind-addr flags connect the network to external Bitcoin or Dogecoin nodes for chain integration testing.

Implicit effects:

• A bitcoin subnet is automatically created (shared by both Bitcoin and Dogecoin)
• The respective chain feature (bitcoin or dogecoin) is enabled

Address format: host:port — this is the P2P address of the node, not the RPC address.

Examples:

# Connect to a local Bitcoin node
icp-cli-network-launcher --bitcoind-addr=127.0.0.1:18444

# Connect to both Bitcoin and Dogecoin nodes
icp-cli-network-launcher --bitcoind-addr=127.0.0.1:18444 --dogecoind-addr=127.0.0.1:22556

# Multiple Bitcoin nodes
icp-cli-network-launcher --bitcoind-addr=127.0.0.1:18444 --bitcoind-addr=192.168.1.5:18444

Interaction Summary

The following table summarizes the subnets created for common configurations. NNS, fiduciary, and TestThresholdKeys subnets are always present regardless of flags.

Configuration	Subnets created
(no flags)	NNS, fiduciary, TestThresholdKeys, application
--ii	NNS, fiduciary, TestThresholdKeys, application, II
--nns	NNS, fiduciary, TestThresholdKeys, application, II, SNS
--bitcoind-addr=...	NNS, fiduciary, TestThresholdKeys, application, bitcoin
--dogecoind-addr=...	NNS, fiduciary, TestThresholdKeys, application, bitcoin
--subnet=system	NNS, fiduciary, TestThresholdKeys, system
--subnet=system --bitcoind-addr=...	NNS, fiduciary, TestThresholdKeys, system, bitcoin
--nns --subnet=system	NNS, fiduciary, TestThresholdKeys, system, II, SNS

Key points:

• NNS, fiduciary, and TestThresholdKeys are always present — they cannot be omitted.
• Specifying any --subnet flag replaces the default application subnet. Add --subnet=application explicitly if you still need it.
• --bitcoind-addr and --dogecoind-addr always add a bitcoin subnet, regardless of --subnet flags.
• --nns always adds an SNS subnet and an II subnet, regardless of --subnet flags.
• Threshold signature keys (test_key_1, dfx_test_key) are always available via the TestThresholdKeys subnet — --ii is not required for threshold signing.

Status File

When --status-dir is provided, the launcher writes a JSON status file (status.json) to the specified directory once the network is ready. This is used by icp-cli and other automated setups to discover the running network.

Field	Type	Description
v	string	Status file format version. Currently "1".
gateway_port	number	Port where the HTTP gateway (ICP API) is listening.
root_key	string	Hex-encoded root key of the network.
config_port	number	Port of the PocketIC admin interface.
instance_id	number	PocketIC instance ID.
default_effective_canister_id	string	Default effective canister ID for provisional canister creation calls.

Shutdown

The launcher handles SIGINT (Ctrl+C) and SIGTERM for graceful shutdown. It stops the PocketIC server and waits for it to exit before terminating.

Experimental features

If the launcher is built with --feature cloud-engine, you can create subnets of type cloud-engine. The subnet admin is set to the anonymous principal. The :engine-beta Docker tag is an alternative to the standard image with this feature enabled.

Installing

icp-cli-network-launcher is typically installed automatically by icp-cli. It can be updated to the latest version with icp network update.

Binary downloads are also available on the releases page.

A Docker image is published under the name ghcr.io/dfinity/icp-cli-network-launcher. The container port 4943 should be published for gateway access, and if a status dir is needed, mount it at /app/status.

Development

Prerequisites

• Rust v1.90 or later. If you have Rustup installed it will automatically use the right version.
• Bash, jq, and curl for the package.sh script.

Building

./package.sh [directory]

This will build the code, download the appropriate version of pocket-ic, and place it in a destination folder. If you do not supply a folder it will use dist/icp-cli-network-launcher-<VERSION> and additionally create a tarball.

License

This project is licensed under the Apache-2.0 license.

Contribution

This project does not accept external contributions. Pull requests from individuals outside the organization will be automatically closed.