Network

Network = "ic" | "local" | "env" | { host: string; rootKey?: Uint8Array; name?: string; fetchRootKey?: boolean; }

Defined in: core/src/network.ts:64

Where the canisters are.

• "ic": mainnet, through https://icp-api.io, checked against the mainnet root key the agent ships with. Nothing is fetched.
• "local": a replica on http://127.0.0.1:4943. Its root key is fetched from the replica before the first call.
• "env": the network of the page this code runs in, as an asset canister or a dev server describes it. In a browser, a page on a local replica or on a mainnet boundary domain (and a Codespaces or Gitpod page, which forwards a local dev server) routes through its own origin. The root key comes from the ic_env cookie, but only where that cookie is trusted: when both the page and the replica are local, or the client was built with allowEnvConfig: true. A local replica with no key from the cookie has its root key fetched. A Codespaces or Gitpod page is routed but is not local, so there the key is neither taken from the cookie nor fetched, and the agent checks the forwarded replica’s certificates against mainnet’s key, so every certified call fails verification. Set allowEnvConfig: true to take the cookie’s key, or name the replica with an object that has a rootKey or fetchRootKey: true. On a server there is no page and no cookie: the host is ICP_HOST or IC_HOST when ICP_NETWORK or DFX_NETWORK is "local" (http://127.0.0.1:4943 if neither is set), and mainnet otherwise.
• An object: any other replica. rootKey is used as given and never fetched. Without one the root key is fetched only when host is local (localhost, *.localhost or any loopback address), unless fetchRootKey says otherwise. A replica behind a Codespaces, Gitpod or custom domain is not local: pass its rootKey, or write fetchRootKey: true to trust the key it reports. name is the network’s segment in query keys and defaults to host.

Union Members

"ic"

---

"local"

---

"env"

---

Type Literal

{ host: string; rootKey?: Uint8Array; name?: string; fetchRootKey?: boolean; }

host

readonly host: string

The replica’s URL. A host with no scheme is read against the page’s protocol, as HttpAgent reads it.

rootKey?

readonly optional rootKey?: Uint8Array

The root key certificates are verified against. Used as given and never fetched, even where fetchRootKey is true.

name?

readonly optional name?: string

This network’s segment in query keys. Defaults to host.

fetchRootKey?

readonly optional fetchRootKey?: boolean

Whether to fetch the root key from the replica when rootKey is absent. Defaults to whether host is local. Writing true for a host that is not local trusts whatever key that host reports, which is why it is never the default.