deploy-to-cloud-engine

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deploy to Cloud Engine

部署到云引擎

What This Is

这是什么

A cloud engine is a user-owned slice of Internet Computer capacity, administered from a web console (by default
https://opencloud.org
). Each engine runs on a single subnet. This skill takes a project that already builds and gets it deployed onto that engine, from a coding agent or an AI chat app.
This skill only covers the cloud-engine-specific steps: choosing how to deploy, signing in as an identity the engine accepts, and putting the canisters on the engine. For everything else about the CLI (
icp.yaml
, recipes, environments, bindings, identities), load the
icp-cli
skill.
**云引擎(cloud engine)是用户自有的一段 Internet Computer 容量,通过 Web 控制台进行管理(默认为
https://opencloud.org
)。每个引擎运行在单个
子网(subnet)**上。本 skill 负责把一个已经可以构建的项目部署到该引擎上,无论你是从编码 Agent 还是 AI 聊天应用发起的。
本 skill 仅覆盖与云引擎相关的步骤:选择部署方式、以引擎可接受的身份登录,以及把 canister 放到引擎上。关于 CLI 的其他所有内容(
icp.yaml
、recipes、environments、bindings、identities),请加载
icp-cli
skill。

Choose the Deploy Route First

先选择部署路径

There are two ways onto an engine. Pick one before you write any code: the route decides how the deploy signs in and what you can ship.
  • ICP MCP connector. DFINITY's official MCP server for the Internet Computer. It is available natively in ChatGPT (the plugin Internet Computer (ICP) by DFINITY Stiftung) and in Claude, and any MCP-capable app can add it as a custom connector at
    https://mcp.internetcomputer.org/mcp
    (setup steps: https://mcp.internetcomputer.org/). It signs as the user with the Internet Identity session they authorized in the chat app, so nothing needs a local CLI, a browser on your machine, or a loopback. You deploy a wasm through the engine's engine-operator canister. See "ICP MCP Route".
  • icp CLI.
    icp identity link web
    , then
    icp deploy --subnet
    . The full toolchain (recipes, asset canisters,
    icp.yaml
    ), but the sign-in completes only when
    icp
    runs on the same machine as the user's browser. See Steps 1 to 4.
Decide like this:
  1. You run in a sandbox and the ICP MCP tools are available to you (
    open_app
    ,
    get_app_principal
    ,
    canister_update_call
    , …) → use the ICP MCP route. A sandbox is a web or mobile chat (ChatGPT, Claude on the web or a phone) or a cloud coding session. Do not ask the user to move to a local session, and do not attempt
    icp identity link web
    or the delegation handoff there.
  2. Otherwise → the CLI route: link the CLI (Step 1).
    • Local session (a coding agent on the user's own computer: Claude Code, Codex CLI, Cursor, or the local environment of the Claude desktop app): link the CLI and deploy with it, even when the ICP MCP tools are also available. The normal link flow works there, and the CLI can ship what the connector cannot, such as the files of an asset canister (see "What the connector cannot do").
    • Sandbox without the ICP MCP tools: the CLI sign-in cannot finish there (see Step 1.0). Tell the user before you build anything, and ask them to start a local session instead. If their chat app can add MCP connectors, adding the ICP MCP connector is the other way. A cloud session cannot move to their computer later, so ask before you build, not after, and wait for the answer. Continue in the sandbox with the CLI only when the user has neither option. Then do the delegation handoff in Step 1.0 first, and build only after the sandbox CLI signs as the user: do not leave the sign-in for deploy time.
Before running any
icp
command you are unsure of, run
icp <subcommand> --help
(e.g.
icp identity link --help
,
icp deploy --help
) to confirm the command and flags exist. Do not infer flags. Authoritative reference: https://cli.internetcomputer.org/llms.txt
进入引擎有两条路。在写任何代码之前先选定一条:路径决定了部署如何登录以及你能发布什么。
  • ICP MCP 连接器。 DFINITY 为 Internet Computer 提供的官方 MCP server。它在 ChatGPT 中原生可用(DFINITY Stiftung 提供的插件 Internet Computer (ICP)),在 Claude 中也可用;任何支持 MCP 的应用都可以在
    https://mcp.internetcomputer.org/mcp
    添加自定义连接器(设置步骤见 https://mcp.internetcomputer.org/)。它以用户在聊天应用中授权的 Internet Identity 会话身份签名,因此无需本地 CLI、无需你机器上的浏览器、也无需 loopback。你通过引擎的 engine-operator canister 部署 wasm。参见 "ICP MCP 路径"。
  • icp CLI。
    icp identity link web
    ,然后
    icp deploy --subnet
    。提供完整工具链(recipes、asset canisters、
    icp.yaml
    ),但只有当
    icp
    与用户浏览器在同一台机器上运行时登录才能完成。参见 步骤 1 到 4。
判断方式如下:
  1. 你运行在沙箱中且可使用 ICP MCP 工具(
    open_app
    、
    get_app_principal
    、
    canister_update_call
    等)→ 使用 ICP MCP 路径。 沙箱指 Web 或移动端聊天(ChatGPT、网页版或手机版 Claude)或云端编码会话。不要要求用户切换到本地会话,也不要在那里尝试
    icp identity link web
    或委派交接。
  2. 其他情况 → 使用 CLI 路径:关联 CLI(步骤 1)。
    • 本地会话(用户自己电脑上的编码 Agent:Claude Code、Codex CLI、Cursor,或 Claude 桌面应用的本地环境):关联 CLI 并用它部署,即使 ICP MCP 工具也可用。在那里正常的关联流程可以工作,而且 CLI 能发布连接器无法发布的内容,例如 asset canister 的文件(见"连接器无法做什么")。
    • 没有 ICP MCP 工具的沙箱:CLI 登录在那里无法完成(见步骤 1.0)。在构建任何东西之前先告知用户,并请他们改用本地会话。如果他们的聊天应用可以添加 MCP 连接器,添加 ICP MCP 连接器是另一种方式。云端会话之后无法转移到他们的电脑上,所以要在构建之前询问,而不是之后;并等待答复。只有当用户两者都没有时,才继续在沙箱中仅使用 CLI。此时要先执行步骤 1.0 中的委派交接,并且只在沙箱 CLI 以用户身份完成登录后再构建:不要把登录拖到部署时再做。
在运行任何你不确定的
icp
命令之前,先执行
icp <subcommand> --help
(例如
icp identity link --help
、
icp deploy --help
)以确认命令和参数存在。不要推测参数。权威参考:https://cli.internetcomputer.org/llms.txt

What You Need

你需要什么

Two values, and a third for some apps. Look for them first in
icp.yaml
or earlier in the conversation. One has a default; the others you must ask for:
  1. Console origin — the URL the user signs in to their cloud engine console with. Defaults to
    https://opencloud.org
    (the main OpenCloud console). Its host is the
    --app
    value in Step 1, so the linked CLI identity derives the same principal that administers the engine. Use the default, but say so and give the user a chance to override before linking:
    • Say: "I'll link the CLI against
      https://opencloud.org
      , the default console. If you sign in to your engine console at a different URL, tell me now."
    • Only use a different origin when the user names one — never substitute another URL on your own; the
      --app
      domain determines the derived principal (see Pitfall 2).
    • On the ICP MCP route there is no
      --app
      ; the console origin is where you look the engine up and where the owner confirms access (M1, M3).
  2. Subnet id (CLI route): the subnet the engine deploys to, required by
    icp deploy --subnet
    . There is no default; never guess it. The user finds it on the engine's Settings page in the console (under the engine's identifiers), or copies it from the console's command palette. If absent, ask and do not proceed without it:
    • Ask: "What is your engine's subnet id? It is on your engine's Settings page in the console."
    • On the ICP MCP route you need the engine id instead (M1). The operator creates canisters on its own engine, so there is no subnet to pass.
  3. Proxy canister id: only if the app calls threshold ECDSA/Schnorr, vetKD, the exchange-rate canister, the Bitcoin API, or the EVM/SOL RPC canisters (look for a
    PROXY_CANISTER_ID
    variable, or a call to a
    proxy
    method). There is no default, you cannot create the console proxy yourself, and a self-deployed one is no substitute (Step 5). If absent, ask before deploying:
    • Ask: "This app needs your engine's proxy canister. If the engine has one, send me its id (engine → Integrations → Proxy canisters). If not, the engine owner can deploy one there with Deploy a proxy: it is paid from the engine's balance, no card. Then send me its id."
Record them so you do not re-ask within the session.
需要两个值,某些应用还需要第三个。先在
icp.yaml
或之前的对话中查找。其中一个有默认值,其余必须询问用户:
  1. 控制台源(console origin)—— 用户登录其云引擎控制台所用的 URL。默认为
    https://opencloud.org
    (OpenCloud 主控制台)。它的主机名就是步骤 1 中的
    --app
    值,因此关联的 CLI 身份会派生出与管理该引擎相同的 principal。使用默认值,但应明确告知并给用户机会在关联前覆盖:
    • 说明:"我会针对
      https://opencloud.org
      这个默认控制台关联 CLI。如果你登录引擎控制台用的是另一个 URL,请现在告诉我。"
    • 只有在用户明确指明时才使用其他源——绝不要自行替换成另一个 URL;
      --app
      域名决定了派生的 principal(见陷阱 2)。
    • 在 ICP MCP 路径上没有
      --app
      ;控制台源用于查找引擎以及让所有者确认访问权限(M1、M3)。
  2. 子网 id(CLI 路径):引擎部署到的子网,
    icp deploy --subnet
    必需。没有默认值;绝不要猜测。用户可以在控制台的引擎 Settings 页面找到它(在引擎标识符下方),或从控制台的命令面板中复制。如果缺失,必须询问,且未获得答案前不要继续:
    • 询问:"你的引擎的 subnet id 是多少?在控制台的引擎 Settings 页面上。"
    • 在 ICP MCP 路径上你需要的是引擎 id(M1)。operator 会在它自己的引擎上创建 canister,因此没有需要传入的子网。
  3. Proxy canister id:仅当应用调用 threshold ECDSA/Schnorr、vetKD、汇率 canister、Bitcoin API 或 EVM/SOL RPC canister 时需要(查找
    PROXY_CANISTER_ID
    变量,或对
    proxy
    方法的调用)。没有默认值,你无法自行创建控制台 proxy,自行部署的 proxy 也不能替代它(步骤 5)。如果缺失,部署前必须询问:
    • 询问:"这个应用需要你引擎的 proxy canister。如果引擎已有一个,请把它的 id 发给我(engine → Integrations → Proxy canisters)。如果没有,引擎所有者可以在那里通过 Deploy a proxy 部署一个:它从引擎余额付费,无需信用卡。然后把 id 发给我。"
记录这些值,以免在本次会话中重复询问。

Prerequisites

前置条件

  • CLI route:
    icp
    on
    $PATH
    — see the
    icp-cli
    skill to install. Verify with
    icp --version
    (this skill's commands are verified against 0.3.0 and 1.0.2). If the installed version differs, confirm the flag set with
    icp <cmd> --help
    before running — flags have changed across major versions.
  • A project that already builds. If it does not build or package yet, set that up first (see the
    icp-cli
    skill), then return here.
  • No project yet, and no description of one? Ask the user what to build before you write any code or create any files: "What app do you want to build?" Do not pick a sample app (a guestbook, a counter, a to-do list) on your own. A prompt that only says "build and deploy an app" is a request to ask, not a request to choose.
  • CLI route, macOS:
    icp
    stores its data under
    ~/Library/Application Support/org.dfinity.icp-cli/
    . If the shell cannot write there (
    Operation not permitted
    from macOS TCC, e.g. when commands run through a bridge), redirect the data to an unprotected path for the session —
    HOME=/tmp/icp-home icp …
    — and keep that same
    HOME
    on every subsequent
    icp
    command, or the later commands will not see the linked identity.
  • ICP MCP route: the connector's tools in your tool list, connected with Actions & questions access (M0).
  • CLI 路径:
    $PATH
    中有
    icp
    ——参见
    icp-cli
    skill 进行安装。用
    icp --version
    验证(本 skill 的命令已在 0.3.0 和 1.0.2 上验证)。如果安装的版本不同,先用
    icp <cmd> --help
    确认参数集合再运行——大版本之间参数已有变化。
  • 一个已经可以构建的项目。如果还无法构建或打包,先按
    icp-cli
    skill 配置好,然后回到这里。
  • 还没有项目,也没有项目描述? 在写任何代码或创建任何文件之前,先询问用户要构建什么:"你想构建什么应用?" 不要自行挑选示例应用(留言簿、计数器、待办清单)。只说"构建并部署一个应用"的提示意味着需要询问,而不是让你替用户选择。
  • CLI 路径,macOS:
    icp
    把数据存放在
    ~/Library/Application Support/org.dfinity.icp-cli/
    下。如果 shell 无法写入那里(来自 macOS TCC 的
    Operation not permitted
    ,例如命令通过 bridge 运行时),把数据重定向到本次会话中不受保护的路径——
    HOME=/tmp/icp-home icp …
    ——并在之后每一条
    icp
    命令中保持相同的
    HOME
    ,否则后续命令将看不到已关联的身份。
  • ICP MCP 路径:你的工具列表中有该连接器的工具,并已连接 Actions & questions 访问级别(M0)。

ICP MCP Route

ICP MCP 路径

For a sandboxed agent that has the ICP MCP tools (see "Choose the Deploy Route First"). No
icp
CLI, no loopback, no delegation handoff. Steps 1 and 3 are the CLI route and do not apply. Step 2 (naming the app) and Step 5 (the proxy canister for chain-key services) still do: M6 shows how to set their variables without
icp.yaml
.
The engine-operator canister's own API guide is the authoritative, current walkthrough of the calls below: read it in M2 before you call anything.
适用于拥有 ICP MCP 工具的沙箱 Agent(见"先选择部署路径")。无需
icp
CLI、无需 loopback、无需委派交接。步骤 1 和 3 属于 CLI 路径,不适用。步骤 2(为应用命名)和步骤 5(面向链上密钥服务的 proxy canister)仍然适用:M6 说明了如何在没有
icp.yaml
的情况下设置相应变量。
engine-operator canister 自身的 API 指南是下列调用的权威且最新的操作手册:在调用任何东西之前先阅读 M2 中的该指南。

M0. The connector and its access level

M0. 连接器及其访问级别

If the tools are missing and the user's app can add MCP connectors, ask them to add it: in ChatGPT the plugin Internet Computer (ICP) by DFINITY Stiftung, in Claude its connector, and in any other MCP-capable app a custom connector at
https://mcp.internetcomputer.org/mcp
. The steps are at https://mcp.internetcomputer.org/.
On connecting, the user signs in with Internet Identity, picks how long the session lasts, and picks an access level. A deploy needs Actions & questions. With Questions only, reads work, but the network rejects every state-changing call, so
create_canister
and
install_code
fail. If an update call is rejected that way, ask the user to reconnect with Actions & questions. Sessions expire by design: reconnecting later is normal.
如果工具缺失且用户的应用可以添加 MCP 连接器,请让他们添加:在 ChatGPT 中是 DFINITY Stiftung 提供的插件 Internet Computer (ICP),在 Claude 中是其连接器,在其他支持 MCP 的应用中是在
https://mcp.internetcomputer.org/mcp
添加自定义连接器。步骤见 https://mcp.internetcomputer.org/。
连接时,用户使用 Internet Identity 登录,选择会话时长和访问级别。部署需要 Actions & questions。若只有 Questions only,读取操作可用,但网络会拒绝所有改变状态的调用,因此
create_canister
和
install_code
会失败。如果更新调用因此被拒绝,请让用户以 Actions & questions 重新连接。会话过期是设计使然,之后重新连接是正常的。

M1. Find the engine

M1. 查找引擎

You need three values: the engine's id, its engine-operator canister id (
engine_operator_id
), and its platform domain (
platform_domain
, like
<engine-name>--<slug>.opencloud.org
).
  • Ask the user for the engine id. It is in the console URL (
    /console/engines/<engine-id>/…
    ) and on the engine's Settings page.
  • open_app
    on the console origin (
    https://opencloud.org
    ) lists the engine registry canister. Read its public
    getEngineViews
    query with
    (vec { "<engine-id>" })
    ; the record carries
    engine_operator_id
    and
    platform_domain
    . Signed as the user, its
    listVisibleEngines
    query returns the engines they own, with the same fields.
A new or renamed engine's platform domain takes about ten minutes to register. Do not open or fetch it before then: a lookup that finds no record can be cached as missing for up to 30 minutes, and the domain keeps failing for you after it is live. Reach the engine through its operator's
https://<engine_operator_id>.icp.net
host instead, which works as soon as
engine_operator_id
is set.
GET https://icp.net/custom-domains/v1/<platform_domain>
answers
registration_status
registered
once the platform domain serves: give the user that address from then on.
你需要三个值:引擎的 id、其 engine-operator canister id(
engine_operator_id
)以及其 平台域名(
platform_domain
,形如
<engine-name>--<slug>.opencloud.org
)。
  • 向用户索取引擎 id。它在控制台 URL(
    /console/engines/<engine-id>/…
    )中以及引擎的 Settings 页面上。
  • 在控制台源(
    https://opencloud.org
    )上执行
    open_app
    会列出引擎注册表 canister。用
    (vec { "<engine-id>" })
    读取其公开的
    getEngineViews
    查询;该记录包含
    engine_operator_id
    和
    platform_domain
    。以用户身份签名调用其
    listVisibleEngines
    查询会返回用户拥有的引擎,字段相同。
新建或重命名的引擎,其平台域名注册大约需要十分钟。在此之前不要打开或访问它:查找不到记录的查询结果可能被缓存为"缺失"长达 30 分钟,域名上线后仍会持续对你失败。请改用其 operator 的
https://<engine_operator_id>.icp.net
主机访问引擎,该地址在
engine_operator_id
设置好之后立即可用。
GET https://icp.net/custom-domains/v1/<platform_domain>
在平台域名开始提供服务后返回
registration_status
registered
:此后请把该地址提供给用户。

M2. Open the engine and read the operator's guide

M2. 打开引擎并阅读 operator 指南

  1. open_app
    on
    https://<engine_operator_id>.icp.net
    . The engine-operator publishes the engine's
    /.well-known/ic-architecture
    manifest, so it comes back as
    [declared]
    ; that is what lets the connector call it. The connector refuses calls to any canister an app does not declare. Check that the
    derivation_origin
    it returns is
    https://<platform_domain>
    . If it is the icp.net origin, the operator does not hold the engine's domain yet: wait a minute and
    open_app
    again before M3, or the principal you get there changes later.
  2. get_canister_api_doc
    on the operator, and read its section "Creating a canister and installing a wasm".
  3. get_canister_candid
    on the operator, and check that its service has a
    proxy
    method. If it has none, the engine still runs an engine-operator from before the ICP MCP route existed: tell the user, and use the CLI route.
  1. 在
    https://<engine_operator_id>.icp.net
    上执行
    open_app
    。engine-operator 会发布引擎的
    /.well-known/ic-architecture
    清单,因此它返回为
    [declared]
    ;正是这一点让连接器可以调用它。连接器会拒绝对应用未声明的任意 canister 的调用。检查它返回的
    derivation_origin
    是否为
    https://<platform_domain>
    。如果是 icp.net 源,说明 operator 尚未持有该引擎的域名:等待一分钟后再次
    open_app
    再进行 M3,否则你在那里获得的 principal 之后会发生变化。
  2. 对 operator 执行
    get_canister_api_doc
    ,阅读其中 "Creating a canister and installing a wasm" 一节。
  3. 对 operator 执行
    get_canister_candid
    ,检查其 service 中是否有
    proxy
    方法。如果没有,说明该引擎运行的仍是 ICP MCP 路径出现之前的 engine-operator:告知用户并改用 CLI 路径。

M3. Get the connector's principal added to the engine

M3. 把连接器的 principal 加入引擎

Internet Identity derives a principal per origin. At the engine, the connector signs as the principal derived for the engine's platform domain (the origin in its
/.well-known/ii-derivation-origin
). That is not the principal the user signs in to the console with, nor a CLI identity linked against the console origin. So the engine does not know it yet, even when the user owns the engine.
  1. get_app_principal
    with the
    derivation_origin
    that
    open_app
    returned in M2 gives you that principal,
    P
    . Its reply also says whether the session is query-only: if it is, stop and have the user reconnect with Actions & questions (M0). If the user has several accounts at the engine, pick one with
    account
    and keep passing the same one, since each account is a different principal.
  2. Check whether it is a member: the operator's public
    getRole
    query with
    (record { principal_id = opt principal "<P>" })
    . Any role is enough, because every role has the
    CreateCanister
    permission that
    proxy
    needs.
  3. If the role is null, you cannot add
    P
    yourself. Give the user (the engine owner, or an engine admin) this link. It opens the engine's invite dialog with the grant filled in, so they only sign in and confirm:
    https://opencloud.org/console/engines/<engine-id>/team?modal=invite-member&principal=<P>&role=developer
    Use their console origin instead of
    https://opencloud.org
    if it differs.
    developer
    is enough to deploy: do not ask for
    admin
    . Wait for them to confirm, then repeat step 2.
Renaming the engine changes its platform domain, and with it
P
: the new principal needs the invite again.
Internet Identity 按源派生 principal。在引擎处,连接器以针对引擎 平台域名(即其
/.well-known/ii-derivation-origin
中的源)派生的 principal 签名。这不是用户登录控制台时使用的 principal,也不是针对控制台源关联的 CLI 身份。因此即使用户拥有该引擎,引擎也还不认识它。
  1. 用 M2 中
    open_app
    返回的
    derivation_origin
    执行
    get_app_principal
    ,即可得到该 principal
    P
    。其回复还会说明会话是否仅为查询模式:如果是,请停止并让用户以 Actions & questions 重新连接(M0)。如果用户在引擎处有多个账户,请用
    account
    选定其中一个并始终传入同一个,因为每个账户都是不同的 principal。
  2. 检查它是否为成员:调用 operator 的公开
    getRole
    查询,参数为
    (record { principal_id = opt principal "<P>" })
    。任何角色都足够,因为每个角色都具备
    proxy
    所需的
    CreateCanister
    权限。
  3. 如果角色为 null,你无法自行添加
    P
    。把下面的链接给用户(引擎所有者或引擎管理员)。它会打开该引擎的邀请对话框并预填授权内容,用户只需登录并确认:
    https://opencloud.org/console/engines/<engine-id>/team?modal=invite-member&principal=<P>&role=developer
    如果你的控制台源不是
    https://opencloud.org
    ,请改用你自己的控制台源。
    developer
    已足够完成部署:不要要求
    admin
    。等待用户确认,然后重复步骤 2。
重命名引擎会改变其平台域名,
P
也会随之改变:新的 principal 需要再次邀请。

M4. Build a wasm the connector can ship

M4. 构建连接器可以发布的 wasm

The connector installs a wasm module and nothing else.
  • Build it where you can. In a code sandbox with the toolchain,
    icp build
    needs no sign-in (see
    icp-cli
    ), and its recipe bakes in Step 2's version metadata as usual. Or use a prebuilt
    .wasm
    /
    .wasm.gz
    the user attaches. Canister code follows the engine's call rules: load
    cloud-engine-canisters
    .
  • Keep it small. The module travels inside the tool call as a Candid blob, so build for release and gzip it: the operator accepts a gzipped module. Above about 2 MB, it has to go up in chunks (M5, step 4).
连接器只能安装 wasm module,不能安装其他东西。
  • 在你能构建的地方构建。 在带有工具链的代码沙箱中,
    icp build
    无需登录(见
    icp-cli
    ),其 recipe 会照常嵌入步骤 2 的版本元数据。也可以使用用户附带的预构建
    .wasm
    /
    .wasm.gz
    。canister 代码需遵循引擎的调用规则:加载
    cloud-engine-canisters
    。
  • 保持体积小。 module 会作为 Candid blob 随工具调用传输,因此请以 release 模式构建并 gzip:operator 接受 gzip 后的 module。超过约 2 MB 时,必须分块上传(M5,步骤 4)。

What the connector cannot do

连接器无法做什么

The connector calls only canisters that an app declares, and the engine's manifest declares only its operator. So your new canister is reachable only through the operator's relayed management calls (M5): the connector cannot call the new canister's own methods. That rules out anything that needs calls after the install, such as uploading the files of an asset canister (
@dfinity/static-site
,
@dfinity/asset-canister
). Pass configuration in the init argument (
arg
), or as environment variables (M6). If the app needs an asset upload, it needs the CLI route: tell the user.
连接器只能调用应用声明过的 canister,而引擎清单只声明了它的 operator。因此你新建的 canister 只能通过 operator 转发的管理调用触达(M5):连接器无法调用新 canister 自身的方法。这排除了任何需要在安装后进行调用的需求,例如上传 asset canister 的文件(
@dfinity/static-site
、
@dfinity/asset-canister
)。请通过 init 参数(
arg
)或环境变量(M6)传入配置。如果应用需要上传静态资源,它需要走 CLI 路径:告知用户。

