Network
Network =
"ic"|"local"|"env"| {host:string;rootKey?:Uint8Array;name?:string;fetchRootKey?:boolean; }
Defined in: core/src/network.ts:89
Where the canisters are.
"ic": mainnet, throughhttps://icp-api.io, checked against the mainnet root key the agent ships with. Nothing is fetched."local": icp-cli’s local network,http://127.0.0.1:8000. Its root key is fetched from the replica before the first call. A dfx replica (port 4943) is an object:{ host: "http://127.0.0.1:4943" }."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 routes through its own origin, and so does a page that forwards a dev server: Codespaces, Gitpod, a LAN address (RFC 1918, link-local, IPv6 ULA), a Tailscale address or name (100.64/10,*.ts.net), a LAN name with no dot such asdevbox, a*.local,*.testor*.internalname such ashost.docker.internal, or a tunnel (ngrok,trycloudflare.com,loca.lt, VS Code’sdevtunnels.ms)."env"is for localhost pages: those others never reach mainnet, but none is local. The root key comes from theic_envcookie, but only where that cookie is trusted: when both the page and the replica are local, or the client was built withallowEnvConfig: true. On a canister’s own<id>.icp0.iopage the cookie’s canister ids are believed by default, never its root key. A local replica with no key from the cookie has its root key fetched. A forwarding 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. Name the replica with an object that has arootKey(orfetchRootKey: true) and the canisters with{ id }: on a dev container or a localtunnel,allowEnvConfig: trueis refused, because every workspace or tunnel is a sibling of every stranger’s. On a mainnet host the cookie’s root key is never taken, even withallowEnvConfig: true: the agent keeps mainnet’s own. On a server there is no page and no cookie: the host isICP_HOSTorIC_HOSTwhenICP_NETWORKis"local"(http://127.0.0.1:8000if neither is set), and mainnet otherwise. With noICP_NETWORK, dfx’sDFX_NETWORK=localcounts too, and its default is dfx’shttp://127.0.0.1:4943.- An object: any other replica.
rootKeyis used as given and never fetched. Without one the root key is fetched only whenhostis local (localhost,*.localhostor any loopback address), unlessfetchRootKeysays otherwise. A replica behind a Codespaces, Gitpod or custom domain is not local: pass itsrootKey, or writefetchRootKey: trueto trust the key it reports.nameis the network’s segment in query keys and defaults tohost.
Union Members
Section titled “Union Members”"ic"
"local"
"env"
Type Literal
Section titled “Type Literal”{ host: string; rootKey?: Uint8Array; name?: string; fetchRootKey?: boolean; }
readonlyhost:string
The replica’s URL, over http: or https:. A host with no scheme is
read against the page’s protocol, as HttpAgent reads it, and is
refused where there is no page. createClient throws a TypeError
for any other host, such as localhost:4943, which reads as the
scheme localhost:.
rootKey?
Section titled “rootKey?”
readonlyoptionalrootKey?:Uint8Array
The root key certificates are verified against. Used as given and
never fetched, even where fetchRootKey is true.
readonlyoptionalname?:string
This network’s segment in query keys. Defaults to host.
fetchRootKey?
Section titled “fetchRootKey?”
readonlyoptionalfetchRootKey?: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.