Skip to content

configuration.md

Latest commit

 

History

History
493 lines (387 loc) · 14.4 KB

configuration.md

File metadata and controls

493 lines (387 loc) · 14.4 KB
title description
Configuration Reference
Complete schema reference for icp.yaml project configuration including canisters, networks, and environments.

Complete reference for icp.yaml project configuration.

For conceptual explanation, see Project Model.

File Structure

# icp.yaml
canisters:
  - # canister definitions or references

networks:
  - # network definitions or references (optional)

environments:
  - # environment definitions (optional)

Canisters

Inline Definition

canisters:
  - name: my-canister
    build:
      steps:
        - type: script
          commands:
            - echo "Building..."
    sync:
      steps:
        - type: assets
          dir: www
    settings:
      compute_allocation: 5
    init_args: "()"

External Reference

canisters:
  - path/to/canister.yaml
  - canisters/*           # Glob pattern
  - services/**/*.yaml    # Recursive glob

Canister Properties

Property Type Required Description
name string Yes Unique canister identifier
build object Yes Build configuration
sync object No Post-deployment sync configuration
settings object No Canister settings
init_args string or object No Initialization arguments (see Init Args)
recipe object No Recipe reference (alternative to build)

Build Steps

Script Step

Execute shell commands:

build:
  steps:
    - type: script
      commands:
        - cargo build --target wasm32-unknown-unknown --release
        - cp target/wasm32-unknown-unknown/release/my_canister.wasm "$ICP_WASM_OUTPUT_PATH"

Environment variables:

  • ICP_WASM_OUTPUT_PATH — Target path for WASM output

See Environment Variables Reference for all available variables.

Pre-built Step

Use existing WASM from a local file or remote URL:

# Local file
build:
  steps:
    - type: pre-built
      path: dist/canister.wasm
      sha256: abc123...  # Optional integrity check

# Remote URL
build:
  steps:
    - type: pre-built
      url: https://github.com/example/releases/download/v1.0/canister.wasm
      sha256: abc123...  # Recommended for remote files
Property Type Required Description
path string One of path or url Local path to WASM file
url string One of path or url URL to download WASM file from
sha256 string No SHA256 hash for verification (recommended for URLs)

Sync Steps

Sync steps run after canister deployment to configure the running canister.

Assets Sync

Upload files to asset canister:

# Single directory
sync:
  steps:
    - type: assets
      dir: dist

# Multiple directories
sync:
  steps:
    - type: assets
      dirs:
        - dist
        - static
        - public/images
Property Type Required Description
dir string One of dir or dirs Single directory to upload
dirs array One of dir or dirs Multiple directories to upload

Script Sync

Run shell commands after deployment:

sync:
  steps:
    - type: script
      commands:
        - echo "Post-deployment setup"
        - ./scripts/configure-canister.sh

Script sync steps support the same command and commands fields as build script steps.

Recipes

Recipe Reference

canisters:
  - name: my-canister
    recipe:
      type: "@dfinity/rust@v3.0.0"
      sha256: abc123...  # Required for remote URLs
      configuration:
        package: my-crate
Property Type Required Description
type string Yes Recipe source (registry, URL, or local path)
sha256 string Conditional Required for remote URLs
configuration object No Parameters passed to recipe template

Recipe Type Formats

# Registry (recommended)
type: "@dfinity/rust@v3.0.0"

# Local file
type: ./recipes/my-recipe.hb.yaml

# Remote URL
type: https://example.com/recipe.hb.yaml

Networks

Networks define where canisters are deployed. There are two modes:

  • Managed (mode: managed): A local test network launched and controlled by icp-cli. Can run natively or in a Docker container.
  • Connected (mode: connected): A remote network accessed by URL.

Managed Network

A managed network runs the network launcher natively on your machine. To run it in a Docker container instead, see Docker Network.

networks:
  - name: local-dev
    mode: managed
    gateway:
      bind: 127.0.0.1
      port: 4943
Property Type Required Description
name string Yes Network identifier
mode string Yes managed
gateway.bind string No Bind address (default: 127.0.0.1)
gateway.port integer No Port number (default: 8000, use 0 for random)
gateway.domains array No Custom domain names the gateway responds to (e.g. my-app.localhost)
artificial-delay-ms integer No Artificial delay for update calls (ms)
ii boolean No Install Internet Identity canister (default: false). Also implicitly enabled by nns, bitcoind-addr, and dogecoind-addr.
nns boolean No Install NNS and SNS canisters (default: false). Implies ii and adds an SNS subnet.
subnets array No Configure subnet types. See Subnet Configuration.
bitcoind-addr array No Bitcoin P2P node addresses (e.g. 127.0.0.1:18444). Adds a bitcoin and II subnet.
dogecoind-addr array No Dogecoin P2P node addresses. Adds a bitcoin and II subnet.

For full details on how these settings interact, see the network launcher CLI reference.

Note: These settings apply to native managed networks only. For Docker image mode, pass equivalent flags via the args field instead.

Subnet Configuration

Configure the local network's subnet layout:

  • Default (no subnets field): one application subnet is created.
  • With subnets: only the listed subnets are created — the default application subnet is replaced, not extended. Add application explicitly if you still need it.
  • An NNS subnet is always created regardless of configuration (required for system operations).
networks:
  - name: local
    mode: managed
    subnets:
      - application
      - application
      - application

Available subnet types: application, system, verified-application, bitcoin, fiduciary, nns, sns

Bitcoin and Dogecoin Integration

Connect the local network to a Bitcoin or Dogecoin node for testing chain integration:

networks:
  - name: local
    mode: managed
    bitcoind-addr:
      - "127.0.0.1:18444"