M5. Create the canister and install the wasm through the operator's
proxy

M5. 通过 operator 的
proxy
创建 canister 并安装 wasm

The connector may not call the IC management canister (
aaaaa-aa
) directly. The engine-operator's
proxy
method
calls it for you, as the caller you sign as. Do not confuse it with the proxy canister of Step 5: that one relays chain-key calls for your app's code, and has nothing to do with deploying.
Each step is one
canister_update_call
with
canister_id
the engine-operator,
method = "proxy"
,
app_url
the app URL and
derivation_origin
the derivation origin that
open_app
returned in M2 (plus the same
account
as in M3, if you chose one). Always pass
derivation_origin
: without it the call runs anonymously, and
proxy
answers
UnauthorizedUser
. The
args
are:
candid
(record {
  canister_id = principal "aaaaa-aa";
  method = "<management method name>";
  args = blob "<the method's argument, Candid-encoded>";
  cycles = 0;
})
args
holds the binary Candid encoding (bytes starting with
DIDL
) of the management method's argument, written as a
blob "…"
literal with
\xx
escapes. It is not textual Candid: encode it with a Candid library in your code sandbox. A success is
variant { Ok = record { result = blob "…" } }
, where
result
is the method's reply in binary Candid. The argument and reply types are in https://docs.internetcomputer.org/references/ic.did.
  1. Create.
    method = "create_canister"
    , and
    args
    encodes:
    candid
    (record { settings = opt record { controllers = opt vec { principal "<engine-operator-id>" } } })
    List the engine-operator as a controller. You (
    P
    ) are added as a controller automatically, but without the operator
    proxy
    can never reach the canister again: no install, no settings, and no
    deleteCanisters
    for the owner either. If the code reads an environment variable when it initializes (such as
    PROXY_CANISTER_ID
    ), add
    environment_variables
    to these
    settings
    now: it must be in place before step 2 (see M6).
    result
    decodes to
    (record { canister_id : principal })
    .
  2. Install.
    method = "install_code"
    , and
    args
    encodes:
    candid
    (record {
      mode = variant { install };
      canister_id = principal "<canister id from step 1>";
      wasm_module = blob "<wasm bytes, gzipped or not>";
      arg = blob "DIDL\00\00";
      sender_canister_version = null;
    })
    arg
    is the binary-Candid init argument;
    DIDL\00\00
    passes none.
    result
    decodes to
    ()
    .
  3. Replace the code later. The same call with
    mode = variant { upgrade = null }
    keeps the stable memory;
    variant { reinstall }
    wipes all state. A canister built with enhanced orthogonal persistence (current Motoko) rejects
    upgrade = null
    : upgrade it with
    variant { upgrade = opt record { wasm_memory_persistence = opt variant { keep } } }
    . Use
    keep
    only for such a build: the IC rejects it when the new module lacks the
    enhanced-orthogonal-persistence
    custom section (a Rust canister, or classical-persistence Motoko), so those keep
    upgrade = null
    . (The operator's guide says other canisters ignore
    keep
    ; the IC interface spec says otherwise, and the spec wins.)
  4. A module over about 2 MB (the single-message limit) goes up with
    upload_chunk
    , then installs with
    install_chunked_code
    .
The operator relays only
create_canister
,
canister_status
,
update_settings
,
install_code
,
upload_chunk
,
clear_chunk_store
,
install_chunked_code
,
start_canister
and
stop_canister
, and only on canisters that list you as a controller. Any other method, the operator itself, and protected canisters come back as
Err
CallFailed
with a
reason
, as does any
proxy
call on a canister while an
update_settings
on it is in flight: retry once it completes.
cycles
is ignored, since the engine charges nothing.
Err
UnauthorizedUser
means the call was not signed by a member: check that you passed
derivation_origin
, then go back to M3.
连接器可能无法直接调用 IC 管理 canister(
aaaaa-aa
)。engine-operator 的
proxy
方法
会为你代为调用,调用者身份即为你签名所用的身份。不要把它与步骤 5 的 proxy canister 混淆:后者为你的应用代码转发链上密钥调用,与部署无关。
每一步都是一次
canister_update_call
,其中
canister_id
为 engine-operator,
method = "proxy"
,
app_url
为应用 URL,
derivation_origin
为 M2 中
open_app
返回的 derivation origin(如果选择了某个
account
,还要带上 M3 中的同一个
account
)。务必传入
derivation_origin
:不传则调用以匿名方式运行,
proxy
会返回
UnauthorizedUser
。
args
为:
candid
(record {
  canister_id = principal "aaaaa-aa";
  method = "<management method name>";
  args = blob "<the method's argument, Candid-encoded>";
  cycles = 0;
})
args
保存管理方法参数的二进制 Candid 编码(以
DIDL
开头的字节),写成带
\xx
转义的
blob "…"
字面量。它不是文本形式的 Candid:请在代码沙箱中用 Candid 库编码。成功时返回
variant { Ok = record { result = blob "…" } }
,其中
result
是该方法的二进制 Candid 回复。参数与回复类型见 https://docs.internetcomputer.org/references/ic.did。
  1. 创建。
    method = "create_canister"
    ,
    args
    编码为:
    candid
    (record { settings = opt record { controllers = opt vec { principal "<engine-operator-id>" } } })
    把 engine-operator 列为 controller。你(
    P
    )会被自动添加为 controller,但如果不把 operator 加入,
    proxy
    就再也无法触达该 canister:既不能安装代码、不能改设置,所有者也无法
    deleteCanisters
    。如果代码在初始化时读取环境变量(如
    PROXY_CANISTER_ID
    ),现在就把
    environment_variables
    加入这些
    settings
    :它必须在步骤 2 之前就位(见 M6)。
    result
    解码为
    (record { canister_id : principal })
    。
  2. 安装。
    method = "install_code"
    ,
    args
    编码为:
    candid
    (record {
      mode = variant { install };
      canister_id = principal "<canister id from step 1>";
      wasm_module = blob "<wasm bytes, gzipped or not>";
      arg = blob "DIDL\00\00";
      sender_canister_version = null;
    })
    arg
    是二进制 Candid 的 init 参数;
    DIDL\00\00
    表示不传参。
    result
    解码为
    ()
    。
  3. 之后替换代码。 同样的调用,改用
    mode = variant { upgrade = null }
    可保留稳定内存;
    variant { reinstall }
    会清除所有状态。使用增强型正交持久化(当前 Motoko)构建的 canister 会拒绝
    upgrade = null
    :请改用
    variant { upgrade = opt record { wasm_memory_persistence = opt variant { keep } } }
    来升级。只有这类构建才使用
    keep
    :当新 module 缺少
    enhanced-orthogonal-persistence
    自定义段时(Rust canister,或使用经典持久化的 Motoko),IC 会拒绝它,因此那些构建仍使用
    upgrade = null
    。(operator 指南说其他 canister 会忽略
    keep
    ;IC 接口规范说法相反,以规范为准。)
  4. 超过约 2 MB 的 module(单条消息上限)需先用
    upload_chunk
    上传,再用
    install_chunked_code
    安装。
operator 只转发
create_canister
、
canister_status
、
update_settings
、
install_code
、
upload_chunk
、
clear_chunk_store
、
install_chunked_code
、
start_canister
和
stop_canister
,且只作用于把你列为 controller 的 canister。其他方法、operator 自身以及受保护的 canister 都会返回
Err
CallFailed
并附带
reason
;在某个 canister 的
update_settings
正在进行时对其发起
proxy
调用同样如此:待其完成后重试一次。
cycles
会被忽略,因为引擎不收费。
Err
UnauthorizedUser
表示该调用不是以成员身份签名:检查是否传入了
derivation_origin
,然后回到 M3。

M6. Name the app, and pass configuration

M6. 为应用命名并传入配置

Step 2's
__META_*
variables, and
PROXY_CANISTER_ID
from Step 5, are canister environment variables. With no
icp.yaml
to carry them, you set them yourself, and when matters:
  • A variable the code reads at init or upgrade (
    PROXY_CANISTER_ID
    , a key name, any configuration) must be set before the
    install_code
    that reads it. Otherwise init sees it missing, and traps or bakes in a fallback that a later upgrade does not undo. Put it in
    create_canister
    's
    settings
    (M5, step 1), or set it with
    update_settings
    between steps 1 and 2. Before an upgrade or reinstall that should see a new value, set that value first.
  • Display-only metadata (
    __META_*
    ) is read by the console, not by your code, so it can follow at any time.
    __META_BASE_URL
    needs the canister id, so it comes after step 1 anyway.
Either way it is
update_settings
through
proxy
, with
args
encoding:
candid
(record {
  canister_id = principal "<canister id>";
  settings = record {
    environment_variables = opt vec {
      record { name = "__META_PROJECT"; value = "My App" };
      record { name = "__META_NAME"; value = "App" };
      record { name = "__META_MAIN_CANISTER"; value = "true" };
    };
  };
})
The list replaces the canister's whole set of variables, so send all of them every time. The rules for their values are in Step 2.
步骤 2 的
__META_*
变量和步骤 5 的
PROXY_CANISTER_ID
都是 canister 环境变量。没有
icp.yaml
承载它们时,需要自行设置,且时机很重要:
  • 代码在 init 或 upgrade 时读取的变量(
    PROXY_CANISTER_ID
    、某个 key 名、任何配置)必须在读取它的
    install_code
    之前
    设置。否则 init 会发现它缺失,从而 trap,或固化一个后续 upgrade 无法撤销的兜底值。把它放进
    create_canister
    的
    settings
    (M5,步骤 1),或在步骤 1 与步骤 2 之间用
    update_settings
    设置。在应看到新值的 upgrade 或 reinstall 之前,先设置该值。
  • 仅用于展示的元数据(
    __META_*
    )由控制台读取,而非你的代码,因此可以随时设置。
    __META_BASE_URL
    需要 canister id,所以本来也要在步骤 1 之后才设置。
两种方式都是通过
proxy
执行
update_settings
,
args
编码为:
candid
(record {
  canister_id = principal "<canister id>";
  settings = record {
    environment_variables = opt vec {
      record { name = "__META_PROJECT"; value = "My App" };
      record { name = "__META_NAME"; value = "App" };
      record { name = "__META_MAIN_CANISTER"; value = "true" };
    };
  };
})
该列表会替换 canister 的全部变量集合,因此每次都要发送所有变量。其取值规则见步骤 2。

M7. Verify

M7. 验证

  • canister_status
    through
    proxy
    , with
    args
    encoding
    (record { canister_id = principal "<canister id>" })
    , shows
    status = variant { running }
    and the installed
    module_hash
    .
  • A canister that serves HTTP is reachable at
    https://<canister-id>.icp.net
    . On an all-in-one engine it is under the engine's own domain instead: the operator's guide names which.
  • The canister appears on the engine's Your apps and services page in the console.
Report the canister id(s), and the URL if any, back to the user.
  • 通过
    proxy
    执行
    canister_status
    ,
    args
    编码为
    (record { canister_id = principal "<canister id>" })
    ,会显示
    status = variant { running }
    以及已安装的
    module_hash
    。
  • 提供 HTTP 服务的 canister 可通过
    https://<canister-id>.icp.net
    访问。在 all-in-one 引擎上,它位于引擎自己的域名之下:operator 指南会说明是哪一个。
  • 该 canister 会出现在控制台的 Your apps and services 页面上。
把 canister id(如有还有 URL)反馈给用户。

Step 1 — Link the CLI to your engine identity (CLI route, once per machine)

步骤 1 —— 把 CLI 关联到你的引擎身份(CLI 路径,每台机器一次)

The CLI must sign as the same identity that administers the engine — that is the principal you log in to the console with.
CLI 必须以与管理该引擎相同的身份签名——也就是你登录控制台时使用的 principal。

Step 1.0 — First determine WHERE the CLI runs relative to the browser

步骤 1.0 —— 先确定 CLI 与浏览器的相对位置