The bitcoind-addr field specifies the P2P address (not RPC) of the Bitcoin node. Multiple addresses can be specified. Dogecoin integration works the same way via dogecoind-addr. Both can be configured simultaneously.

Implicit effects: When bitcoind-addr or dogecoind-addr is configured, the network launcher automatically adds a bitcoin subnet and an II subnet (provides threshold signing keys required for chain operations). If you also explicitly specify subnets, you must include application to keep the default application subnet:

networks:
  - name: local
    mode: managed
    bitcoind-addr:
      - "127.0.0.1:18444"
    subnets:
      - application
      - system

Connected Network

networks:
  - name: testnet
    mode: connected
    url: https://testnet.ic0.app
    root-key: <hex-encoded-key>  # For non-mainnet
Property Type Required Description
name string Yes Network identifier
mode string Yes connected
url string Yes Network endpoint URL
root-key string No Hex-encoded root key (non-mainnet only)

Docker Network

A managed network can also run inside a Docker container. Adding the image field switches from native to Docker mode:

networks:
  - name: docker-local
    mode: managed
    image: ghcr.io/dfinity/icp-cli-network-launcher
    port-mapping:
      - "0:4943"

To configure image-specific behavior (e.g., enabling Internet Identity, NNS, or Bitcoin integration), use the args field to pass command-line arguments to the container entrypoint:

networks:
  - name: docker-local
    mode: managed
    image: ghcr.io/dfinity/icp-cli-network-launcher
    port-mapping:
      - "8000:4943"
    args:
      - "--ii"

The available arguments depend on the Docker image — see the image's documentation for details.

Docker networking note: When referencing services running on the host machine from inside a container (e.g., a local Bitcoin node), use host.docker.internal instead of 127.0.0.1 or localhost. Inside a container, 127.0.0.1 refers to the container's own loopback, not the host. For example: --bitcoind-addr=host.docker.internal:18444. Docker Desktop (macOS/Windows) resolves host.docker.internal automatically. On Linux Docker Engine, you may need to pass --add-host=host.docker.internal:host-gateway or equivalent to ensure it resolves.

See Containerized Networks for full configuration options.

Environments

environments:
  - name: staging
    network: ic
    canisters:
      - frontend
      - backend
    settings:
      frontend:
        memory_allocation: 2gib
      backend:
        compute_allocation: 10
        environment_variables:
          LOG_LEVEL: "info"
    init_args:
      backend: "(record { mode = \"staging\" })"
Property Type Required Description
name string Yes Environment identifier
network string Yes Network to deploy to
canisters array No Canisters to include (default: all)
settings object No Per-canister setting overrides
init_args object No Per-canister init arg overrides (see Init Args)

Canister Settings

See Canister Settings Reference for all options.

settings:
  compute_allocation: 5
  memory_allocation: 4gib
  freezing_threshold: 30d
  reserved_cycles_limit: 1t
  wasm_memory_limit: 1gib
  wasm_memory_threshold: 512mib
  log_visibility: controllers
  environment_variables:
    KEY: "value"

Memory values accept suffixes: kb (1000), kib (1024), mb, mib, gb, gib. Cycles values accept suffixes: k (thousand), m (million), b (billion), t (trillion). Duration values accept suffixes: s (seconds), m (minutes), h (hours), d (days), w (weeks). Decimals and underscores are supported where applicable (e.g. 2.5gib, 1_000_000).

Init Args

A plain string is shorthand for inline Candid content:

init_args: "(record { owner = principal \"aaaaa-aa\" })"

File reference:

init_args:
  path: ./args.bin
  format: bin

Inline value (explicit):

init_args:
  value: "(record { owner = principal \"aaaaa-aa\" })"
  format: candid
Property Type Required Description
path string Yes* Relative path to file containing init args
value string Yes* Inline init args value
format string No hex, candid, or bin (default: candid)

*Exactly one of path or value must be specified.

Supported formats:

  • hex — Hex-encoded bytes (inline or file)
  • candid — Candid text format (inline or file)
  • bin — Raw binary bytes; only valid with path (e.g. output of didc encode)

Implicit Defaults

Networks

Name Mode Description
local managed localhost:8000, can be overridden
ic connected ICP mainnet, cannot be overridden

Environments

Name Network Canisters
local local All
ic ic All

Complete Example

canisters:
  - name: frontend
    recipe:
      type: "@dfinity/asset-canister@v2.1.0"
      configuration:
        dir: dist
    settings:
      memory_allocation: 1gib

  - name: backend
    build:
      steps:
        - type: script
          commands:
            - cargo build --target wasm32-unknown-unknown --release
            - cp target/wasm32-unknown-unknown/release/backend.wasm "$ICP_WASM_OUTPUT_PATH"
    settings:
      compute_allocation: 5
    init_args:
      value: "(record { admin = principal \"aaaaa-aa\" })"

networks:
  - name: local
    mode: managed
    gateway:
      port: 9999

environments:
  - name: staging
    network: ic
    canisters: [frontend, backend]
    settings:
      backend:
        compute_allocation: 10
        environment_variables:
          ENV: "staging"

  - name: production
    network: ic
    canisters: [frontend, backend]
    settings:
      frontend:
        memory_allocation: 4gib
      backend:
        compute_allocation: 30
        freezing_threshold: 90d
        environment_variables:
          ENV: "production"
    init_args:
      backend: "(record { admin = principal \"xxxx-xxxx\" })"

Schema

JSON schemas for editor integration are available in docs/schemas/:

Configure your editor to use them for autocomplete and validation:

# yaml-language-server: $schema=https://raw.githubusercontent.com/dfinity/icp-cli/main/docs/schemas/icp-yaml-schema.json
canisters:
  - name: my-canister
    # ...