icp identity link web
completes the sign-in via a redirect to
http://127.0.0.1:<port>
on the machine where the CLI runs. The browser in which the user completes the Internet Identity sign-in must be able to reach that loopback address. Determine the environment before linking:
  • CLI and browser on the same machine, with network (local development, or a terminal-integrated agent on the user's own machine) → use the normal link flow below.
  • CLI in a remote or isolated sandbox, with network (the agent runs in the cloud; the user's browser is on a different machine) → the normal flow cannot work: the sign-in URL carries a
    callback=http://127.0.0.1:<port>
    bound to the sandbox, the user's browser resolves
    127.0.0.1
    to its own machine, and the delegation never reaches the CLI. Later commands then fail with authorization errors. If you have the ICP MCP tools, stop here and use the ICP MCP route. Otherwise ask the user to switch to a local session, or to add the ICP MCP connector (see "Choose the Deploy Route First"). Use the delegation handoff below only if they can do neither.
  • CLI shell with no network at all (e.g. a sandboxed device bridge on the user's own machine: DNS blocked, HTTPS requests fail, writes limited to
    /tmp
    ) → no
    icp
    network command can run there — not the link, and not
    icp deploy
    either. The delegation handoff does not help: it only moves signing authority, not network access. Do not retry, tunnel, or proxy. Prepare the project and hand the user one script to run in their real terminal — see "No-network CLI host" below.
When in doubt, probe before linking:
curl -sI https://<console-origin>
failing (or DNS not resolving) from the CLI shell means the no-network case.
Never present a sandbox
127.0.0.1
URL to the user as something to open in their browser — it is unreachable from their machine. And do not invent a headless flag on
icp identity link web
: as of icp-cli 1.0.2 it has none (confirm with
icp identity link web --help
).
icp identity link web
通过重定向到运行 CLI 的那台机器上的
http://127.0.0.1:<port>
来完成登录。用户完成 Internet Identity 登录的浏览器必须能访问到这个 loopback 地址。关联前先确定环境:
  • CLI 与浏览器在同一台机器上且有网络(本地开发,或用户自己机器上的终端集成 Agent)→ 使用下面正常的关联流程。
  • CLI 位于远程或隔离的沙箱中且有网络(Agent 运行在云上;用户浏览器在另一台机器上)→ 正常流程无法工作:登录 URL 携带绑定到沙箱的
    callback=http://127.0.0.1:<port>
    ,用户的浏览器会把
    127.0.0.1
    解析到它自己的机器,委派永远送不到 CLI。之后命令就会因授权错误失败。如果你有 ICP MCP 工具,请停下并改用 ICP MCP 路径。否则请让用户切换到本地会话,或添加 ICP MCP 连接器(见"先选择部署路径")。只有当用户两者都无法做到时,才使用下面的委派交接。
  • 完全没有网络的 CLI shell(例如用户自己机器上的沙箱设备 bridge:DNS 被阻断、HTTPS 请求失败、只能写入
    /tmp
    )→ 任何
    icp
    网络命令都无法在那里运行——既不能关联,也不能
    icp deploy
    。委派交接也无济于事:它只转移签名权限,不转移网络访问能力。不要重试、不要打隧道、不要做代理。请准备好项目并交给用户一个脚本,在他们的真实终端中运行——见下面的"无网络 CLI 主机"。
拿不准时先探测再关联:从 CLI shell 执行
curl -sI https://<console-origin>
失败(或 DNS 无法解析)即属于无网络情况。
绝不要把沙箱的
127.0.0.1
URL 呈现给用户、让他在自己浏览器里打开——从他的机器无法访问。也不要臆造
icp identity link web
的 headless 参数:截至 icp-cli 1.0.2 它没有该参数(用
icp identity link web --help
确认)。

Delegation handoff (CLI host and browser on different machines)

委派交接(CLI 主机与浏览器在不同机器上)

icp identity delegation
transfers signing authority from an identity linked on the user's machine to a session key on the CLI host, without the browser ever reaching the CLI host. It requires
icp
installed on the user's machine too, and exists in icp-cli 1.0.x — verify with
icp identity delegation --help
on both machines. If the user's machine has
icp
and you can run commands there, the simplest path is to run this whole skill there instead; otherwise:
  1. On the CLI host (sandbox) — create a pending identity with a fresh session key:
    bash
    icp identity delegation request <your-identity-name>
    It prints the session public key as a PEM to stdout. Give that PEM block to the user. (If the default
    --storage keyring
    fails in a headless sandbox, retry with
    --storage plaintext
    .)
  2. On the user's machine — the user links there if not already linked (
    icp identity link web <local-name> --app <console-domain>
    — the normal flow works locally), saves the PEM to a file, and signs a delegation to it:
    bash
    icp identity delegation sign --identity <local-name> --key-pem session-key.pem --duration 8h > delegation.json
    --duration
    takes e.g.
    30m
    ,
    8h
    ,
    1d
    ; optionally
    --canisters <ids>
    restricts the delegation. The user sends
    delegation.json
    back. If
    sign
    fails with
    delegation for identity <name> has expired or will expire within 5 minutes
    , the local web session has lapsed — run
    icp identity reauth <local-name>
    (the normal browser flow, which works locally) and retry.
  3. On the CLI host — complete the pending identity and activate it:
    bash
    icp identity delegation use <your-identity-name> --from-json delegation.json
    icp identity default <your-identity-name>
    icp identity principal   # must print the user's console principal
Treat
delegation.json
as a time-limited credential: whoever holds the sandbox's session key can sign as the user's console principal until it expires. Keep the duration short and re-run the handoff when it lapses.
icp identity delegation
把签名权限从用户机器上已关联的身份转移到 CLI 主机上的会话密钥,全程浏览器都无需访问 CLI 主机。它要求用户机器上也安装了
icp
,并存在于 icp-cli 1.0.x 中——在两台机器上分别用
icp identity delegation --help
验证。如果用户机器上有
icp
且你能在那里运行命令,最简单的做法是直接在那边运行整个 skill;否则:
  1. 在 CLI 主机(沙箱)上 —— 用新的会话密钥创建待定身份:
    bash
    icp identity delegation request <your-identity-name>
    它会把会话 public 密钥以 PEM 形式打印到 stdout。把该 PEM 块交给用户。(如果默认的
    --storage keyring
    在无头沙箱中失败,请改用
    --storage plaintext
    重试。)
  2. 在用户机器上 —— 如果尚未关联则先关联(
    icp identity link web <local-name> --app <console-domain>
    ——正常流程在本地可用),把 PEM 保存到文件,并对它签署一份委派:
    bash
    icp identity delegation sign --identity <local-name> --key-pem session-key.pem --duration 8h > delegation.json
    --duration
    可取如
    30m
    、
    8h
    、
    1d
    ;可选的
    --canisters <ids>
    可限制委派范围。用户把
    delegation.json
    发回。如果
    sign
    失败并提示
    delegation for identity <name> has expired or will expire within 5 minutes
    ,说明本地 web 会话已失效——运行
    icp identity reauth <local-name>
    (正常浏览器流程,本地可用)后重试。
  3. 在 CLI 主机上 —— 完成待定身份并激活它:
    bash
    icp identity delegation use <your-identity-name> --from-json delegation.json
    icp identity default <your-identity-name>
    icp identity principal   # 必须打印用户的控制台 principal
把
delegation.json
视为有时效的凭据:持有沙箱会话密钥的人可以在其过期前以用户的控制台 principal 签名。让时长保持较短,过期后重新执行交接。

No-network CLI host — hand the user one script

无网络 CLI 主机 —— 交给用户一个脚本

If the CLI shell cannot reach the network, the user's real terminal is the deploy machine — and because their terminal and browser share a loopback there, the normal link flow works; no delegation handoff is needed. Your job shifts to preparation:
  1. Get the built project into a directory the user's terminal can reach.
  2. Write one script at the project root that does the whole network-bound sequence — adapt this template (fill in the real identity name, console domain, and subnet id; do not leave placeholders):
    bash
    #!/usr/bin/env bash
    set -euo pipefail
    icp --version
    icp identity list | grep -E '^\*? *<your-identity-name> ' >/dev/null || icp identity link web <your-identity-name> --app <console-domain>
    icp identity default <your-identity-name>
    icp deploy -e ic --subnet <subnet-id>
  3. Ask the user to run it in their terminal, complete the Internet Identity sign-in when the browser opens, and paste the output back.
  4. Verify from the pasted output (canister ids, frontend URL) and continue — a re-deploy for the Step 2
    __META_*
    variables goes through the same script.
如果 CLI shell 无法访问网络,用户的真实终端就是部署机器——而且因为他们的终端与浏览器在那里共享 loopback,正常的关联流程可以工作;无需委派交接。你的工作转为准备:
  1. 把已构建的项目放到用户终端可访问的目录中。
  2. 在项目根目录写一个脚本,执行全部需要网络的步骤——按需改造以下模板(填入真实的身份名、控制台域名和子网 id;不要留下占位符):
    bash
    #!/usr/bin/env bash
    set -euo pipefail
    icp --version
    icp identity list | grep -E '^\*? *<your-identity-name> ' >/dev/null || icp identity link web <your-identity-name> --app <console-domain>
    icp identity default <your-identity-name>
    icp deploy -e ic --subnet <subnet-id>
  3. 请用户在他们的终端中运行它,在浏览器打开时完成 Internet Identity 登录,并把输出粘贴回来。
  4. 根据粘贴的输出进行验证(canister ids、前端 URL)并继续——为步骤 2 的
    __META_*
    变量重新部署也走同一个脚本。

Normal link flow (CLI and browser share a loopback)

正常关联流程(CLI 与浏览器共享 loopback)

First check what already exists:
bash
icp identity list      # names + principals; * marks the active identity
The list does not show which console (if any) an identity was linked against — that cannot be determined from the CLI. Decide like this:
  • Only
    anonymous
    (or plain local identities) listed
    — no web-linked identity exists; run the link command below.
  • An identity the user recognizes as their engine identity (by name or principal) — set it active (below) and skip to Step 2.
  • Unsure — ask the user, or simply relink under a new name; linking again is cheap and safe.
To link, run this, substituting a name the user picks —
<your-identity-name>
is any local label, not a fixed value (do not hardcode something like
my-engine-admin
); reuse the same name in every command below:
bash
icp identity link web <your-identity-name> --app <console-domain>
  • <console-domain>
    is the host of the console origin, with no scheme, port or path:
    opencloud.org
    for the default console,
    beta.opencloud.org
    for
    https://beta.opencloud.org
    . The console derives its principal from the host it serves, so this is the domain to name. Do not take it from
    /.well-known/ii-derivation-origin
    : that file serves the ICP MCP route and can name another host.
  • Never omit
    --app
    . Without it, Internet Identity derives the principal for
    cli.id.ai
    , which is not your console, and the engine rejects every deploy as unauthorized.
  • Do not use
    --auth <console-origin>
    for the OpenCloud console. It reaches the same principal, but through the console's own
    /cli
    page, so the user signs in on two screens instead of one. Use
    --auth <console-origin>
    (no
    --app
    ) only when the user says their console signs in with its own Internet Identity rather than
    id.ai
    , as a test deployment does.
  • The command first waits at a "Press Enter to log in" prompt before anything happens. Run it interactively when you can; in a non-interactive shell (e.g. a background process) pipe a real newline:
    bash
    printf '\n' | icp identity link web <your-identity-name> --app <console-domain>
    Do not redirect stdin from
    /dev/null
    — the bare EOF does not satisfy the prompt, and the command sits on "Press Enter to log in" indefinitely with no browser ever opening.
  • After Enter it opens a browser tab. The user completes the Internet Identity sign-in there. Wait for them to confirm before continuing — you cannot complete the sign-in for them.
  • On first use, id.ai can stop at a "CLI access disabled" screen. That is the expected first run, not an error. Tell the user to turn on CLI access for their identity in the Internet Identity settings, then run the link command again from the start: the old sign-in URL is single-use. See the
    agent-web-identity
    skill, Pitfall 1.
  • --app
    must be the exact console host, e.g.
    opencloud.org
    . Another domain derives a different principal, and the engine will reject the deploy as unauthorized.
  • This is a one-time, per-machine step.
Then make it the active identity and verify:
bash
icp identity default <your-identity-name>
icp identity default     # prints the active identity name
icp identity principal   # prints the principal the deploy will sign as
先检查已存在什么:
bash
icp identity list      # 名称 + principal;* 标记当前身份
该列表不显示某个身份关联到了哪个控制台(如果有的话)——这无法通过 CLI 判断。按如下方式决定:
  • 只列出
    anonymous
    (或普通本地身份)—— 不存在 web 关联身份;执行下面的关联命令。
  • 存在用户认得出的引擎身份(按名称或 principal)—— 把它设为当前身份(见下)并跳到步骤 2。
  • 不确定 —— 询问用户,或直接用新名称重新关联;再次关联既便宜又安全。
关联时运行以下命令,名称由用户自选——
<your-identity-name>
是任意本地标签,不是固定值(不要硬编码类似
my-engine-admin
的东西);在下面所有命令中复用同一个名称:
bash
icp identity link web <your-identity-name> --app <console-domain>
  • <console-domain>
    是控制台源的主机名,不带 scheme、端口或路径:默认控制台为
    opencloud.org
    ,
    https://beta.opencloud.org
    为
    beta.opencloud.org
    。控制台从它所服务的主机名派生 principal,所以要指定的就是这个域名。不要从
    /.well-known/ii-derivation-origin
    取:那个文件服务于 ICP MCP 路径,可能指向另一个主机。
  • 绝不要省略
    --app
    。省略后 Internet Identity 会派生
    cli.id.ai
    的 principal,那不是你的控制台,引擎会把每次部署都当作未授权而拒绝。
  • 对 OpenCloud 控制台不要使用
    --auth <console-origin>
    。它能到达同一个 principal,但会走控制台自己的
    /cli
    页面,导致用户在两个页面而不是一个页面登录。只有当用户表示其控制台使用自己的 Internet Identity(而非
    id.ai
    )登录时,才使用
    --auth <console-origin>
    (不带
    --app
    ),例如测试部署就是如此。
  • 该命令一开始会停在 "Press Enter to log in" 提示。可以交互式运行时就这样运行;在非交互式 shell(例如后台进程)中请管道传入一个真实换行符:
    bash
    printf '\n' | icp identity link web <your-identity-name> --app <console-domain>
    不要把 stdin 从
    /dev/null
    重定向——单纯的 EOF 无法满足提示,命令会永远停在 "Press Enter to log in",浏览器永远不会打开。
  • 按下 Enter 后会打开一个浏览器标签页。由用户在那里完成 Internet Identity 登录。继续之前等待他们确认——你无法替他们完成登录。
  • 首次使用时,id.ai 可能停在 "CLI access disabled" 页面。这是预期的首次运行,不是错误。告诉用户在 Internet Identity 设置中为其身份开启 CLI access,然后从头重新运行关联命令:旧的登录 URL 是单次有效的。参见
    agent-web-identity
    skill,陷阱 1。
  • --app
    必须是精确的控制台主机名,例如
    opencloud.org
    。其他域名会派生出不同的 principal,引擎会以未授权拒绝部署。
  • 这是每台机器一次性的步骤。
然后把它设为当前身份并验证:
bash
icp identity default <your-identity-name>
icp identity default     # 打印当前身份名称
icp identity principal   # 打印部署将用于签名的 principal

Step 2 — Name the app (and give it an icon) in the console (recommended)

步骤 2 —— 在控制台中为应用命名(并指定图标)(推荐)

By default, CLI-deployed canisters appear on the engine console's Your apps and services page as bare rows labelled only by their principal id. A set of canister environment variables makes the console group them into a single named application with readable per-canister labels, an "Open" button, and an icon. Set them once in your project config:
  • __META_PROJECT
    — the application name. Canisters that share the same value are grouped into one named app, so set an identical value on every canister of the app.
  • __META_NAME
    — the per-canister display label (e.g.
    Backend
    ,
    Frontend
    ).
  • __META_MAIN_CANISTER
    — the literal string
    "true"
    on exactly one canister (the entry point, usually the frontend/asset canister). This marks the app's main canister: the console reads
    __META_BASE_URL
    and
    __META_ICON_PATH
    only from it, and the "Open" button targets it.
  • __META_BASE_URL
    — an absolute
    https://
    URL
    , set on the main canister (e.g. the frontend canister's URL
    https://<frontend-canister-id>.icp.net
    , or a custom domain). When present and valid, it is the URL the "Open" button opens; when absent or not
    https
    , the "Open" button falls back to the main canister's gateway URL. It is also the base that
    __META_ICON_PATH
    resolves against.
  • __META_ICON_PATH
    — the path to the app icon, resolved against
    __META_BASE_URL
    to form the icon the console renders (e.g.
    /favicon.svg
    →
    https://<base>/favicon.svg
    ). Set it on the main canister, alongside
    __META_BASE_URL
    .
The icon and "Open" link are read only from the main canister (the one marked
__META_MAIN_CANISTER: "true"
) —
__META_BASE_URL
/
__META_ICON_PATH
on any other canister are ignored.
On the ICP MCP route there is no project config: set the same variables with
update_settings
(M6). On the CLI route, set them under each canister's
settings.environment_variables
— this is valid alongside a recipe. With per-canister
canister.yaml
files:
yaml
undefined
默认情况下,通过 CLI 部署的 canister 会在引擎控制台的 Your apps and services 页面上显示为只有 principal id 的裸行。一组 canister 环境变量可以让控制台把它们归组为一个具名应用,并显示可读的每个 canister 标签、"Open" 按钮和图标。在你的项目配置中设置一次:
  • __META_PROJECT
    —— 应用名称。共享相同值的 canister 会被归组为一个具名应用,因此请在该应用的每个 canister 上设置相同的值。
  • __META_NAME
    —— 每个 canister 的显示标签(例如
    Backend
    、
    Frontend
    )。
  • __META_MAIN_CANISTER
    —— 在且仅在一个 canister 上设置字面字符串
    "true"
    (入口点,通常是前端/asset canister)。它标记应用的 main canister:控制台只从它读取
    __META_BASE_URL
    和
    __META_ICON_PATH
    ,"Open" 按钮也指向它。
  • __META_BASE_URL
    —— 一个绝对的
    https://
    URL
    ,设置在 main canister 上(例如前端 canister 的 URL
    https://<frontend-canister-id>.icp.net
    ,或自定义域名)。存在且有效时,它就是 "Open" 按钮打开的 URL;缺失或不是
    https
    时,"Open" 按钮回退到 main canister 的网关 URL。它同时也是
    __META_ICON_PATH
    解析时的基准。
  • __META_ICON_PATH
    —— 应用图标的路径,会基于
    __META_BASE_URL
    解析成控制台渲染的图标(例如
    /favicon.svg
    →
    https://<base>/favicon.svg
    )。与
    __META_BASE_URL
    一起设置在 main canister 上。
图标和 "Open" 链接只从 main canister 读取(即标记
__META_MAIN_CANISTER: "true"
的那个)——其他任何 canister 上的
__META_BASE_URL
/
__META_ICON_PATH
都会被忽略。
在 ICP MCP 路径上没有项目配置:用
update_settings
设置同样的变量(M6)。在 CLI 路径上,在每个 canister 的
settings.environment_variables
下设置——这与 recipe 并用也有效。使用每个 canister 的
canister.yaml
文件时:
yaml
undefined

frontend/canister.yaml

frontend/canister.yaml

name: frontend recipe: type: "@dfinity/static-site@v0.4.3" configuration: build: - npm install - npm run build dir: dist settings: environment_variables: __META_PROJECT: "My App" __META_NAME: "Frontend" __META_MAIN_CANISTER: "true" __META_BASE_URL: "https://<frontend-canister-id>.icp.net" __META_ICON_PATH: "/favicon.svg"

```yaml
name: frontend recipe: type: "@dfinity/static-site@v0.4.3" configuration: build: - npm install - npm run build dir: dist settings: environment_variables: __META_PROJECT: "My App" __META_NAME: "Frontend" __META_MAIN_CANISTER: "true" __META_BASE_URL: "https://<frontend-canister-id>.icp.net" __META_ICON_PATH: "/favicon.svg"

```yaml

backend/canister.yaml

backend/canister.yaml

name: backend recipe: type: "@dfinity/motoko@v5.0.0" # v5 reads main/candid from mops.toml ([canisters.backend]) — see the icp-cli skill settings: environment_variables: __META_PROJECT: "My App" __META_NAME: "Backend"

For a single inline `icp.yaml` (canisters defined there directly), put the same `settings.environment_variables` block under each canister entry. Note the inline form: `canisters` is an **array** of `{name, recipe, settings}` items, not a map keyed by canister name:

```yaml
name: backend recipe: type: "@dfinity/motoko@v5.0.0" # v5 从 mops.toml 读取 main/candid([canisters.backend])——见 icp-cli skill settings: environment_variables: __META_PROJECT: "My App" __META_NAME: "Backend"

对于单个内联 `icp.yaml`(canister 直接定义在其中),把同样的 `settings.environment_variables` 块放在每个 canister 条目下。注意内联形式:`canisters` 是 `{name, recipe, settings}` 项的**数组**,不是以 canister 名称为键的映射:

```yaml

icp.yaml — canisters defined inline

icp.yaml —— 内联定义的 canister

canisters:
  • name: frontend recipe: # … as in the canister.yaml example above settings: environment_variables: __META_PROJECT: "My App" __META_NAME: "Frontend" __META_MAIN_CANISTER: "true" __META_BASE_URL: "https://<frontend-canister-id>.icp.net" __META_ICON_PATH: "/favicon.svg"
  • name: backend recipe: # … as in the canister.yaml example above settings: environment_variables: __META_PROJECT: "My App" __META_NAME: "Backend"

Notes:
- icp-cli **merges** these with the `PUBLIC_CANISTER_ID:<name>` variables it injects automatically at deploy time — the asset canister keeps serving and the app keeps working. (Verified against icp-cli 0.3.0.)
- All values are strings; `__META_MAIN_CANISTER` must be the exact string `"true"`.
- They are applied during `icp deploy` (the "Setting environment variables" step). After deploy, confirm with `icp canister settings show <name> -e ic`.

Icon specifics (the console builds the icon as `__META_BASE_URL` + `__META_ICON_PATH`):
- **Both** must be present and **on the main canister** for an icon to appear — there is no fallback. `__META_ICON_PATH` alone does nothing.
- `__META_BASE_URL` must parse as an absolute **`https://`** URL. A bare host, an `http://` URL, or a `data:` / `javascript:` value is rejected: the icon then does not render, and the "Open" button falls back to the main canister's gateway URL (it does not disappear). (The console validates the scheme before using it.)
- `__META_ICON_PATH` is a **path to an asset your frontend actually serves** (e.g. `/favicon.svg`), not an inline image. The resolved URL is rendered as an `<img>` `src`, so it must return an image. Do **not** put a `data:` URI here: engine env values are length-capped (≤128 chars observed), so it would not fit, and the field is a path by design.
- The frontend canister's id is only known **after** the first deploy. The usual flow is: deploy once, read the frontend canister id from the output, set `__META_BASE_URL` to `https://<that-id>.icp.net` (and `__META_ICON_PATH`), then re-deploy to apply. If you control a custom domain for the app, you can set it up front instead.
canisters:
  • name: frontend recipe: # ……与上面的 canister.yaml 示例相同 settings: environment_variables: __META_PROJECT: "My App" __META_NAME: "Frontend" __META_MAIN_CANISTER: "true" __META_BASE_URL: "https://<frontend-canister-id>.icp.net" __META_ICON_PATH: "/favicon.svg"
  • name: backend recipe: # ……与上面的 canister.yaml 示例相同 settings: environment_variables: __META_PROJECT: "My App" __META_NAME: "Backend"

说明:
- icp-cli 会把这些变量与它在部署时自动注入的 `PUBLIC_CANISTER_ID:<name>` 变量**合并**——asset canister 继续提供服务,应用继续正常工作。(已在 icp-cli 0.3.0 上验证。)
- 所有值都是字符串;`__META_MAIN_CANISTER` 必须是精确字符串 `"true"`。
- 它们在 `icp deploy`("Setting environment variables" 步骤)期间生效。部署后用 `icp canister settings show <name> -e ic` 确认。

图标细节(控制台以 `__META_BASE_URL` + `__META_ICON_PATH` 构建图标):
- 两者必须**同时存在**且**位于 main canister 上**,图标才会出现——没有兜底。只有 `__META_ICON_PATH` 不起作用。
- `__META_BASE_URL` 必须能解析为绝对的 **`https://`** URL。裸主机名、`http://` URL 或 `data:` / `javascript:` 值都会被拒绝:此时图标不渲染,"Open" 按钮回退到 main canister 的网关 URL(按钮不会消失)。(控制台在使用前会校验 scheme。)
- `__META_ICON_PATH` 是**前端实际提供的资源的路径**(例如 `/favicon.svg`),不是内联图片。解析后的 URL 会作为 `<img>` 的 `src` 渲染,因此必须返回图片。**不要**在这里放 `data:` URI:引擎环境变量值有长度上限(观察到 ≤128 字符),根本放不下,而且该字段按设计就是一个路径。
- 前端 canister 的 id 只有在**首次部署之后**才知道。通常流程是:先部署一次,从输出中读取前端 canister id,把 `__META_BASE_URL` 设为 `https://<that-id>.icp.net`(以及 `__META_ICON_PATH`),然后重新部署以生效。如果你为应用控制了自定义域名,可以提前设置。

Pin the Internet Identity derivation origin (if the app signs users in)

固定 Internet Identity 派生源(如果应用需要用户登录)

Internet Identity derives a principal per origin. An app reached at both its canister address and a custom domain signs the same person in as two different users.
The engine console names the app's canister address as the origin to derive from. It cannot be renamed or removed, so it survives adding, changing, or dropping a custom domain. It is the address of the canister that serves your frontend (the asset/static-site canister the browser loads the app from), built from that canister's id:
https://<frontend-canister-id>.icp.net
That is usually the canister you marked
__META_MAIN_CANISTER: "true"
, but that flag is a console display setting, not a guarantee. If you marked a backend canister, still derive from the frontend canister. A backend canister cannot be a derivation origin: the browser is never on it, and it cannot serve the
.well-known/ii-alternative-origins
file Internet Identity fetches from that origin to validate the claim.
Build the value from the canister id, not from
__META_BASE_URL
. The two match only while
__META_BASE_URL
still points at the canister address. Pointing it at a custom domain is normal and supported (see the icon notes above), and the two then differ. A custom domain is the one value that must never become the derivation origin.
Do this before the app has users, not after. A domain that has already collected sign-ins cannot be repointed at a derivation origin without orphaning every account created under it. If the app might ever get a custom domain, set
derivationOrigin
on the first deploy even while the canister address is the only origin — it costs nothing then and cannot be applied retroactively without losing accounts.
For the mechanics — the
derivationOrigin
option and the
.well-known/ii-alternative-origins
file, including the
_headers
entry the
@dfinity/static-site
recipe needs — load the
user-sign-in
skill.
Caffeine apps are the exception: Caffeine owns their address, so it is not the app's to derive from. The console withholds the canister-address row for them.
Internet Identity 按源派生 principal。一个同时通过 canister 地址和自定义域名访问的应用,会把同一个人登录成两个不同用户。
引擎控制台指定应用的 canister 地址 作为派生源。它无法被重命名或移除,因此能在添加、修改或放弃自定义域名后继续存活。它是提供前端的那个 canister(浏览器加载应用的 asset/static-site canister)的地址,由该 canister 的 id 构造:
https://<frontend-canister-id>.icp.net
这通常就是你标记了
__META_MAIN_CANISTER: "true"
的 canister,但该标记只是控制台显示设置,并不能保证。如果你标记的是后端 canister,仍要从前端 canister 派生。后端 canister 不能作为派生源:浏览器永远不在它上面,而且它无法提供 Internet Identity 用于验证声明的
.well-known/ii-alternative-origins
文件。
该值要从 canister id 构造,不要从
__META_BASE_URL
构造。只有当
__META_BASE_URL
仍指向 canister 地址时两者才一致。把它指向自定义域名是正常且受支持的(见上面的图标说明),此时两者就不同了。自定义域名正是那个绝不能成为派生源的值。
要在应用还没有用户之前做这件事,而不是之后。 已经收集过登录的域名无法再被改为派生源,否则会孤立在该域名下创建的所有账户。如果应用将来可能使用自定义域名,那么首次部署时即设置
derivationOrigin
,即使当时 canister 地址是唯一的源——此时毫无成本,事后也无法在不丢账户的情况下补做。
具体机制——
derivationOrigin
选项和
.well-known/ii-alternative-origins
文件,包括
@dfinity/static-site
recipe 所需的
_headers
条目——请加载
user-sign-in
skill。
Caffeine 应用是例外:Caffeine 拥有自己的地址,因此不属于应用可派生的源。控制台会为它们隐藏 canister 地址那一行。

Version metadata (recommended)

版本元数据(推荐)

Embed build provenance into each canister's wasm so tooling and the console can show what version is running (console support is rolling out; the metadata is already readable — see the verify note below). Add this by default on every deploy — do not wait for the user to ask. All official recipes (motoko, rust, static-site, asset-canister, prebuilt) accept a
metadata
list under the recipe
configuration
; each entry is baked into the wasm as a custom section. Values are interpolated into a shell command at build time, so
$(…)
command substitution works. (Verified by live builds against
@dfinity/motoko
v4.1.0 and v5.0.0 on icp-cli 1.0.2.)
Git project (check first:
git rev-parse HEAD
succeeds):
yaml
recipe:
  type: "@dfinity/motoko@v5.0.0"
  configuration:
    metadata:
      - name: service:git:sha
        value: $(git rev-parse HEAD)$(git diff --quiet HEAD 2>/dev/null || echo +dirty)
      - name: service:git:origin
        value: $(git remote get-url origin)
      - name: service:git:updated_at
        value: $(git log -1 --format=%cI)
      - name: service:version
        value: $(node -p "require('./package.json').version" 2>/dev/null || echo 1.0.0)
Non-git project — the git substitutions above do not fail the build; they silently bake garbage (
service:git:sha
becomes the literal
+dirty
,
service:git:origin
comes out empty). Use only an explicit version, and bump it on each subsequent deploy:
yaml
metadata:
  - name: service:version
    value: "1.0.0"
Notes:
  • Use these exact names (
    service:git:sha
    ,
    service:git:origin
    ,
    service:git:updated_at
    ,
    service:version
    ) — they are the agreed convention the console will read; differently named entries will not be picked up.
  • Prefer command results over literals where possible:
    +dirty
    on the sha flags uncommitted changes, so a deploy is traceable to its exact source state.
  • Values must be deterministic for a given source tree: sha, origin, the last commit's date, a version string. Never embed a build time (
    $(date)
    ) or other build-time-varying values. The commit date (
    %cI
    ) is allowed because it is a property of the commit, not of the build — but note it means "code last changed", not "last deployed": deploying an old commit shows the old date. The deploy time itself comes from the canister history the network records automatically.
  • If the project has no
    package.json
    (or no version field), the fallback
    1.0.0
    applies; replace it with the project's real versioning scheme when one exists.
  • The sections are injected as
    icp:private
    , readable by the canister's controllers (you, and the console acting as you) via read_state — no canister call needed. Verify after deploy, with the linked identity active:
    icp canister metadata <canister-name> service:git:sha -e ic
    .
把构建来源信息嵌入每个 canister 的 wasm,让工具和控制台能显示当前运行的版本(控制台支持正在逐步推出;元数据已经可读——见下面的验证说明)。默认在每次部署时都添加——不要等用户提出。所有官方 recipe(motoko、rust、static-site、asset-canister、prebuilt)都接受 recipe
configuration
下的
metadata
列表;每个条目都会作为自定义段被烘焙进 wasm。值在构建时被插入 shell 命令,因此
$(…)
命令替换可用。(已针对 icp-cli 1.0.2 上
@dfinity/motoko
v4.1.0 和 v5.0.0 进行真实构建验证。)
Git 项目(先检查:
git rev-parse HEAD
能成功):
yaml
recipe:
  type: "@dfinity/motoko@v5.0.0"
  configuration:
    metadata:
      - name: service:git:sha
        value: $(git rev-parse HEAD)$(git diff --quiet HEAD 2>/dev/null || echo +dirty)
      - name: service:git:origin
        value: $(git remote get-url origin)
      - name: service:git:updated_at
        value: $(git log -1 --format=%cI)
      - name: service:version
        value: $(node -p "require('./package.json').version" 2>/dev/null || echo 1.0.0)
非 Git 项目 —— 上面的 git 替换不会让构建失败;它们会悄悄烘焙进垃圾内容(
service:git:sha
变成字面量
+dirty
,
service:git:origin
为空)。只使用明确的版本号,并在之后的每次部署中递增:
yaml
metadata:
  - name: service:version
    value: "1.0.0"
说明:
  • 使用这些精确名称(
    service:git:sha
    、
    service:git:origin
    、
    service:git:updated_at
    、
    service:version
    )——这是控制台会读取的约定名称;名称不同就不会被识别。
  • 尽可能使用命令结果而非字面量:sha 上的
    +dirty
    表明存在未提交改动,因此一次部署可以追溯到确切的源码状态。
  • 对给定源码树,值必须是确定性的:sha、origin、最后一次提交的时间、版本字符串。绝不要嵌入构建时间(
    $(date)
    )或其他随构建变化的值。提交日期(
    %cI
    )是可以的,因为它是提交的属性而非构建的属性——但请注意它表示"代码最后修改时间"而不是"最后部署时间":部署旧提交会显示旧日期。真正的部署时间来自网络自动记录的 canister 历史。
  • 如果项目没有
    package.json
    (或没有 version 字段),会使用兜底值
    1.0.0
    ;若项目已有自己的版本方案,请替换为真实方案。
  • 这些段以
    icp:private
    注入,canister 的 controller(你,以及以你身份行动的控制台)可通过 read_state 读取——无需 canister 调用。部署后用已激活的关联身份验证:
    icp canister metadata <canister-name> service:git:sha -e ic
    。

Step 3 — Deploy to the engine's subnet (CLI route)

步骤 3 —— 部署到引擎的子网(CLI 路径)

From the project root:
bash
icp deploy -e ic --subnet <subnet-id>
  • -e ic
    targets mainnet (the engine runs on an IC subnet);
    --subnet <subnet-id>
    pins the deploy to your engine's subnet. Confirm the exact flags with
    icp deploy --help
    before running if unsure.
  • Deploying consumes capacity on the engine; make sure the engine has room.
Alternative: packaged upload. If the project is distributed as a built
.icp
package and a direct
icp deploy
is not available, the user can upload the bundle instead: engine → Your apps and services → Upload a bundle, which walks through uploading the
.icp
bundle. The page's other button, Build with agents, gathers the other ways in: a coding agent, Caffeine, the CLI instructions this skill automates, and OpenSaaS for ready-made apps.
在项目根目录执行:
bash
icp deploy -e ic --subnet <subnet-id>
  • -e ic
    指向 mainnet(引擎运行在一个 IC 子网上);
    --subnet <subnet-id>
    把部署固定到你的引擎的子网。不确定时先运行
    icp deploy --help
    确认确切参数。
  • 部署会消耗引擎上的容量;请确保引擎有足够空间。
替代方案:打包上传。 如果项目以已构建的
.icp
包分发且无法直接
icp deploy
,用户可以改为上传 bundle:engine → Your apps and services → Upload a bundle,该流程会引导上传
.icp
bundle。该页面的另一个按钮 Build with agents 汇总了其他方式:编码 Agent、Caffeine、本 skill 自动化的 CLI 指令,以及 OpenSaaS 提供的现成应用。

Step 4 — Verify

步骤 4 —— 验证

  • The
    icp deploy
    output reports the deployed canister ids.
  • The canisters appear on the engine's Your apps and services page in the console; each canister's detail view offers an "Open in browser" link.
  • If you set the metadata in Step 2, the canisters are grouped under your
    __META_PROJECT
    name with their
    __META_NAME
    labels, and the main canister shows an "Open" button — instead of bare principal rows. With
    __META_BASE_URL
    +
    __META_ICON_PATH
    set, the app also shows its icon (allow for a short console cache delay).
  • A frontend (asset) canister is served at
    https://<frontend-canister-id>.icp.net
    .
Report the deployed canister ids (and the frontend URL, if any) back to the user.
  • icp deploy
    的输出会报告已部署的 canister id。
  • canister 会出现在控制台的 Your apps and services 页面上;每个 canister 的详情视图提供 "Open in browser" 链接。
  • 如果你在步骤 2 设置了元数据,canister 会以
    __META_PROJECT
    名称归组,并带有各自的
    __META_NAME
    标签,main canister 会显示 "Open" 按钮——而不是裸的 principal 行。设置了
    __META_BASE_URL
    +
    __META_ICON_PATH
    后,应用还会显示图标(请预留控制台缓存延迟)。
  • 前端(asset)canister 可通过
    https://<frontend-canister-id>.icp.net
    访问。
把已部署的 canister id(以及前端 URL,如果有)反馈给用户。

Step 5: Deploy a proxy canister (only if the app needs chain-key services)

步骤 5 —— 部署 proxy canister(仅当应用需要链上密钥服务时)

Skip this step unless the app calls threshold ECDSA or Schnorr (Bitcoin, Ethereum), vetKD / VetKeys, the exchange-rate canister (XRC), the Bitcoin API, or the EVM / SOL RPC canisters: a console proxy relays nothing else for the engine's canisters (the exact list is in
cloud-engine-canisters
). Everything else (the app's own execution, storage, messaging, and HTTPS outcalls) is free on an engine and needs no proxy at all.
Those services live on other subnets and charge cycles per call, and an engine canister can neither hold cycles nor send a cycle-bearing message across the engine boundary. A proxy canister on a normal Application subnet makes the call on its behalf and pays from its own balance.
If you are writing or deploying such an app and do not have the proxy id yet, ask for it now (What You Need, item 3) rather than deploying with a placeholder: the first proxied call would fail.
除非应用调用 threshold ECDSA 或 Schnorr(Bitcoin、Ethereum)、vetKD / VetKeys、汇率 canister(XRC)、Bitcoin API,或 EVM / SOL RPC canister,否则跳过本步骤:控制台 proxy 不会为引擎的 canister 转发其他任何内容(确切列表见
cloud-engine-canisters
)。其他一切(应用自身的执行、存储、消息传递和 HTTPS 出站调用)在引擎上都是免费的,完全不需要 proxy。
这些服务位于其他子网,并按调用收取 cycles;而引擎 canister 既不能持有 cycles,也不能跨引擎边界发送携带 cycles 的消息。普通 Application 子网上的 proxy canister 会代为发起调用,并用自己的余额支付。
如果你正在编写或部署这类应用但还没有 proxy id,请现在就索取("你需要什么"第 3 项),而不是带着占位符部署:第一次代理调用就会失败。

Which proxy

选择哪个 proxy

Two different canisters can play this role, and picking the wrong one produces a working-looking setup that fails at the first call:
Console proxySelf-deployed proxy
Deployed byThe engine's owner, from the consoleYou, with
icp
Authorized callersEvery canister on the engine's subnet (checked with the NNS registry), plus its controllerControllers only
Your engine canisters may call itYes, automaticallyOnly after you add each one as a controller
What it relays for themOnly chain-key, Bitcoin and exchange-rate / RPC services (list in
cloud-engine-canisters
)
Anything
Your CLI identity may call itNo (rejected as
UnauthorizedUser
)
Yes: you are a controller
Threshold-key derivationIsolated per calling canisterNo isolation
Funded withThe engine's balance, automatically (no card)Cycles you hold (
icp cycles mint
)
  • App code calling chain-key services → the console proxy. It is the one that admits your engine's canisters without per-canister configuration.
  • You calling something from the CLI (
    icp canister call --proxy
    ,
    icp deploy --proxy
    , canister-only management methods like
    canister_info
    or
    raw_rand
    ) → your own proxy. The console proxy cannot serve this: it rejects ingress from any non-controller principal, and your CLI identity is not one.
They are not substitutes, and they derive different keys: see the derivation warning in
cloud-engine-canisters
before switching an app from one to the other.
有两个不同的 canister 可以承担这个角色,选错会得到一个看起来正常却在第一次调用时失败的配置:
控制台 proxy自行部署的 proxy
部署方引擎的所有者,通过控制台你自己,使用
icp
授权的调用者引擎子网上的每个 canister(通过 NNS 注册表校验),以及它自己的 controller仅 controller
你的引擎 canister 可以调用它是,自动生效需要你把每个都添加为 controller 之后
它为调用者转发什么仅链上密钥、Bitcoin 以及汇率 / RPC 服务(列表见
cloud-engine-canisters
任意内容
你的 CLI 身份可以调用它否(被拒绝为
UnauthorizedUser
)
可以:你是它的 controller
阈值密钥派生按调用 canister 隔离无隔离
资金来源引擎的余额,自动充值(无需信用卡)你持有的 cycles(
icp cycles mint
)
  • 应用代码调用链上密钥服务 → 用控制台 proxy。 它能接纳你引擎上的 canister,无需逐个 canister 配置。
  • 你在 CLI 中发起调用(
    icp canister call --proxy
    、
    icp deploy --proxy
    、仅限 canister 的管理方法如
    canister_info
    或
    raw_rand
    )→ 用你自己的 proxy。 控制台 proxy 无法胜任:它拒绝任何非 controller principal 的入口访问,而你的 CLI 身份不是 controller。
二者不可互相替代,而且派生出不同的密钥:切换之前请先阅读
cloud-engine-canisters
中的派生警告。

Console proxy: the engine owner deploys it (a console action, not a CLI one)

控制台 proxy:由引擎所有者部署(控制台操作,而非 CLI 操作)

Only the engine's owner can deploy one, and only from the console. There is no
icp
command for it, and nothing an agent can call creates one: the console endpoints behind the button authenticate with a browser session cookie minted by the Internet Identity login. Hand the user these steps and wait for the proxy canister id:
  1. Open the engine in the console → Integrations in the engine's sidebar → the Proxy canisters card.
  2. Deploy a proxy, then Deploy proxy in the dialog. There is no amount to choose and no card is charged: the proxy is created on a normal Application subnet out of the engine's balance, starting with a few dollars' worth of cycles.
  3. Copy the proxy canister id from the card's table (it opens after a deploy; otherwise expand it with the N deployed toggle). That id is what the app calls.
The deploy is refused while the engine is not serving, or when the engine's balance has too little free to cover the proxy's first cycles: the owner adds funds to the engine, then retries.
How it stays funded. Every few minutes while its balance is below a low threshold, the proxy asks for a top-up, which is sent out of the engine's balance: capped per hour, and never out of what the engine owes for its nodes. There is no Top up button and no automatic top-up setting for it; its row shows the balance and the cycles it has drawn so far. If it runs dry anyway, fund the engine (see "Paying for an engine" below).
Also on that table: Refresh balance (a live read, since the displayed figure is cached) and Delete proxy (stops and deletes the canister; its unspent cycles, less the small reserve a canister keeps to run, go back to the engine's balance).
An engine may have more than one proxy ("Deploy another proxy"). Each has its own balance (all refilled from the same engine balance) and, for a signing app, its own key namespace.
只有引擎的所有者才能部署,而且只能从控制台部署。没有对应的
icp
命令,也没有任何 Agent 能调用的接口可以创建它:按钮背后的控制台端点依赖由 Internet Identity 登录产生的浏览器会话 cookie 认证。把下面的步骤交给用户,并等待 proxy canister id:
  1. 在控制台中打开引擎 → 引擎侧边栏中的 Integrations → Proxy canisters 卡片。
  2. 点击 Deploy a proxy,然后在对话框中点击 Deploy proxy。无需选择金额,也不会扣信用卡:proxy 会在普通 Application 子网上创建,从引擎余额支付,起始带有价值数美元的 cycles。
  3. 从卡片的表格中复制 proxy canister id(部署后会自动展开;否则用 N deployed 开关展开)。该 id 就是应用要调用的对象。
如果引擎未在服务,或引擎余额可用额度不足以覆盖 proxy 的首批 cycles,部署会被拒绝:所有者为引擎充值后重试。
它如何持续获得资金。 每隔几分钟,只要其余额低于某个低阈值,proxy 就会请求一次充值,从引擎余额中扣除:每小时有上限,且绝不会动用引擎应付给其节点的钱。它没有 Top up 按钮,也没有自动充值设置;它所在行会显示余额以及迄今已支取的 cycles。如果它还是耗尽了,请为引擎充值(见下面的"为引擎付费:选择哪个余额")。
该表格上还有:Refresh balance(实时读取,因为显示的数字是缓存的)和 Delete proxy(停止并删除该 canister;其未支取的 cycles,扣除 canister 为运行保留的小额储备后,会退回引擎余额)。
一个引擎可以有多个 proxy("Deploy another proxy")。每个都有自己的余额(都由同一引擎余额充值),并且对一个签名应用而言,各自拥有独立的密钥命名空间。

Wire the proxy id into the app

把 proxy id 接入应用

The app needs the id at runtime. Pass it as a canister environment variable rather than hardcoding it in source, so the same code can run against a local mock and against the engine:
yaml
settings:
  environment_variables:
    PROXY_CANISTER_ID: "<proxy-canister-id>"
On the ICP MCP route, set it with
update_settings
(M6). Read it in the canister the same way as any other environment variable, and treat it as permanent configuration: for an app that derives threshold keys, changing this value changes every address the app owns.
应用在运行时需要该 id。请把它作为 canister 环境变量传入,而不是硬编码在源码中,这样同一份代码既能跑在本地 mock 上,也能跑在引擎上:
yaml
settings:
  environment_variables:
    PROXY_CANISTER_ID: "<proxy-canister-id>"
在 ICP MCP 路径上,用
update_settings
设置(M6)。在 canister 中按读取其他环境变量同样的方式读取它,并视其为永久配置:对于派生阈值密钥的应用,改动该值会改变应用拥有的每一个地址。

Self-deployed proxy: the CLI path

自行部署的 proxy:CLI 路径

For proxying your own calls. This one is the upstream
dfinity/proxy-canister
, deployed from a template:
bash
icp new my-proxy --subfolder proxy       # pre-built wasm, no init args
cd my-proxy
icp deploy -e ic                         # NOT --subnet <engine-subnet>: see below
export PROXY_ID=$(icp canister status -e ic --id-only proxy)
Fund it, and check on it, with the cycles ledger:
bash
icp cycles balance -e ic                 # what you hold
icp cycles mint --icp 1 -e ic            # ICP -> cycles, if you need more
icp canister top-up "$PROXY_ID" --amount 5t -e ic
icp canister status "$PROXY_ID" -e ic    # the proxy's own balance
Then pass it to any command that needs cycles or a canister-only management method:
bash
icp canister call my-canister charge_me '()' -e ic --proxy "$PROXY_ID" --cycles 1_000_000_000_000
icp deploy -e ic --proxy "$PROXY_ID"
Three things to get right:
  • Do not deploy it onto the engine's subnet. A proxy on a
    CloudEngine
    subnet is useless: it holds 0 cycles and cannot send a cycle-bearing message either. Omit
    --subnet
    (Step 3's engine-subnet flag is for your app, not for this) so it lands on a normal Application subnet.
  • It authorizes controllers only. For an engine canister to call it, that canister's principal must be added as a controller (
    icp canister settings update "$PROXY_ID" --add-controller <canister-id> -e ic
    ), one call per canister, repeated whenever a canister is added. This is the maintenance burden the console proxy exists to remove.
  • It does not isolate key derivation. Any authorized caller can request any derivation path, and the keys it produces differ from the console proxy's. Do not point a signing app at one casually.
用于代理你自己的调用。这是上游的
dfinity/proxy-canister
,从模板部署:
bash
icp new my-proxy --subfolder proxy       # 预构建 wasm,无 init 参数
cd my-proxy
icp deploy -e ic                         # 不要用 --subnet <engine-subnet>:见下文
export PROXY_ID=$(icp canister status -e ic --id-only proxy)
用 cycles 账本为其充值并查看状态:
bash
icp cycles balance -e ic                 # 你持有的数量
icp cycles mint --icp 1 -e ic            # ICP -> cycles,如需更多
icp canister top-up "$PROXY_ID" --amount 5t -e ic
icp canister status "$PROXY_ID" -e ic    # proxy 自身的余额
然后把它传给任何需要 cycles 或仅限 canister 管理方法的命令:
bash
icp canister call my-canister charge_me '()' -e ic --proxy "$PROXY_ID" --cycles 1_000_000_000_000
icp deploy -e ic --proxy "$PROXY_ID"
有三件事必须做对:
  • 不要把它部署到引擎的子网上。 位于
    CloudEngine
    子网的 proxy 毫无用处:它持有 0 cycles,也无法发送携带 cycles 的消息。省略
    --subnet
    (步骤 3 的引擎子网参数是给你的应用用的,不是给它用的),让它落在普通 Application 子网上。
  • 它只授权 controller。 若要让引擎 canister 调用它,该 canister 的 principal 必须被添加为 controller(
    icp canister settings update "$PROXY_ID" --add-controller <canister-id> -e ic
    ),每个 canister 一次调用,每新增一个 canister 都要重复。这正是控制台 proxy 要消除的维护负担。
  • 它不隔离密钥派生。 任何被授权的调用者都可以请求任意派生路径,且它产生的密钥与控制台 proxy 的不同。不要随意把签名应用指向它。

Paying for an engine: which balance

为引擎付费:选择哪个余额

Two balances exist, they are funded differently, and the app's own canisters have neither. Do not "top up the canister" on an engine without first establishing which of these is meant:
BalanceWhat it pays forHow it is fundedWhat happens when it empties
Engine balanceThe engine itself (its nodes, day by day), and the top-ups of its console proxiesAdd funds on the engine's Billing page (charged to the card on file), and automatic top-ups that charge the card about a week before the balance would run outThe engine is deleted, with everything on it: not reversible, so treat a low-runway warning as urgent. An engine whose automatic top-up keeps failing is halted, and runs again once a payment lands
Proxy cycle balanceOnly the calls the proxy relays (signing, vetKD, XRC, Bitcoin API, EVM/SOL RPC)A console proxy refills itself from the engine balance (Step 5); a self-deployed one takes
icp canister top-up
Relayed calls fail with
InsufficientCycles
; the proxy freezes rather than being deleted, and recovers on a later top-up
A console proxy's top-ups come out of the engine balance, so a busy proxy shortens the engine's runway, though never by what the engine owes for its nodes.
The app's own canisters have none of these: they hold 0 cycles by design and cannot be topped up. A "0 cycles" reading on an engine canister is normal (see
cloud-engine-canisters
, pitfall 5).
存在两种余额,它们的充值方式不同,而且应用自身的 canister 两种都没有。在引擎上"为 canister 充值"之前,先弄清楚指的是哪一种:
余额用于支付什么如何充值耗尽时会发生什么
引擎余额引擎自身(其节点,逐日消耗),以及其控制台 proxy 的充值在引擎的 Billing 页面执行 Add funds(扣档案中的信用卡),以及在余额即将耗尽前约一周自动充值(同样扣信用卡)引擎被删除,其上的一切随之消失:不可逆,因此要严肃对待余额不足的警告。自动充值持续失败的引擎会停止运行,在款项到账后恢复
Proxy cycles 余额仅 proxy 转发的调用(签名、vetKD、XRC、Bitcoin API、EVM/SOL RPC)控制台 proxy 从引擎余额自行补充(步骤 5);自行部署的 proxy 使用
icp canister top-up
转发的调用失败并返回
InsufficientCycles
;proxy 会被冻结而非删除,后续充值后可恢复
控制台 proxy 的充值来自引擎余额,因此繁忙的 proxy 会缩短引擎的续航,但绝不会动用引擎应付给其节点的钱。
应用自身的 canister 没有上述任何一种余额:它们按设计持有 0 cycles,且无法充值。引擎 canister 上显示 "0 cycles" 是正常的(见
cloud-engine-canisters
陷阱 5)。

Code that runs on the engine

在引擎上运行的代码

A cloud engine runs on a
CloudEngine
subnet
with protocol-level call rules that differ from normal Application subnets: engine canisters hold 0 cycles and must never attach cycles to any call, cross-subnet calls must be bounded-wait, HTTPS outcalls are made directly and free, and cycle-bearing cross-subnet targets (exchange-rate XRC, threshold ECDSA/Schnorr, vetKD) go through the engine's funded console proxy canister. Before writing or debugging any canister code that will run on the engine, load the
cloud-engine-canisters
skill — it has the rules, the proxy interface, and the pitfalls.
云引擎运行在
CloudEngine
子网
上,其协议级调用规则与普通 Application 子网不同:引擎 canister 持有 0 cycles,且绝不要给任何调用附加 cycles,跨子网调用必须使用 bounded-wait,HTTPS 出站调用直接发起且免费,而携带 cycles 的跨子网目标(汇率 XRC、threshold ECDSA/Schnorr、vetKD)则要通过引擎有资金的 console proxy canister。在编写或调试任何将在引擎上运行的 canister 代码之前,先加载
cloud-engine-canisters
skill——其中包含这些规则、proxy 接口和陷阱。

Common Pitfalls

常见陷阱

  1. Sign-in not completed. Running
    icp identity link web …
    but not finishing the Internet Identity sign-in in the browser leaves the CLI unlinked; later commands fail with authorization errors. Re-run and wait for the user to confirm the browser flow finished. If no browser ever opened, the command is stalled at the "Press Enter to log in" prompt — relaunch with a piped newline,
    printf '\n' | icp identity link web …
    , never
    < /dev/null
    (see Step 1). If the CLI runs in a remote sandbox, re-running can never complete — see Pitfall 10 and the delegation handoff in Step 1.0.
  2. Wrong or missing
    --app
    domain.
    Any domain other than the console host, or no
    --app
    at all, derives a different principal, and the engine rejects the deploy as not authorized. Relink with the exact domain (Step 1). If the deploy is rejected as unauthorized after linking with the default
    --app opencloud.org
    , ask the user for the exact URL they sign in with and relink with its host.
  3. Guessing the subnet id. Never invent it: the deploy fails or targets the wrong subnet. It is on the engine's Settings page in the console; ask the user.
  4. Deploying with the anonymous identity. The default local identity is anonymous and is not the engine admin. You must link and
    icp identity default <your-identity-name>
    first.
  5. Using
    dfx
    .
    This ecosystem uses
    icp
    , never
    dfx
    . The correct sequence is
    icp identity link web <name> --app <console-domain>
    (Step 1), then
    icp deploy -e ic --subnet <subnet-id>
    (Step 3). See the
    icp-cli
    skill.
  6. Skipping the app metadata. Without
    __META_PROJECT
    (Step 2), the canisters still deploy and work but render as bare, unnamed principal rows in the console. Setting
    __META_*
    is what produces a named app with labelled canisters and an "Open" button.
  7. Wrong
    __META_MAIN_CANISTER
    value.
    It is matched as the exact string
    "true"
    . A boolean,
    "True"
    , or marking more than one canister means no (or the wrong) "Open" button. Mark exactly one entry-point canister.
  8. Inventing an icon variable. The icon variable is
    __META_ICON_PATH
    (a path resolved against
    __META_BASE_URL
    ). Do not guess
    __META_ICON
    ,
    __META_LOGO
    , or
    __META_ICON_LINK
    — they are ignored, so the icon silently never appears.
  9. Icon set on the wrong canister, or without a base URL. The icon is read only from the main canister and needs both
    __META_BASE_URL
    (a valid absolute
    https://
    URL) and
    __META_ICON_PATH
    . Setting the icon path on a side canister, omitting the base URL, or giving a non-https /
    data:
    base means no icon renders. (The "Open" button still works — it falls back to the main canister's gateway URL — so a bad base URL costs the icon and the custom Open URL, not the button.)
  10. Assuming the browser and CLI share localhost.
    icp identity link web
    returns the delegation to
    127.0.0.1:<port>
    on the CLI host. If the CLI runs in a remote sandbox while the user's browser is on a different machine, the sign-in never completes and later commands fail with authorization errors — no amount of re-running the link fixes it. With the ICP MCP tools, use the ICP MCP route instead. Without them, see Step 1.0: prefer a local session, where the browser and CLI share a loopback, or the ICP MCP connector, and use the delegation handoff (
    icp identity delegation request
    /
    sign
    /
    use
    ) only when the user has neither option. Ask before you build in the sandbox, not after.
  11. Expecting the delegation handoff to fix a missing network. The handoff moves signing authority, not connectivity —
    icp deploy
    still needs the network from the shell that runs it. If the CLI shell has no network at all (a sandboxed device bridge: DNS blocked, HTTPS fails), no
    icp
    network command can run there, link or deploy. Do not offer to "do the rest" from that shell and do not tunnel — hand the user one script for their real terminal (see "No-network CLI host" in Step 1.0), where the normal link flow works because terminal and browser share a loopback.
  12. Build timestamps in wasm metadata. Metadata is baked into the wasm and must be deterministic — a build time (
    $(date)
    ) changes every build even with identical source, breaking reproducibility and changing the module hash on every deploy. The deterministic alternative is the last commit's date,
    service:git:updated_at
    =
    $(git log -1 --format=%cI)
    — a property of the source tree, not the build. The deploy time itself comes from the canister history recorded by the network, never from metadata.
  13. Git metadata substitutions in a non-git project. Outside a git repository,
    $(git rev-parse HEAD)
    does not fail the build — it silently bakes garbage:
    service:git:sha
    becomes the literal
    +dirty
    and
    service:git:origin
    comes out empty. Check for a git repo first (
    git rev-parse HEAD
    succeeds); if there is none, set only
    service:version
    with an explicit value (or
    git init
    and commit before deploying, if version control is wanted anyway).
  14. Letting an engine app collect sign-ins before pinning a derivation origin. Internet Identity principals are per-origin, so adding a custom domain later turns every existing user into a stranger at the new address — and the fix cannot be applied retroactively without orphaning the accounts already made under the old origin. On the first deploy of any app that uses II, set
    derivationOrigin
    to the address of the canister that serves the frontend, built from its canister id (
    https://<frontend-canister-id>.icp.net
    ), even when that is currently the app's only origin. Do not copy
    __META_BASE_URL
    : it is allowed to point at a custom domain, and a custom domain is exactly what must not become the derivation origin. See the
    user-sign-in
    skill for the
    .well-known/ii-alternative-origins
    half.
  15. Trying to deploy or fund the console proxy from the CLI or an API. There is no
    icp
    command for it, and the console endpoints behind the buttons authenticate with a browser-session cookie from the Internet Identity login (no token auth), so an agent cannot drive them. Only the engine's owner can deploy one. Hand the user the console steps (engine → Integrations → Proxy canisters → Deploy a proxy) and wait for the proxy canister id. It needs no funding step: it is paid from the engine's balance. An agent can do the whole self-deployed-proxy path unattended, but that is a different canister with different authorization (Step 5).
  16. Deploying a self-deployed proxy onto the engine's subnet. Reusing Step 3's
    --subnet <engine-subnet-id>
    puts the proxy on the
    CloudEngine
    subnet, where it holds 0 cycles and may not send cycle-bearing messages either, so it cannot do the one thing a proxy is for. Omit
    --subnet
    so it lands on a normal Application subnet.
  17. Expecting a self-deployed proxy to accept calls from engine canisters. It authorizes controllers only. An engine canister calling it gets
    UnauthorizedUser
    until that canister's principal is added with
    icp canister settings update <proxy> --add-controller <canister-id> -e ic
    , and again for every canister added later. The console proxy authorizes every canister on the engine's subnet instead, which is why it is the right one for app code.
  18. Deleting a proxy that a signing app derives keys from. The delete button sends the unspent cycles back to the engine's balance, which makes it look like a tidy-up. It is not: threshold keys are derived from the proxy's own principal, so deleting it (or repointing the app at another proxy) changes every Bitcoin/Ethereum address the app owns and strands any funds at the old ones. See
    cloud-engine-canisters
    for the derivation rules before touching a proxy that an app already signs with.
  19. Confusing the balances. "The canister is out of cycles" means something different for each: an engine canister holds 0 cycles by design and cannot be topped up, the engine's balance running low is fixed with Add funds on its Billing page, and
    InsufficientCycles
    from a relayed call is the proxy's balance (for a console proxy, which refills from the engine's balance, that again means funding the engine). Establish which one before topping anything up, and note that the engine's balance running out deletes the engine.
  20. Deploying a proxy-dependent app without the proxy id. An app that signs, derives vetKeys, reads exchange rates or calls the Bitcoin API or EVM/SOL RPC deploys fine with a placeholder, a guessed id or an id from another engine, then fails on its first proxied call (
    UnauthorizedUser
    , or keys and addresses that belong to someone else's proxy). Ask for the id before deploying (What You Need, item 3). If the engine has none, the owner deploys one from the console (Step 5); never stand in a self-deployed proxy for it.
  21. Picking the wrong route. In a sandbox (a web or mobile chat, or a cloud coding session) that has the ICP MCP tools, asking the user to switch to a local session, or trying
    icp identity link web
    or the delegation handoff, wastes a round trip the connector makes unnecessary: use the ICP MCP route. The reverse holds too: in a local session, link the CLI and deploy with it even when the connector is also available, because the CLI can upload an asset canister's files and the connector cannot.
  22. Assuming the connector signs as the console principal. Internet Identity principals are per-origin, and at the engine the connector signs as the principal derived for the engine's platform domain. It is not the user's console principal and not a CLI identity, so a
    proxy
    call answers
    UnauthorizedUser
    until that principal is an engine member, even for the engine's owner. Read it with
    get_app_principal
    and hand the user the invite link (M3); you cannot add it yourself. A
    canister_update_call
    without
    derivation_origin
    gets the same answer for a different reason: it runs anonymously, so pass the derivation origin
    open_app
    returned on every call.
  23. A Questions-only connector session. With the Questions only access level, reads work and every state-changing call is rejected by the network,
    create_canister
    and
    install_code
    included. This is not an engine permission problem, so the invite link does not fix it. Ask the user to reconnect with Actions & questions (M0).
  24. Calling the management canister directly, or confusing the two proxies. The connector refuses calls to
    aaaaa-aa
    ; deploys go through the engine-operator's
    proxy
    method (M5). That method is not the chain-key proxy canister of Step 5, and the console proxy canister cannot create or install canisters: it relays only chain-key, Bitcoin and exchange-rate / RPC services.
  25. Creating a canister without listing the engine-operator as a controller.
    create_canister
    through
    proxy
    always adds you, but the operator only when you list it in
    settings.controllers
    . Without it,
    proxy
    can no longer reach the canister (no install, no settings), and the owner cannot remove it with
    deleteCanisters
    either. List the operator in the create call (M5, step 1).
  26. Textual Candid in
    proxy
    's
    args
    .
    args
    is a
    blob
    holding the binary Candid encoding of the management method's argument (bytes starting with
    DIDL
    ), and
    result
    comes back the same way. Passing the textual
    (record { … })
    as
    args
    makes the management canister fail to decode the argument. Encode it with a Candid library first (M5).
  27. Expecting the connector to finish a deploy that needs calls into the new canister. The connector calls only canisters an app declares, and the engine's manifest declares only its operator. It can install your wasm through
    proxy
    , but it cannot call the canister you installed, so it cannot upload an asset canister's files. Ship configuration in the init argument or environment variables, or use the CLI route for such an app.
  28. Serving a custom domain from certified-assets older than 0.4.3. For each app canister with a custom domain, the engine writes
    /.well-known/ic-domains
    (the HTTP gateway needs it to serve the domain) and
    /.well-known/ii-alternative-origins
    (Internet Identity needs it to accept the domain). It writes them with certified-assets'
    upload_asset
    , which arrived in 0.4.3. On an older canister the console warns that the engine can't write these files, and the domain does not work. Pin
    @dfinity/static-site@v0.4.3
    or newer. To fix an app that is already deployed, bump the recipe and run
    icp deploy -e ic
    . If the sync then stops with
    assets canister version mismatch
    , run
    icp canister install <frontend> --mode upgrade -e ic
    (v0.4.x to v0.4.3 is a patch, so the state stays), then
    icp deploy -e ic
    again. From v0.3.x the bump is breaking: see the
    static-site
    skill, pitfall 11. The engine replaces whatever the app ships at these two paths, so do not build them into
    dir
    . List both in a
    _preserve
    file at the root of
    dir
    : without it, every deploy deletes them until the engine writes them again (within 10 minutes).
  1. 登录未完成。 运行了
    icp identity link web …
    但没有在浏览器中完成 Internet Identity 登录,CLI 就仍处于未关联状态;后续命令会因授权错误失败。重新运行并等待用户确认浏览器流程已完成。如果浏览器从未打开,说明命令停在 "Press Enter to log in" 提示——用管道换行重新启动:
    printf '\n' | icp identity link web …
    ,绝不要用
    < /dev/null
    (见步骤 1)。如果 CLI 运行在远程沙箱中,重跑永远无法完成——见陷阱 10 以及步骤 1.0 中的委派交接。
  2. --app
    域名错误或缺失。
    任何不是控制台主机名的域名,或完全省略
    --app
    ,都会派生出不同的 principal,引擎会以未授权拒绝部署。用精确域名重新关联(步骤 1)。如果用默认的
    --app opencloud.org
    关联后部署仍被拒绝为未授权,请向用户询问其登录时使用的准确 URL,并用其主机名重新关联。
  3. 猜测子网 id。 绝不要臆造:部署会失败或指向错误的子网。它在控制台的引擎 Settings 页面上;请询问用户。
  4. 使用匿名身份部署。 默认本地身份是 anonymous,并非引擎管理员。你必须先关联并执行
    icp identity default <your-identity-name>
    。
  5. 使用
    dfx
    。
    这个生态使用
    icp
    ,绝不用
    dfx
    。正确顺序是
    icp identity link web <name> --app <console-domain>
    (步骤 1),然后
    icp deploy -e ic --subnet <subnet-id>
    (步骤 3)。见
    icp-cli
    skill。
  6. 跳过应用元数据。 没有
    __META_PROJECT
    (步骤 2)时,canister 仍能部署并工作,但在控制台中显示为无名 principal 行。设置
    __META_*
    才是产生具名应用、标签化 canister 和 "Open" 按钮的关键。
  7. __META_MAIN_CANISTER
    值错误。
    它按精确字符串
    "true"
    匹配。布尔值、
    "True"
    ,或标记多个 canister,都会导致没有(或错误的)"Open" 按钮。请只标记一个入口 canister。
  8. 臆造图标变量。 图标变量是
    __META_ICON_PATH
    (一个基于
    __META_BASE_URL
    解析的路径)。不要猜测
    __META_ICON
    、
    __META_LOGO
    或
    __META_ICON_LINK
    ——它们会被忽略,图标将静默永不出现。
  9. 图标设在错误的 canister 上,或缺少 base URL。 图标只从 main canister 读取,并且需要 两者皆备:
    __META_BASE_URL
    (有效的绝对
    https://
    URL)和
    __META_ICON_PATH
    。把图标路径设在附属 canister 上、省略 base URL,或给出非 https /
    data:
    的 base,都会导致图标不渲染。("Open" 按钮仍然可用——它会回退到 main canister 的网关 URL——所以错误的 base URL 损失的是图标和自定义 Open URL,而不是按钮。)
  10. 假设浏览器与 CLI 共享 localhost。
    icp identity link web
    会把委派返回到 CLI 主机上的
    127.0.0.1:<port>
    。如果 CLI 运行在远程沙箱而用户浏览器在另一台机器上,登录永远无法完成,后续命令会因授权错误失败——重跑关联多少次都无济于事。有 ICP MCP 工具时,请改用 ICP MCP 路径。没有时见步骤 1.0:优先选择本地会话(浏览器与 CLI 共享 loopback),或 ICP MCP 连接器;只有在用户两者都没有时才使用委派交接(
    icp identity delegation request
    /
    sign
    /
    use
    )。要在沙箱中构建之前询问,而不是之后。
  11. 指望委派交接能解决网络缺失。 交接转移的是签名权限,不是连通性——
    icp deploy
    仍需要运行它的 shell 具备网络。如果 CLI shell 完全没有网络(沙箱设备 bridge:DNS 被阻断、HTTPS 失败),任何
    icp
    网络命令都无法在那里运行,无论关联还是部署。不要提议"在那之后把剩下的做完",也不要打隧道——交给用户一个脚本在其真实终端中运行(见步骤 1.0 中的"无网络 CLI 主机"),在那里正常关联流程可用,因为终端与浏览器共享 loopback。
  12. 在 wasm 元数据中放入构建时间戳。 元数据会烘焙进 wasm,必须是确定性的——构建时间(
    $(date)
    )每次构建都会变化,即使源码相同也会破坏可复现性,并导致每次部署 module hash 都变化。确定性的替代方案是最后一次提交的日期,
    service:git:updated_at
    =
    $(git log -1 --format=%cI)
    ——它是源码树的属性而非构建的属性。真正的部署时间来自网络记录的 canister 历史,绝不会来自元数据。
  13. 在非 Git 项目中做 git 元数据替换。 在 git 仓库之外,
    $(git rev-parse HEAD)
    不会让构建失败——它会悄悄烘焙垃圾:
    service:git:sha
    变成字面量
    +dirty
    ,
    service:git:origin
    为空。先检查是否存在 git 仓库(
    git rev-parse HEAD
    能成功);如果没有,只设置带明确值的
    service:version
    (或先
    git init
    并提交再部署,如果确实需要版本控制)。
  14. 让引擎应用在固定派生源之前收集登录。 Internet Identity principal 是按源区分的,因此日后添加自定义域名会把每个已有用户在新地址上变成陌生人——而且该修复无法事后应用,否则会孤立旧源下已创建的账户。任何使用 II 的应用首次部署时,把
    derivationOrigin
    设为提供前端的那个 canister 的地址,由 canister id 构造(
    https://<frontend-canister-id>.icp.net
    ),即使目前它是应用唯一的源。不要照抄
    __META_BASE_URL
    :它被允许指向自定义域名,而自定义域名正是绝不能成为派生源的东西。关于
    .well-known/ii-alternative-origins
    那一半,见
    user-sign-in
    skill。
  15. 试图从 CLI 或 API 部署或给控制台 proxy 充值。 没有对应的
    icp
    命令,且按钮背后的控制台端点用 Internet Identity 登录产生的浏览器会话 cookie 认证(无 token 认证),因此 Agent 无法驱动它们。只有引擎的所有者才能部署。请把控制台步骤交给用户(engine → Integrations → Proxy canisters → Deploy a proxy)并等待 proxy canister id。它不需要充值步骤:它从引擎余额支付。Agent 可以全程无人值守地完成自行部署 proxy 的路径,但那是另一个 canister,授权方式也不同(步骤 5)。
  16. 把自行部署的 proxy 部署到引擎的子网上。 复用步骤 3 的
    --subnet <engine-subnet-id>
    会把 proxy 放到
    CloudEngine
    子网,在那里它持有 0 cycles,也不能发送携带 cycles 的消息,因此无法完成 proxy 唯一该做的事。省略
    --subnet
    ,让它落在普通 Application 子网上。
  17. 期望自行部署的 proxy 接受来自引擎 canister 的调用。 它只授权 controller。在用
    icp canister settings update <proxy> --add-controller <canister-id> -e ic
    把该 canister 的 principal 添加为 controller 之前,引擎 canister 调用它会得到
    UnauthorizedUser
    ;之后每新增一个 canister 都要再来一次。控制台 proxy 则授权引擎子网上的每个 canister,这才是它适合应用代码的原因。
  18. 删除签名应用派生密钥所依赖的 proxy。 删除按钮把未支取的 cycles 退回引擎余额,看起来像一次整洁清理。其实不是:阈值密钥是从 proxy 自身的 principal 派生的,所以删除它(或把应用重新指向另一个 proxy)会改变应用拥有的每一个 Bitcoin/Ethereum 地址,并把旧地址上的资金困住。在动一个应用已经用于签名的 proxy 之前,先阅读
    cloud-engine-canisters
    中的派生规则。
  19. 混淆各种余额。 "canister 没有 cycles 了"在不同场景下含义不同:引擎 canister 按设计持有 0 cycles 且无法充值;引擎的余额不足应通过其 Billing 页面的 Add funds 解决;而转发调用返回的
    InsufficientCycles
    指的是 proxy 的余额(对于从引擎余额充值的控制台 proxy 而言,这同样意味着要给引擎充值)。在给任何东西充值之前先确认是哪一个,并注意引擎余额耗尽会删除引擎。
  20. 部署依赖 proxy 的应用却没有 proxy id。 一个签名、派生 vetKey、读取汇率或调用 Bitcoin API 或 EVM/SOL RPC 的应用,用占位符、猜测的 id 或来自其他引擎的 id 都能部署成功,但在第一次代理调用时失败(
    UnauthorizedUser
    ,或密钥与地址属于别人的 proxy)。部署前索取 id("你需要什么"第 3 项)。如果引擎没有,所有者从控制台部署一个(步骤 5);绝不要用自行部署的 proxy 顶替。
  21. 选错路径。 在拥有 ICP MCP 工具的沙箱(网页或移动端聊天,或云端编码会话)中,让用户切换到本地会话、或尝试
    icp identity link web
    或委派交接,都会白白多绕一圈,而连接器本可省去这些:请使用 ICP MCP 路径。反过来也一样:在本地会话中,即使连接器也可用,也应关联 CLI 并用它部署,因为 CLI 能上传 asset canister 的文件,而连接器不能。
  22. 假设连接器以控制台 principal 签名。 Internet Identity principal 是按源区分的,在引擎处连接器以针对引擎平台域名派生的 principal 签名。它既不是用户的控制台 principal,也不是 CLI 身份,因此在你把该 principal 加入引擎成员之前,
    proxy
    调用都会返回
    UnauthorizedUser
    ,即使你是引擎所有者。用
    get_app_principal
    读取它,并把邀请链接交给用户(M3);你无法自行添加。不带
    derivation_origin
    的
    canister_update_call
    会因另一个原因得到同样的答案:它以匿名方式运行,所以每次调用都要传入
    open_app
    返回的 derivation origin。
  23. 连接器会话仅有 Questions-only 权限。 在 Questions only 访问级别下,读取可用,所有改变状态的调用都会被网络拒绝,包括
    create_canister
    和
    install_code
    。这不是引擎权限问题,邀请链接也解决不了。请让用户以 Actions & questions 重新连接(M0)。
  24. 直接调用管理 canister,或混淆两种 proxy。 连接器拒绝对
    aaaaa-aa
    的调用;部署要走 engine-operator 的
    proxy
    方法(M5)。该方法不是步骤 5 的链上密钥 proxy canister,而控制台 proxy canister 既不能创建也不能安装 canister:它只转发链上密钥、Bitcoin 以及汇率 / RPC 服务。
  25. 创建 canister 时未把 engine-operator 列为 controller。 通过
    proxy
    执行
    create_canister
    总会把你加上,但只有当你在
    settings.controllers
    中列出 operator 时才会加上它。少了它,
    proxy
    就再也无法触达该 canister(不能安装代码、不能改设置),所有者也无法用
    deleteCanisters
    删除它。在创建调用中列出 operator(M5,步骤 1)。
  26. 在
    proxy
    的
    args
    中使用文本形式的 Candid。
    args
    是保存管理方法参数二进制 Candid 编码的
    blob
    (以
    DIDL
    开头的字节),
    result
    也以同样形式返回。把文本形式的
    (record { … })
    作为
    args
    传入,会让管理 canister 无法解码参数。请先用 Candid 库编码(M5)。
  27. 期望连接器完成一个需要对新建 canister 进行调用的部署。 连接器只能调用应用声明过的 canister,而引擎清单只声明了它的 operator。它能通过
    proxy
    安装你的 wasm,但无法调用你安装的 canister,因此无法上传 asset canister 的文件。请在 init 参数或环境变量中传入配置,或对这类应用改用 CLI 路径。
  28. 用早于 0.4.3 的 certified-assets 提供自定义域名。 对于每个带自定义域名的应用 canister,引擎会写入
    /.well-known/ic-domains
    (HTTP 网关需要它才能提供该域名)和
    /.well-known/ii-alternative-origins
    (Internet Identity 需要它才能接受该域名)。它通过 certified-assets 的
    upload_asset
    写入这些文件,而该功能在 0.4.3 才出现。在更老的 canister 上,控制台会警告引擎无法写入这些文件,域名也不可用。请固定使用
    @dfinity/static-site@v0.4.3
    或更新版本。要修复已部署的应用,提升 recipe 版本并运行
    icp deploy -e ic
    。如果同步随后以
    assets canister version mismatch
    停止,运行
    icp canister install <frontend> --mode upgrade -e ic
    (v0.4.x 到 v0.4.3 是补丁版本,状态保留),然后再次运行
    icp deploy -e ic
    。从 v0.3.x 升级则是破坏性变更:见
    static-site
    skill 陷阱 11。引擎会替换应用在这两个路径上提供的任何内容,所以不要把它们构建进
    dir
    。请在
    dir
    根目录的
    _preserve
    文件中列出两者:没有它,每次部署都会删除它们,直到引擎再次写入(10 分钟内)。

Additional References

附加参考

  • Load
    cloud-engine-canisters
    for the call rules for code that runs on the engine: never attach cycles, bounded-wait cross-subnet calls, direct HTTPS outcalls, and the console proxy for cycle-bearing cross-subnet targets (XRC, threshold signing, vetKD). Load it before writing or debugging engine canister code.
  • Load
    icp-cli
    for general icp CLI usage (
    icp.yaml
    , recipes, environments, bindings, identities). Load it for anything beyond this cloud-engine deploy flow — in particular when the project does not build or package yet.
  • Load
    user-sign-in
    for details of the Internet Identity sign-in that Step 1 triggers in the browser.
  • Load
    service-discoverability
    for the
    /.well-known/ic-architecture
    manifest that decides which canisters the ICP MCP connector may call, including how an app you deployed can declare its own canisters, and the operator terms that publishing it accepts.
  • ICP MCP connector setup (ChatGPT plugin, Claude, custom connector URL): https://mcp.internetcomputer.org/.
  • Load
    vetkeys
    for what vetKD is and how VetKeys are used, once a proxy is in place: its call code targets a normal subnet, so see
    cloud-engine-canisters
    for the proxied form an engine needs.
  • Load
    cycles-management
    for cycles on ordinary (non-engine) canisters: balances, freezing thresholds, and ICP-to-cycles conversion via the CMC.
  • 加载
    cloud-engine-canisters
    获取在引擎上运行代码的调用规则:绝不附加 cycles、bounded-wait 跨子网调用、直接 HTTPS 出站调用,以及面向携带 cycles 的跨子网目标(XRC、threshold 签名、vetKD)使用控制台 proxy。在编写或调试引擎 canister 代码之前先加载它。
  • 加载
    icp-cli
    获取 icp CLI 的通用用法(
    icp.yaml
    、recipes、environments、bindings、identities)。除本云引擎部署流程之外的内容都要加载它——尤其是项目还无法构建或打包时。
  • 加载
    user-sign-in
    获取步骤 1 在浏览器中触发的 Internet Identity 登录细节。
  • 加载
    service-discoverability
    获取决定 ICP MCP 连接器可调用哪些 canister 的
    /.well-known/ic-architecture
    清单,包括你部署的应用如何声明自己的 canister,以及发布该清单所接受的 operator 条款。
  • ICP MCP 连接器设置(ChatGPT 插件、Claude、自定义连接器 URL):https://mcp.internetcomputer.org/。
  • 加载
    vetkeys
    了解 vetKD 是什么以及 VetKeys 如何使用(proxy 就位之后):其调用代码面向普通子网,因此引擎所需的形式请见
    cloud-engine-canisters
    。
  • 加载
    cycles-management
    了解普通(非引擎)canister 上的 cycles:余额、冻结阈值,以及通过 CMC 的 ICP 转 cycles。