deploy-to-cloud-engine
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDeploy 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 ). 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.
https://opencloud.orgThis 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 (, recipes, environments, bindings, identities), load the skill.
icp.yamlicp-cli**云引擎(cloud engine)是用户自有的一段 Internet Computer 容量,通过 Web 控制台进行管理(默认为 )。每个引擎运行在单个子网(subnet)**上。本 skill 负责把一个已经可以构建的项目部署到该引擎上,无论你是从编码 Agent 还是 AI 聊天应用发起的。
https://opencloud.org本 skill 仅覆盖与云引擎相关的步骤:选择部署方式、以引擎可接受的身份登录,以及把 canister 放到引擎上。关于 CLI 的其他所有内容(、recipes、environments、bindings、identities),请加载 skill。
icp.yamlicp-cliChoose 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 (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".
https://mcp.internetcomputer.org/mcp - icp CLI. , then
icp identity link web. The full toolchain (recipes, asset canisters,icp deploy --subnet), but the sign-in completes only whenicp.yamlruns on the same machine as the user's browser. See Steps 1 to 4.icp
Decide like this:
- You run in a sandbox and the ICP MCP tools are available to you (,
open_app,get_app_principal, …) → 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 attemptcanister_update_callor the delegation handoff there.icp identity link web - 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 command you are unsure of, run (e.g. , ) to confirm the command and flags exist. Do not infer flags. Authoritative reference: https://cli.internetcomputer.org/llms.txt
icpicp <subcommand> --helpicp identity link --helpicp deploy --help进入引擎有两条路。在写任何代码之前先选定一条:路径决定了部署如何登录以及你能发布什么。
- ICP MCP 连接器。 DFINITY 为 Internet Computer 提供的官方 MCP server。它在 ChatGPT 中原生可用(DFINITY Stiftung 提供的插件 Internet Computer (ICP)),在 Claude 中也可用;任何支持 MCP 的应用都可以在 添加自定义连接器(设置步骤见 https://mcp.internetcomputer.org/)。它以用户在聊天应用中授权的 Internet Identity 会话身份签名,因此无需本地 CLI、无需你机器上的浏览器、也无需 loopback。你通过引擎的 engine-operator canister 部署 wasm。参见 "ICP MCP 路径"。
https://mcp.internetcomputer.org/mcp - icp CLI。 ,然后
icp identity link web。提供完整工具链(recipes、asset canisters、icp deploy --subnet),但只有当icp.yaml与用户浏览器在同一台机器上运行时登录才能完成。参见 步骤 1 到 4。icp
判断方式如下:
- 你运行在沙箱中且可使用 ICP MCP 工具(、
open_app、get_app_principal等)→ 使用 ICP MCP 路径。 沙箱指 Web 或移动端聊天(ChatGPT、网页版或手机版 Claude)或云端编码会话。不要要求用户切换到本地会话,也不要在那里尝试canister_update_call或委派交接。icp identity link web - 其他情况 → 使用 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 以用户身份完成登录后再构建:不要把登录拖到部署时再做。
在运行任何你不确定的 命令之前,先执行 (例如 、)以确认命令和参数存在。不要推测参数。权威参考:https://cli.internetcomputer.org/llms.txt
icpicp <subcommand> --helpicp identity link --helpicp deploy --helpWhat You Need
你需要什么
Two values, and a third for some apps. Look for them first in or earlier in the conversation. One has a default; the others you must ask for:
icp.yaml- Console origin — the URL the user signs in to their cloud engine console with. Defaults to (the main OpenCloud console). Its host is the
https://opencloud.orgvalue 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:--app- Say: "I'll link the CLI against , the default console. If you sign in to your engine console at a different URL, tell me now."
https://opencloud.org - Only use a different origin when the user names one — never substitute another URL on your own; the domain determines the derived principal (see Pitfall 2).
--app - On the ICP MCP route there is no ; the console origin is where you look the engine up and where the owner confirms access (M1, M3).
--app
- Say: "I'll link the CLI against
- Subnet id (CLI route): the subnet the engine deploys to, required by . 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:
icp deploy --subnet- 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.
- 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 variable, or a call to a
PROXY_CANISTER_IDmethod). 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:proxy- 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- 控制台源(console origin)—— 用户登录其云引擎控制台所用的 URL。默认为 (OpenCloud 主控制台)。它的主机名就是步骤 1 中的
https://opencloud.org值,因此关联的 CLI 身份会派生出与管理该引擎相同的 principal。使用默认值,但应明确告知并给用户机会在关联前覆盖:--app- 说明:"我会针对 这个默认控制台关联 CLI。如果你登录引擎控制台用的是另一个 URL,请现在告诉我。"
https://opencloud.org - 只有在用户明确指明时才使用其他源——绝不要自行替换成另一个 URL;域名决定了派生的 principal(见陷阱 2)。
--app - 在 ICP MCP 路径上没有 ;控制台源用于查找引擎以及让所有者确认访问权限(M1、M3)。
--app
- 说明:"我会针对
- 子网 id(CLI 路径):引擎部署到的子网,必需。没有默认值;绝不要猜测。用户可以在控制台的引擎 Settings 页面找到它(在引擎标识符下方),或从控制台的命令面板中复制。如果缺失,必须询问,且未获得答案前不要继续:
icp deploy --subnet- 询问:"你的引擎的 subnet id 是多少?在控制台的引擎 Settings 页面上。"
- 在 ICP MCP 路径上你需要的是引擎 id(M1)。operator 会在它自己的引擎上创建 canister,因此没有需要传入的子网。
- Proxy canister id:仅当应用调用 threshold ECDSA/Schnorr、vetKD、汇率 canister、Bitcoin API 或 EVM/SOL RPC canister 时需要(查找 变量,或对
PROXY_CANISTER_ID方法的调用)。没有默认值,你无法自行创建控制台 proxy,自行部署的 proxy 也不能替代它(步骤 5)。如果缺失,部署前必须询问:proxy- 询问:"这个应用需要你引擎的 proxy canister。如果引擎已有一个,请把它的 id 发给我(engine → Integrations → Proxy canisters)。如果没有,引擎所有者可以在那里通过 Deploy a proxy 部署一个:它从引擎余额付费,无需信用卡。然后把 id 发给我。"
记录这些值,以免在本次会话中重复询问。
Prerequisites
前置条件
- CLI route: on
icp— see the$PATHskill to install. Verify withicp-cli(this skill's commands are verified against 0.3.0 and 1.0.2). If the installed version differs, confirm the flag set withicp --versionbefore running — flags have changed across major versions.icp <cmd> --help - A project that already builds. If it does not build or package yet, set that up first (see the skill), then return here.
icp-cli - 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: stores its data under
icp. If the shell cannot write there (~/Library/Application Support/org.dfinity.icp-cli/from macOS TCC, e.g. when commands run through a bridge), redirect the data to an unprotected path for the session —Operation not permitted— and keep that sameHOME=/tmp/icp-home icp …on every subsequentHOMEcommand, or the later commands will not see the linked identity.icp - ICP MCP route: the connector's tools in your tool list, connected with Actions & questions access (M0).
- CLI 路径:中有
$PATH——参见icpskill 进行安装。用icp-cli验证(本 skill 的命令已在 0.3.0 和 1.0.2 上验证)。如果安装的版本不同,先用icp --version确认参数集合再运行——大版本之间参数已有变化。icp <cmd> --help - 一个已经可以构建的项目。如果还无法构建或打包,先按 skill 配置好,然后回到这里。
icp-cli - 还没有项目,也没有项目描述? 在写任何代码或创建任何文件之前,先询问用户要构建什么:"你想构建什么应用?" 不要自行挑选示例应用(留言簿、计数器、待办清单)。只说"构建并部署一个应用"的提示意味着需要询问,而不是让你替用户选择。
- CLI 路径,macOS:把数据存放在
icp下。如果 shell 无法写入那里(来自 macOS TCC 的~/Library/Application Support/org.dfinity.icp-cli/,例如命令通过 bridge 运行时),把数据重定向到本次会话中不受保护的路径——Operation not permitted——并在之后每一条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 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 .
icpicp.yamlThe 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(见"先选择部署路径")。无需 CLI、无需 loopback、无需委派交接。步骤 1 和 3 属于 CLI 路径,不适用。步骤 2(为应用命名)和步骤 5(面向链上密钥服务的 proxy canister)仍然适用:M6 说明了如何在没有 的情况下设置相应变量。
icpicp.yamlengine-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 . The steps are at https://mcp.internetcomputer.org/.
https://mcp.internetcomputer.org/mcpOn 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 and 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.
create_canisterinstall_code如果工具缺失且用户的应用可以添加 MCP 连接器,请让他们添加:在 ChatGPT 中是 DFINITY Stiftung 提供的插件 Internet Computer (ICP),在 Claude 中是其连接器,在其他支持 MCP 的应用中是在 添加自定义连接器。步骤见 https://mcp.internetcomputer.org/。
https://mcp.internetcomputer.org/mcp连接时,用户使用 Internet Identity 登录,选择会话时长和访问级别。部署需要 Actions & questions。若只有 Questions only,读取操作可用,但网络会拒绝所有改变状态的调用,因此 和 会失败。如果更新调用因此被拒绝,请让用户以 Actions & questions 重新连接。会话过期是设计使然,之后重新连接是正常的。
create_canisterinstall_codeM1. Find the engine
M1. 查找引擎
You need three values: the engine's id, its engine-operator canister id (), and its platform domain (, like ).
engine_operator_idplatform_domain<engine-name>--<slug>.opencloud.org- Ask the user for the engine id. It is in the console URL () and on the engine's Settings page.
/console/engines/<engine-id>/… - on the console origin (
open_app) lists the engine registry canister. Read its publichttps://opencloud.orgquery withgetEngineViews; the record carries(vec { "<engine-id>" })andengine_operator_id. Signed as the user, itsplatform_domainquery returns the engines they own, with the same fields.listVisibleEngines
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 host instead, which works as soon as is set. answers once the platform domain serves: give the user that address from then on.
https://<engine_operator_id>.icp.netengine_operator_idGET https://icp.net/custom-domains/v1/<platform_domain>registration_statusregistered你需要三个值:引擎的 id、其 engine-operator canister id()以及其 平台域名(,形如 )。
engine_operator_idplatform_domain<engine-name>--<slug>.opencloud.org- 向用户索取引擎 id。它在控制台 URL()中以及引擎的 Settings 页面上。
/console/engines/<engine-id>/… - 在控制台源()上执行
https://opencloud.org会列出引擎注册表 canister。用open_app读取其公开的(vec { "<engine-id>" })查询;该记录包含getEngineViews和engine_operator_id。以用户身份签名调用其platform_domain查询会返回用户拥有的引擎,字段相同。listVisibleEngines
新建或重命名的引擎,其平台域名注册大约需要十分钟。在此之前不要打开或访问它:查找不到记录的查询结果可能被缓存为"缺失"长达 30 分钟,域名上线后仍会持续对你失败。请改用其 operator 的 主机访问引擎,该地址在 设置好之后立即可用。 在平台域名开始提供服务后返回 :此后请把该地址提供给用户。
https://<engine_operator_id>.icp.netengine_operator_idGET https://icp.net/custom-domains/v1/<platform_domain>registration_statusregisteredM2. Open the engine and read the operator's guide
M2. 打开引擎并阅读 operator 指南
- on
open_app. The engine-operator publishes the engine'shttps://<engine_operator_id>.icp.netmanifest, so it comes back as/.well-known/ic-architecture; that is what lets the connector call it. The connector refuses calls to any canister an app does not declare. Check that the[declared]it returns isderivation_origin. If it is the icp.net origin, the operator does not hold the engine's domain yet: wait a minute andhttps://<platform_domain>again before M3, or the principal you get there changes later.open_app - on the operator, and read its section "Creating a canister and installing a wasm".
get_canister_api_doc - on the operator, and check that its service has a
get_canister_candidmethod. 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.proxy
- 在 上执行
https://<engine_operator_id>.icp.net。engine-operator 会发布引擎的open_app清单,因此它返回为/.well-known/ic-architecture;正是这一点让连接器可以调用它。连接器会拒绝对应用未声明的任意 canister 的调用。检查它返回的[declared]是否为derivation_origin。如果是 icp.net 源,说明 operator 尚未持有该引擎的域名:等待一分钟后再次https://<platform_domain>再进行 M3,否则你在那里获得的 principal 之后会发生变化。open_app - 对 operator 执行 ,阅读其中 "Creating a canister and installing a wasm" 一节。
get_canister_api_doc - 对 operator 执行 ,检查其 service 中是否有
get_canister_candid方法。如果没有,说明该引擎运行的仍是 ICP MCP 路径出现之前的 engine-operator:告知用户并改用 CLI 路径。proxy
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 ). 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.
/.well-known/ii-derivation-origin-
with the
get_app_principalthatderivation_originreturned in M2 gives you that principal,open_app. 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 withPand keep passing the same one, since each account is a different principal.account -
Check whether it is a member: the operator's publicquery with
getRole. Any role is enough, because every role has the(record { principal_id = opt principal "<P>" })permission thatCreateCanisterneeds.proxy -
If the role is null, you cannot addyourself. 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:
Phttps://opencloud.org/console/engines/<engine-id>/team?modal=invite-member&principal=<P>&role=developerUse their console origin instead ofif it differs.https://opencloud.orgis enough to deploy: do not ask fordeveloper. Wait for them to confirm, then repeat step 2.admin
Renaming the engine changes its platform domain, and with it : the new principal needs the invite again.
PInternet Identity 按源派生 principal。在引擎处,连接器以针对引擎 平台域名(即其 中的源)派生的 principal 签名。这不是用户登录控制台时使用的 principal,也不是针对控制台源关联的 CLI 身份。因此即使用户拥有该引擎,引擎也还不认识它。
/.well-known/ii-derivation-origin-
用 M2 中返回的
open_app执行derivation_origin,即可得到该 principalget_app_principal。其回复还会说明会话是否仅为查询模式:如果是,请停止并让用户以 Actions & questions 重新连接(M0)。如果用户在引擎处有多个账户,请用P选定其中一个并始终传入同一个,因为每个账户都是不同的 principal。account -
检查它是否为成员:调用 operator 的公开查询,参数为
getRole。任何角色都足够,因为每个角色都具备(record { principal_id = opt principal "<P>" })所需的proxy权限。CreateCanister -
如果角色为 null,你无法自行添加。把下面的链接给用户(引擎所有者或引擎管理员)。它会打开该引擎的邀请对话框并预填授权内容,用户只需登录并确认:
Phttps://opencloud.org/console/engines/<engine-id>/team?modal=invite-member&principal=<P>&role=developer如果你的控制台源不是,请改用你自己的控制台源。https://opencloud.org已足够完成部署:不要要求developer。等待用户确认,然后重复步骤 2。admin
重命名引擎会改变其平台域名, 也会随之改变:新的 principal 需要再次邀请。
PM4. 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, needs no sign-in (see
icp build), and its recipe bakes in Step 2's version metadata as usual. Or use a prebuilticp-cli/.wasmthe user attaches. Canister code follows the engine's call rules: load.wasm.gz.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),其 recipe 会照常嵌入步骤 2 的版本元数据。也可以使用用户附带的预构建icp-cli/.wasm。canister 代码需遵循引擎的调用规则:加载.wasm.gz。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 (, ). Pass configuration in the init argument (), or as environment variables (M6). If the app needs an asset upload, it needs the CLI route: tell the user.
@dfinity/static-site@dfinity/asset-canisterarg连接器只能调用应用声明过的 canister,而引擎清单只声明了它的 operator。因此你新建的 canister 只能通过 operator 转发的管理调用触达(M5):连接器无法调用新 canister 自身的方法。这排除了任何需要在安装后进行调用的需求,例如上传 asset canister 的文件(、)。请通过 init 参数()或环境变量(M6)传入配置。如果应用需要上传静态资源,它需要走 CLI 路径:告知用户。
@dfinity/static-site@dfinity/asset-canisterargM5. Create the canister and install the wasm through the operator's proxy
proxyM5. 通过 operator 的 proxy
创建 canister 并安装 wasm
proxyThe connector may not call the IC management canister () directly. The engine-operator's 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.
aaaaa-aaproxyEach step is one with the engine-operator, , the app URL and the derivation origin that returned in M2 (plus the same as in M3, if you chose one). Always pass : without it the call runs anonymously, and answers . The are:
canister_update_callcanister_idmethod = "proxy"app_urlderivation_originopen_appaccountderivation_originproxyUnauthorizedUserargscandid
(record {
canister_id = principal "aaaaa-aa";
method = "<management method name>";
args = blob "<the method's argument, Candid-encoded>";
cycles = 0;
})argsDIDLblob "…"\xxvariant { Ok = record { result = blob "…" } }result-
Create., and
method = "create_canister"encodes:argscandid(record { settings = opt record { controllers = opt vec { principal "<engine-operator-id>" } } })List the engine-operator as a controller. You () are added as a controller automatically, but without the operatorPcan never reach the canister again: no install, no settings, and noproxyfor the owner either. If the code reads an environment variable when it initializes (such asdeleteCanisters), addPROXY_CANISTER_IDto theseenvironment_variablesnow: it must be in place before step 2 (see M6).settingsdecodes toresult.(record { canister_id : principal }) -
Install., and
method = "install_code"encodes:argscandid(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; })is the binary-Candid init argument;argpasses none.DIDL\00\00decodes toresult.() -
Replace the code later. The same call withkeeps the stable memory;
mode = variant { upgrade = null }wipes all state. A canister built with enhanced orthogonal persistence (current Motoko) rejectsvariant { reinstall }: upgrade it withupgrade = null. Usevariant { upgrade = opt record { wasm_memory_persistence = opt variant { keep } } }only for such a build: the IC rejects it when the new module lacks thekeepcustom section (a Rust canister, or classical-persistence Motoko), so those keepenhanced-orthogonal-persistence. (The operator's guide says other canisters ignoreupgrade = null; the IC interface spec says otherwise, and the spec wins.)keep -
A module over about 2 MB (the single-message limit) goes up with, then installs with
upload_chunk.install_chunked_code
The operator relays only , , , , , , , and , and only on canisters that list you as a controller. Any other method, the operator itself, and protected canisters come back as with a , as does any call on a canister while an on it is in flight: retry once it completes. is ignored, since the engine charges nothing. means the call was not signed by a member: check that you passed , then go back to M3.
create_canistercanister_statusupdate_settingsinstall_codeupload_chunkclear_chunk_storeinstall_chunked_codestart_canisterstop_canisterErrCallFailedreasonproxyupdate_settingscyclesErrUnauthorizedUserderivation_origin连接器可能无法直接调用 IC 管理 canister()。engine-operator 的 方法会为你代为调用,调用者身份即为你签名所用的身份。不要把它与步骤 5 的 proxy canister 混淆:后者为你的应用代码转发链上密钥调用,与部署无关。
aaaaa-aaproxy每一步都是一次 ,其中 为 engine-operator,, 为应用 URL, 为 M2 中 返回的 derivation origin(如果选择了某个 ,还要带上 M3 中的同一个 )。务必传入 :不传则调用以匿名方式运行, 会返回 。 为:
canister_update_callcanister_idmethod = "proxy"app_urlderivation_originopen_appaccountaccountderivation_originproxyUnauthorizedUserargscandid
(record {
canister_id = principal "aaaaa-aa";
method = "<management method name>";
args = blob "<the method's argument, Candid-encoded>";
cycles = 0;
})argsDIDL\xxblob "…"variant { Ok = record { result = blob "…" } }result-
创建。,
method = "create_canister"编码为:argscandid(record { settings = opt record { controllers = opt vec { principal "<engine-operator-id>" } } })把 engine-operator 列为 controller。你()会被自动添加为 controller,但如果不把 operator 加入,P就再也无法触达该 canister:既不能安装代码、不能改设置,所有者也无法proxy。如果代码在初始化时读取环境变量(如deleteCanisters),现在就把PROXY_CANISTER_ID加入这些environment_variables:它必须在步骤 2 之前就位(见 M6)。settings解码为result。(record { canister_id : principal }) -
安装。,
method = "install_code"编码为:argscandid(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; })是二进制 Candid 的 init 参数;arg表示不传参。DIDL\00\00解码为result。() -
之后替换代码。 同样的调用,改用可保留稳定内存;
mode = variant { upgrade = null }会清除所有状态。使用增强型正交持久化(当前 Motoko)构建的 canister 会拒绝variant { reinstall }:请改用upgrade = null来升级。只有这类构建才使用variant { upgrade = opt record { wasm_memory_persistence = opt variant { keep } } }:当新 module 缺少keep自定义段时(Rust canister,或使用经典持久化的 Motoko),IC 会拒绝它,因此那些构建仍使用enhanced-orthogonal-persistence。(operator 指南说其他 canister 会忽略upgrade = null;IC 接口规范说法相反,以规范为准。)keep -
超过约 2 MB 的 module(单条消息上限)需先用上传,再用
upload_chunk安装。install_chunked_code
operator 只转发 、、、、、、、 和 ,且只作用于把你列为 controller 的 canister。其他方法、operator 自身以及受保护的 canister 都会返回 并附带 ;在某个 canister 的 正在进行时对其发起 调用同样如此:待其完成后重试一次。 会被忽略,因为引擎不收费。 表示该调用不是以成员身份签名:检查是否传入了 ,然后回到 M3。
create_canistercanister_statusupdate_settingsinstall_codeupload_chunkclear_chunk_storeinstall_chunked_codestart_canisterstop_canisterErrCallFailedreasonupdate_settingsproxycyclesErrUnauthorizedUserderivation_originM6. Name the app, and pass configuration
M6. 为应用命名并传入配置
Step 2's variables, and from Step 5, are canister environment variables. With no to carry them, you set them yourself, and when matters:
__META_*PROXY_CANISTER_IDicp.yaml- A variable the code reads at init or upgrade (, a key name, any configuration) must be set before the
PROXY_CANISTER_IDthat reads it. Otherwise init sees it missing, and traps or bakes in a fallback that a later upgrade does not undo. Put it ininstall_code'screate_canister(M5, step 1), or set it withsettingsbetween steps 1 and 2. Before an upgrade or reinstall that should see a new value, set that value first.update_settings - Display-only metadata () is read by the console, not by your code, so it can follow at any time.
__META_*needs the canister id, so it comes after step 1 anyway.__META_BASE_URL
Either way it is through , with encoding:
update_settingsproxyargscandid
(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 的 变量和步骤 5 的 都是 canister 环境变量。没有 承载它们时,需要自行设置,且时机很重要:
__META_*PROXY_CANISTER_IDicp.yaml- 代码在 init 或 upgrade 时读取的变量(、某个 key 名、任何配置)必须在读取它的
PROXY_CANISTER_ID之前设置。否则 init 会发现它缺失,从而 trap,或固化一个后续 upgrade 无法撤销的兜底值。把它放进install_code的create_canister(M5,步骤 1),或在步骤 1 与步骤 2 之间用settings设置。在应看到新值的 upgrade 或 reinstall 之前,先设置该值。update_settings - 仅用于展示的元数据()由控制台读取,而非你的代码,因此可以随时设置。
__META_*需要 canister id,所以本来也要在步骤 1 之后才设置。__META_BASE_URL
两种方式都是通过 执行 , 编码为:
proxyupdate_settingsargscandid
(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. 验证
- through
canister_status, withproxyencodingargs, shows(record { canister_id = principal "<canister id>" })and the installedstatus = variant { running }.module_hash - A canister that serves HTTP is reachable at . On an all-in-one engine it is under the engine's own domain instead: the operator's guide names which.
https://<canister-id>.icp.net - 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 可通过 访问。在 all-in-one 引擎上,它位于引擎自己的域名之下:operator 指南会说明是哪一个。
https://<canister-id>.icp.net - 该 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 webhttp://127.0.0.1:<port>- 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 bound to the sandbox, the user's browser resolves
callback=http://127.0.0.1:<port>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.127.0.0.1 - 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 ) → no
/tmpnetwork command can run there — not the link, and noticpeither. 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.icp deploy
When in doubt, probe before linking: failing (or DNS not resolving) from the CLI shell means the no-network case.
curl -sI https://<console-origin>Never present a sandbox 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 : as of icp-cli 1.0.2 it has none (confirm with ).
127.0.0.1icp identity link webicp identity link web --helpicp identity link webhttp://127.0.0.1:<port>- CLI 与浏览器在同一台机器上且有网络(本地开发,或用户自己机器上的终端集成 Agent)→ 使用下面正常的关联流程。
- CLI 位于远程或隔离的沙箱中且有网络(Agent 运行在云上;用户浏览器在另一台机器上)→ 正常流程无法工作:登录 URL 携带绑定到沙箱的 ,用户的浏览器会把
callback=http://127.0.0.1:<port>解析到它自己的机器,委派永远送不到 CLI。之后命令就会因授权错误失败。如果你有 ICP MCP 工具,请停下并改用 ICP MCP 路径。否则请让用户切换到本地会话,或添加 ICP MCP 连接器(见"先选择部署路径")。只有当用户两者都无法做到时,才使用下面的委派交接。127.0.0.1 - 完全没有网络的 CLI shell(例如用户自己机器上的沙箱设备 bridge:DNS 被阻断、HTTPS 请求失败、只能写入 )→ 任何
/tmp网络命令都无法在那里运行——既不能关联,也不能icp。委派交接也无济于事:它只转移签名权限,不转移网络访问能力。不要重试、不要打隧道、不要做代理。请准备好项目并交给用户一个脚本,在他们的真实终端中运行——见下面的"无网络 CLI 主机"。icp deploy
拿不准时先探测再关联:从 CLI shell 执行 失败(或 DNS 无法解析)即属于无网络情况。
curl -sI https://<console-origin>绝不要把沙箱的 URL 呈现给用户、让他在自己浏览器里打开——从他的机器无法访问。也不要臆造 的 headless 参数:截至 icp-cli 1.0.2 它没有该参数(用 确认)。
127.0.0.1icp identity link webicp identity link web --helpDelegation handoff (CLI host and browser on different machines)
委派交接(CLI 主机与浏览器在不同机器上)
icp identity delegationicpicp identity delegation --helpicp-
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 defaultfails in a headless sandbox, retry with--storage keyring.)--storage plaintext -
On the user's machine — the user links there if not already linked (— the normal flow works locally), saves the PEM to a file, and signs a delegation to it:
icp identity link web <local-name> --app <console-domain>bashicp identity delegation sign --identity <local-name> --key-pem session-key.pem --duration 8h > delegation.jsontakes e.g.--duration,30m,8h; optionally1drestricts the delegation. The user sends--canisters <ids>back. Ifdelegation.jsonfails withsign, the local web session has lapsed — rundelegation for identity <name> has expired or will expire within 5 minutes(the normal browser flow, which works locally) and retry.icp identity reauth <local-name> -
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 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.
delegation.jsonicp identity delegationicpicp identity delegation --helpicp-
在 CLI 主机(沙箱)上 —— 用新的会话密钥创建待定身份:bash
icp identity delegation request <your-identity-name>它会把会话 public 密钥以 PEM 形式打印到 stdout。把该 PEM 块交给用户。(如果默认的在无头沙箱中失败,请改用--storage keyring重试。)--storage plaintext -
在用户机器上 —— 如果尚未关联则先关联(——正常流程在本地可用),把 PEM 保存到文件,并对它签署一份委派:
icp identity link web <local-name> --app <console-domain>bashicp identity delegation sign --identity <local-name> --key-pem session-key.pem --duration 8h > delegation.json可取如--duration、30m、8h;可选的1d可限制委派范围。用户把--canisters <ids>发回。如果delegation.json失败并提示sign,说明本地 web 会话已失效——运行delegation for identity <name> has expired or will expire within 5 minutes(正常浏览器流程,本地可用)后重试。icp identity reauth <local-name> -
在 CLI 主机上 —— 完成待定身份并激活它:bash
icp identity delegation use <your-identity-name> --from-json delegation.json icp identity default <your-identity-name> icp identity principal # 必须打印用户的控制台 principal
把 视为有时效的凭据:持有沙箱会话密钥的人可以在其过期前以用户的控制台 principal 签名。让时长保持较短,过期后重新执行交接。
delegation.jsonNo-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:
-
Get the built project into a directory the user's terminal can reach.
-
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> -
Ask the user to run it in their terminal, complete the Internet Identity sign-in when the browser opens, and paste the output back.
-
Verify from the pasted output (canister ids, frontend URL) and continue — a re-deploy for the Step 2variables goes through the same script.
__META_*
如果 CLI shell 无法访问网络,用户的真实终端就是部署机器——而且因为他们的终端与浏览器在那里共享 loopback,正常的关联流程可以工作;无需委派交接。你的工作转为准备:
-
把已构建的项目放到用户终端可访问的目录中。
-
在项目根目录写一个脚本,执行全部需要网络的步骤——按需改造以下模板(填入真实的身份名、控制台域名和子网 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> -
请用户在他们的终端中运行它,在浏览器打开时完成 Internet Identity 登录,并把输出粘贴回来。
-
根据粘贴的输出进行验证(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 identityThe list does not show which console (if any) an identity was linked against — that cannot be determined from the CLI. Decide like this:
- Only (or plain local identities) listed — no web-linked identity exists; run the link command below.
anonymous - 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 — is any local label, not a fixed value (do not hardcode something like ); reuse the same name in every command below:
<your-identity-name>my-engine-adminbash
icp identity link web <your-identity-name> --app <console-domain>-
is the host of the console origin, with no scheme, port or path:
<console-domain>for the default console,opencloud.orgforbeta.opencloud.org. The console derives its principal from the host it serves, so this is the domain to name. Do not take it fromhttps://beta.opencloud.org: that file serves the ICP MCP route and can name another host./.well-known/ii-derivation-origin -
Never omit. Without it, Internet Identity derives the principal for
--app, which is not your console, and the engine rejects every deploy as unauthorized.cli.id.ai -
Do not usefor the OpenCloud console. It reaches the same principal, but through the console's own
--auth <console-origin>page, so the user signs in on two screens instead of one. Use/cli(no--auth <console-origin>) only when the user says their console signs in with its own Internet Identity rather than--app, as a test deployment does.id.ai -
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— the bare EOF does not satisfy the prompt, and the command sits on "Press Enter to log in" indefinitely with no browser ever opening./dev/null -
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 theskill, Pitfall 1.
agent-web-identity -
must be the exact console host, e.g.
--app. Another domain derives a different principal, and the engine will reject the deploy as unauthorized.opencloud.org -
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 判断。按如下方式决定:
- 只列出 (或普通本地身份)—— 不存在 web 关联身份;执行下面的关联命令。
anonymous - 存在用户认得出的引擎身份(按名称或 principal)—— 把它设为当前身份(见下)并跳到步骤 2。
- 不确定 —— 询问用户,或直接用新名称重新关联;再次关联既便宜又安全。
关联时运行以下命令,名称由用户自选—— 是任意本地标签,不是固定值(不要硬编码类似 的东西);在下面所有命令中复用同一个名称:
<your-identity-name>my-engine-adminbash
icp identity link web <your-identity-name> --app <console-domain>-
是控制台源的主机名,不带 scheme、端口或路径:默认控制台为
<console-domain>,opencloud.org为https://beta.opencloud.org。控制台从它所服务的主机名派生 principal,所以要指定的就是这个域名。不要从beta.opencloud.org取:那个文件服务于 ICP MCP 路径,可能指向另一个主机。/.well-known/ii-derivation-origin -
绝不要省略。省略后 Internet Identity 会派生
--app的 principal,那不是你的控制台,引擎会把每次部署都当作未授权而拒绝。cli.id.ai -
对 OpenCloud 控制台不要使用。它能到达同一个 principal,但会走控制台自己的
--auth <console-origin>页面,导致用户在两个页面而不是一个页面登录。只有当用户表示其控制台使用自己的 Internet Identity(而非/cli)登录时,才使用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 从重定向——单纯的 EOF 无法满足提示,命令会永远停在 "Press Enter to log in",浏览器永远不会打开。/dev/null -
按下 Enter 后会打开一个浏览器标签页。由用户在那里完成 Internet Identity 登录。继续之前等待他们确认——你无法替他们完成登录。
-
首次使用时,id.ai 可能停在 "CLI access disabled" 页面。这是预期的首次运行,不是错误。告诉用户在 Internet Identity 设置中为其身份开启 CLI access,然后从头重新运行关联命令:旧的登录 URL 是单次有效的。参见skill,陷阱 1。
agent-web-identity -
必须是精确的控制台主机名,例如
--app。其他域名会派生出不同的 principal,引擎会以未授权拒绝部署。opencloud.org -
这是每台机器一次性的步骤。
然后把它设为当前身份并验证:
bash
icp identity default <your-identity-name>
icp identity default # 打印当前身份名称
icp identity principal # 打印部署将用于签名的 principalStep 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:
- — 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_PROJECT - — the per-canister display label (e.g.
__META_NAME,Backend).Frontend - — the literal string
__META_MAIN_CANISTERon exactly one canister (the entry point, usually the frontend/asset canister). This marks the app's main canister: the console reads"true"and__META_BASE_URLonly from it, and the "Open" button targets it.__META_ICON_PATH - — an absolute
__META_BASE_URLURL, set on the main canister (e.g. the frontend canister's URLhttps://, or a custom domain). When present and valid, it is the URL the "Open" button opens; when absent or nothttps://<frontend-canister-id>.icp.net, the "Open" button falls back to the main canister's gateway URL. It is also the base thathttpsresolves against.__META_ICON_PATH - — the path to the app icon, resolved against
__META_ICON_PATHto form the icon the console renders (e.g.__META_BASE_URL→/favicon.svg). Set it on the main canister, alongsidehttps://<base>/favicon.svg.__META_BASE_URL
The icon and "Open" link are read only from the main canister (the one marked ) — / on any other canister are ignored.
__META_MAIN_CANISTER: "true"__META_BASE_URL__META_ICON_PATHOn the ICP MCP route there is no project config: set the same variables with (M6). On the CLI route, set them under each canister's — this is valid alongside a recipe. With per-canister files:
update_settingssettings.environment_variablescanister.yamlyaml
undefined默认情况下,通过 CLI 部署的 canister 会在引擎控制台的 Your apps and services 页面上显示为只有 principal id 的裸行。一组 canister 环境变量可以让控制台把它们归组为一个具名应用,并显示可读的每个 canister 标签、"Open" 按钮和图标。在你的项目配置中设置一次:
- —— 应用名称。共享相同值的 canister 会被归组为一个具名应用,因此请在该应用的每个 canister 上设置相同的值。
__META_PROJECT - —— 每个 canister 的显示标签(例如
__META_NAME、Backend)。Frontend - —— 在且仅在一个 canister 上设置字面字符串
__META_MAIN_CANISTER(入口点,通常是前端/asset canister)。它标记应用的 main canister:控制台只从它读取"true"和__META_BASE_URL,"Open" 按钮也指向它。__META_ICON_PATH - —— 一个绝对的
__META_BASE_URLURL,设置在 main canister 上(例如前端 canister 的 URLhttps://,或自定义域名)。存在且有效时,它就是 "Open" 按钮打开的 URL;缺失或不是https://<frontend-canister-id>.icp.net时,"Open" 按钮回退到 main canister 的网关 URL。它同时也是https解析时的基准。__META_ICON_PATH - —— 应用图标的路径,会基于
__META_ICON_PATH解析成控制台渲染的图标(例如__META_BASE_URL→/favicon.svg)。与https://<base>/favicon.svg一起设置在 main canister 上。__META_BASE_URL
图标和 "Open" 链接只从 main canister 读取(即标记 的那个)——其他任何 canister 上的 / 都会被忽略。
__META_MAIN_CANISTER: "true"__META_BASE_URL__META_ICON_PATH在 ICP MCP 路径上没有项目配置:用 设置同样的变量(M6)。在 CLI 路径上,在每个 canister 的 下设置——这与 recipe 并用也有效。使用每个 canister 的 文件时:
update_settingssettings.environment_variablescanister.yamlyaml
undefinedfrontend/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"
```yamlname: 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"
```yamlbackend/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:
```yamlname: 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 名称为键的映射:
```yamlicp.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.netThat is usually the canister you marked , 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 file Internet Identity fetches from that origin to validate the claim.
__META_MAIN_CANISTER: "true".well-known/ii-alternative-originsBuild the value from the canister id, not from . The two match only while 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.
__META_BASE_URL__META_BASE_URLDo 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 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.
derivationOriginFor the mechanics — the option and the file, including the entry the recipe needs — load the skill.
derivationOrigin.well-known/ii-alternative-origins_headers@dfinity/static-siteuser-sign-inCaffeine 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这通常就是你标记了 的 canister,但该标记只是控制台显示设置,并不能保证。如果你标记的是后端 canister,仍要从前端 canister 派生。后端 canister 不能作为派生源:浏览器永远不在它上面,而且它无法提供 Internet Identity 用于验证声明的 文件。
__META_MAIN_CANISTER: "true".well-known/ii-alternative-origins该值要从 canister id 构造,不要从 构造。只有当 仍指向 canister 地址时两者才一致。把它指向自定义域名是正常且受支持的(见上面的图标说明),此时两者就不同了。自定义域名正是那个绝不能成为派生源的值。
__META_BASE_URL__META_BASE_URL要在应用还没有用户之前做这件事,而不是之后。 已经收集过登录的域名无法再被改为派生源,否则会孤立在该域名下创建的所有账户。如果应用将来可能使用自定义域名,那么首次部署时即设置 ,即使当时 canister 地址是唯一的源——此时毫无成本,事后也无法在不丢账户的情况下补做。
derivationOrigin具体机制—— 选项和 文件,包括 recipe 所需的 条目——请加载 skill。
derivationOrigin.well-known/ii-alternative-origins@dfinity/static-site_headersuser-sign-inCaffeine 应用是例外: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 list under the recipe ; 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 v4.1.0 and v5.0.0 on icp-cli 1.0.2.)
metadataconfiguration$(…)@dfinity/motokoGit project (check first: succeeds):
git rev-parse HEADyaml
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 ( becomes the literal , comes out empty). Use only an explicit version, and bump it on each subsequent deploy:
service:git:sha+dirtyservice:git:originyaml
metadata:
- name: service:version
value: "1.0.0"Notes:
- Use these exact names (,
service:git:sha,service:git:origin,service:git:updated_at) — they are the agreed convention the console will read; differently named entries will not be picked up.service:version - Prefer command results over literals where possible: on the sha flags uncommitted changes, so a deploy is traceable to its exact source state.
+dirty - Values must be deterministic for a given source tree: sha, origin, the last commit's date, a version string. Never embed a build time () or other build-time-varying values. The commit date (
$(date)) 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.%cI - If the project has no (or no version field), the fallback
package.jsonapplies; replace it with the project's real versioning scheme when one exists.1.0.0 - The sections are injected as , 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:private.icp canister metadata <canister-name> service:git:sha -e ic
把构建来源信息嵌入每个 canister 的 wasm,让工具和控制台能显示当前运行的版本(控制台支持正在逐步推出;元数据已经可读——见下面的验证说明)。默认在每次部署时都添加——不要等用户提出。所有官方 recipe(motoko、rust、static-site、asset-canister、prebuilt)都接受 recipe 下的 列表;每个条目都会作为自定义段被烘焙进 wasm。值在构建时被插入 shell 命令,因此 命令替换可用。(已针对 icp-cli 1.0.2 上 v4.1.0 和 v5.0.0 进行真实构建验证。)
configurationmetadata$(…)@dfinity/motokoGit 项目(先检查: 能成功):
git rev-parse HEADyaml
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+dirtyservice:git:originyaml
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))是可以的,因为它是提交的属性而非构建的属性——但请注意它表示"代码最后修改时间"而不是"最后部署时间":部署旧提交会显示旧日期。真正的部署时间来自网络自动记录的 canister 历史。%cI - 如果项目没有 (或没有 version 字段),会使用兜底值
package.json;若项目已有自己的版本方案,请替换为真实方案。1.0.0 - 这些段以 注入,canister 的 controller(你,以及以你身份行动的控制台)可通过 read_state 读取——无需 canister 调用。部署后用已激活的关联身份验证:
icp:private。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>- targets mainnet (the engine runs on an IC subnet);
-e icpins the deploy to your engine's subnet. Confirm the exact flags with--subnet <subnet-id>before running if unsure.icp deploy --help - Deploying consumes capacity on the engine; make sure the engine has room.
Alternative: packaged upload. If the project is distributed as a built package and a direct is not available, the user can upload the bundle instead: engine → Your apps and services → Upload a bundle, which walks through uploading the 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.
.icpicp deploy.icp在项目根目录执行:
bash
icp deploy -e ic --subnet <subnet-id>- 指向 mainnet(引擎运行在一个 IC 子网上);
-e ic把部署固定到你的引擎的子网。不确定时先运行--subnet <subnet-id>确认确切参数。icp deploy --help - 部署会消耗引擎上的容量;请确保引擎有足够空间。
替代方案:打包上传。 如果项目以已构建的 包分发且无法直接 ,用户可以改为上传 bundle:engine → Your apps and services → Upload a bundle,该流程会引导上传 bundle。该页面的另一个按钮 Build with agents 汇总了其他方式:编码 Agent、Caffeine、本 skill 自动化的 CLI 指令,以及 OpenSaaS 提供的现成应用。
.icpicp deploy.icpStep 4 — Verify
步骤 4 —— 验证
- The output reports the deployed canister ids.
icp deploy - 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 name with their
__META_PROJECTlabels, and the main canister shows an "Open" button — instead of bare principal rows. With__META_NAME+__META_BASE_URLset, the app also shows its icon (allow for a short console cache delay).__META_ICON_PATH - 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.
- 的输出会报告已部署的 canister id。
icp deploy - canister 会出现在控制台的 Your apps and services 页面上;每个 canister 的详情视图提供 "Open in browser" 链接。
- 如果你在步骤 2 设置了元数据,canister 会以 名称归组,并带有各自的
__META_PROJECT标签,main canister 会显示 "Open" 按钮——而不是裸的 principal 行。设置了__META_NAME+__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 ). Everything else (the app's own execution, storage, messaging, and HTTPS outcalls) is free on an engine and needs no proxy at all.
cloud-engine-canistersThose 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 转发其他任何内容(确切列表见 )。其他一切(应用自身的执行、存储、消息传递和 HTTPS 出站调用)在引擎上都是免费的,完全不需要 proxy。
cloud-engine-canisters这些服务位于其他子网,并按调用收取 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 proxy | Self-deployed proxy | |
|---|---|---|
| Deployed by | The engine's owner, from the console | You, with |
| Authorized callers | Every canister on the engine's subnet (checked with the NNS registry), plus its controller | Controllers only |
| Your engine canisters may call it | Yes, automatically | Only after you add each one as a controller |
| What it relays for them | Only chain-key, Bitcoin and exchange-rate / RPC services (list in | Anything |
| Your CLI identity may call it | No (rejected as | Yes: you are a controller |
| Threshold-key derivation | Isolated per calling canister | No isolation |
| Funded with | The engine's balance, automatically (no card) | Cycles you hold ( |
- 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, canister-only management methods likeicp deploy --proxyorcanister_info) → your own proxy. The console proxy cannot serve this: it rejects ingress from any non-controller principal, and your CLI identity is not one.raw_rand
They are not substitutes, and they derive different keys: see the derivation warning in before switching an app from one to the other.
cloud-engine-canisters有两个不同的 canister 可以承担这个角色,选错会得到一个看起来正常却在第一次调用时失败的配置:
| 控制台 proxy | 自行部署的 proxy | |
|---|---|---|
| 部署方 | 引擎的所有者,通过控制台 | 你自己,使用 |
| 授权的调用者 | 引擎子网上的每个 canister(通过 NNS 注册表校验),以及它自己的 controller | 仅 controller |
| 你的引擎 canister 可以调用它 | 是,自动生效 | 需要你把每个都添加为 controller 之后 |
| 它为调用者转发什么 | 仅链上密钥、Bitcoin 以及汇率 / RPC 服务(列表见 | 任意内容 |
| 你的 CLI 身份可以调用它 | 否(被拒绝为 | 可以:你是它的 controller |
| 阈值密钥派生 | 按调用 canister 隔离 | 无隔离 |
| 资金来源 | 引擎的余额,自动充值(无需信用卡) | 你持有的 cycles( |
- 应用代码调用链上密钥服务 → 用控制台 proxy。 它能接纳你引擎上的 canister,无需逐个 canister 配置。
- 你在 CLI 中发起调用(、
icp canister call --proxy、仅限 canister 的管理方法如icp deploy --proxy或canister_info)→ 用你自己的 proxy。 控制台 proxy 无法胜任:它拒绝任何非 controller principal 的入口访问,而你的 CLI 身份不是 controller。raw_rand
二者不可互相替代,而且派生出不同的密钥:切换之前请先阅读 中的派生警告。
cloud-engine-canistersConsole 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 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:
icp- Open the engine in the console → Integrations in the engine's sidebar → the Proxy canisters card.
- 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.
- 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.
只有引擎的所有者才能部署,而且只能从控制台部署。没有对应的 命令,也没有任何 Agent 能调用的接口可以创建它:按钮背后的控制台端点依赖由 Internet Identity 登录产生的浏览器会话 cookie 认证。把下面的步骤交给用户,并等待 proxy canister id:
icp- 在控制台中打开引擎 → 引擎侧边栏中的 Integrations → Proxy canisters 卡片。
- 点击 Deploy a proxy,然后在对话框中点击 Deploy proxy。无需选择金额,也不会扣信用卡:proxy 会在普通 Application 子网上创建,从引擎余额支付,起始带有价值数美元的 cycles。
- 从卡片的表格中复制 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 (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.
update_settings应用在运行时需要该 id。请把它作为 canister 环境变量传入,而不是硬编码在源码中,这样同一份代码既能跑在本地 mock 上,也能跑在引擎上:
yaml
settings:
environment_variables:
PROXY_CANISTER_ID: "<proxy-canister-id>"在 ICP MCP 路径上,用 设置(M6)。在 canister 中按读取其他环境变量同样的方式读取它,并视其为永久配置:对于派生阈值密钥的应用,改动该值会改变应用拥有的每一个地址。
update_settingsSelf-deployed proxy: the CLI path
自行部署的 proxy:CLI 路径
For proxying your own calls. This one is the upstream , deployed from a template:
dfinity/proxy-canisterbash
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 balanceThen 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 subnet is useless: it holds 0 cycles and cannot send a cycle-bearing message either. Omit
CloudEngine(Step 3's engine-subnet flag is for your app, not for this) so it lands on a normal Application subnet.--subnet - It authorizes controllers only. For an engine canister to call it, that canister's principal must be added as a controller (), one call per canister, repeated whenever a canister is added. This is the maintenance burden the console proxy exists to remove.
icp canister settings update "$PROXY_ID" --add-controller <canister-id> -e ic - 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-canisterbash
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"有三件事必须做对:
- 不要把它部署到引擎的子网上。 位于 子网的 proxy 毫无用处:它持有 0 cycles,也无法发送携带 cycles 的消息。省略
CloudEngine(步骤 3 的引擎子网参数是给你的应用用的,不是给它用的),让它落在普通 Application 子网上。--subnet - 它只授权 controller。 若要让引擎 canister 调用它,该 canister 的 principal 必须被添加为 controller(),每个 canister 一次调用,每新增一个 canister 都要重复。这正是控制台 proxy 要消除的维护负担。
icp canister settings update "$PROXY_ID" --add-controller <canister-id> -e ic - 它不隔离密钥派生。 任何被授权的调用者都可以请求任意派生路径,且它产生的密钥与控制台 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:
| Balance | What it pays for | How it is funded | What happens when it empties |
|---|---|---|---|
| Engine balance | The engine itself (its nodes, day by day), and the top-ups of its console proxies | Add 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 out | The 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 balance | Only 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 | Relayed calls fail with |
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 , pitfall 5).
cloud-engine-canisters存在两种余额,它们的充值方式不同,而且应用自身的 canister 两种都没有。在引擎上"为 canister 充值"之前,先弄清楚指的是哪一种:
| 余额 | 用于支付什么 | 如何充值 | 耗尽时会发生什么 |
|---|---|---|---|
| 引擎余额 | 引擎自身(其节点,逐日消耗),以及其控制台 proxy 的充值 | 在引擎的 Billing 页面执行 Add funds(扣档案中的信用卡),以及在余额即将耗尽前约一周自动充值(同样扣信用卡) | 引擎被删除,其上的一切随之消失:不可逆,因此要严肃对待余额不足的警告。自动充值持续失败的引擎会停止运行,在款项到账后恢复 |
| Proxy cycles 余额 | 仅 proxy 转发的调用(签名、vetKD、XRC、Bitcoin API、EVM/SOL RPC) | 控制台 proxy 从引擎余额自行补充(步骤 5);自行部署的 proxy 使用 | 转发的调用失败并返回 |
控制台 proxy 的充值来自引擎余额,因此繁忙的 proxy 会缩短引擎的续航,但绝不会动用引擎应付给其节点的钱。
应用自身的 canister 没有上述任何一种余额:它们按设计持有 0 cycles,且无法充值。引擎 canister 上显示 "0 cycles" 是正常的(见 陷阱 5)。
cloud-engine-canistersCode that runs on the engine
在引擎上运行的代码
A cloud engine runs on a 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 skill — it has the rules, the proxy interface, and the pitfalls.
CloudEnginecloud-engine-canisters云引擎运行在 子网上,其协议级调用规则与普通 Application 子网不同:引擎 canister 持有 0 cycles,且绝不要给任何调用附加 cycles,跨子网调用必须使用 bounded-wait,HTTPS 出站调用直接发起且免费,而携带 cycles 的跨子网目标(汇率 XRC、threshold ECDSA/Schnorr、vetKD)则要通过引擎有资金的 console proxy canister。在编写或调试任何将在引擎上运行的 canister 代码之前,先加载 skill——其中包含这些规则、proxy 接口和陷阱。
CloudEnginecloud-engine-canistersCommon Pitfalls
常见陷阱
- Sign-in not completed. Running 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,
icp identity link web …, neverprintf '\n' | icp identity link web …(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.< /dev/null - Wrong or missing domain. Any domain other than the console host, or no
--appat 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, ask the user for the exact URL they sign in with and relink with its host.--app opencloud.org - 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.
- Deploying with the anonymous identity. The default local identity is anonymous and is not the engine admin. You must link and first.
icp identity default <your-identity-name> - Using . This ecosystem uses
dfx, nevericp. The correct sequence isdfx(Step 1), thenicp identity link web <name> --app <console-domain>(Step 3). See theicp deploy -e ic --subnet <subnet-id>skill.icp-cli - Skipping the app metadata. Without (Step 2), the canisters still deploy and work but render as bare, unnamed principal rows in the console. Setting
__META_PROJECTis what produces a named app with labelled canisters and an "Open" button.__META_* - Wrong value. It is matched as the exact string
__META_MAIN_CANISTER. A boolean,"true", or marking more than one canister means no (or the wrong) "Open" button. Mark exactly one entry-point canister."True" - Inventing an icon variable. The icon variable is (a path resolved against
__META_ICON_PATH). Do not guess__META_BASE_URL,__META_ICON, or__META_LOGO— they are ignored, so the icon silently never appears.__META_ICON_LINK - Icon set on the wrong canister, or without a base URL. The icon is read only from the main canister and needs both (a valid absolute
__META_BASE_URLURL) andhttps://. Setting the icon path on a side canister, omitting the base URL, or giving a non-https /__META_ICON_PATHbase 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.)data: - Assuming the browser and CLI share localhost. returns the delegation to
icp identity link webon 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 (127.0.0.1:<port>/icp identity delegation request/sign) only when the user has neither option. Ask before you build in the sandbox, not after.use - Expecting the delegation handoff to fix a missing network. The handoff moves signing authority, not connectivity — 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 deploynetwork 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.icp - Build timestamps in wasm metadata. Metadata is baked into the wasm and must be deterministic — a build time () 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,
$(date)=service:git:updated_at— 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.$(git log -1 --format=%cI) - Git metadata substitutions in a non-git project. Outside a git repository, does not fail the build — it silently bakes garbage:
$(git rev-parse HEAD)becomes the literalservice:git:shaand+dirtycomes out empty. Check for a git repo first (service:git:originsucceeds); if there is none, set onlygit rev-parse HEADwith an explicit value (orservice:versionand commit before deploying, if version control is wanted anyway).git init - 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 to the address of the canister that serves the frontend, built from its canister id (
derivationOrigin), even when that is currently the app's only origin. Do not copyhttps://<frontend-canister-id>.icp.net: it is allowed to point at a custom domain, and a custom domain is exactly what must not become the derivation origin. See the__META_BASE_URLskill for theuser-sign-inhalf..well-known/ii-alternative-origins - Trying to deploy or fund the console proxy from the CLI or an API. There is no 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).
icp - Deploying a self-deployed proxy onto the engine's subnet. Reusing Step 3's puts the proxy on the
--subnet <engine-subnet-id>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. OmitCloudEngineso it lands on a normal Application subnet.--subnet - Expecting a self-deployed proxy to accept calls from engine canisters. It authorizes controllers only. An engine canister calling it gets until that canister's principal is added with
UnauthorizedUser, 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.icp canister settings update <proxy> --add-controller <canister-id> -e ic - 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 for the derivation rules before touching a proxy that an app already signs with.
cloud-engine-canisters - 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 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.
InsufficientCycles - 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 (, 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.
UnauthorizedUser - 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 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.
icp identity link web - 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 call answers
proxyuntil that principal is an engine member, even for the engine's owner. Read it withUnauthorizedUserand hand the user the invite link (M3); you cannot add it yourself. Aget_app_principalwithoutcanister_update_callgets the same answer for a different reason: it runs anonymously, so pass the derivation originderivation_originreturned on every call.open_app - A Questions-only connector session. With the Questions only access level, reads work and every state-changing call is rejected by the network, and
create_canisterincluded. This is not an engine permission problem, so the invite link does not fix it. Ask the user to reconnect with Actions & questions (M0).install_code - Calling the management canister directly, or confusing the two proxies. The connector refuses calls to ; deploys go through the engine-operator's
aaaaa-aamethod (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.proxy - Creating a canister without listing the engine-operator as a controller. through
create_canisteralways adds you, but the operator only when you list it inproxy. Without it,settings.controllerscan no longer reach the canister (no install, no settings), and the owner cannot remove it withproxyeither. List the operator in the create call (M5, step 1).deleteCanisters - Textual Candid in 's
proxy.argsis aargsholding the binary Candid encoding of the management method's argument (bytes starting withblob), andDIDLcomes back the same way. Passing the textualresultas(record { … })makes the management canister fail to decode the argument. Encode it with a Candid library first (M5).args - 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 , 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.
proxy - Serving a custom domain from certified-assets older than 0.4.3. For each app canister with a custom domain, the engine writes (the HTTP gateway needs it to serve the domain) and
/.well-known/ic-domains(Internet Identity needs it to accept the domain). It writes them with certified-assets'/.well-known/ii-alternative-origins, 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. Pinupload_assetor newer. To fix an app that is already deployed, bump the recipe and run@dfinity/static-site@v0.4.3. If the sync then stops withicp deploy -e ic, runassets canister version mismatch(v0.4.x to v0.4.3 is a patch, so the state stays), thenicp canister install <frontend> --mode upgrade -e icagain. From v0.3.x the bump is breaking: see theicp deploy -e icskill, pitfall 11. The engine replaces whatever the app ships at these two paths, so do not build them intostatic-site. List both in adirfile at the root of_preserve: without it, every deploy deletes them until the engine writes them again (within 10 minutes).dir
- 登录未完成。 运行了 但没有在浏览器中完成 Internet Identity 登录,CLI 就仍处于未关联状态;后续命令会因授权错误失败。重新运行并等待用户确认浏览器流程已完成。如果浏览器从未打开,说明命令停在 "Press Enter to log in" 提示——用管道换行重新启动:
icp identity link web …,绝不要用printf '\n' | icp identity link web …(见步骤 1)。如果 CLI 运行在远程沙箱中,重跑永远无法完成——见陷阱 10 以及步骤 1.0 中的委派交接。< /dev/null - 域名错误或缺失。 任何不是控制台主机名的域名,或完全省略
--app,都会派生出不同的 principal,引擎会以未授权拒绝部署。用精确域名重新关联(步骤 1)。如果用默认的--app关联后部署仍被拒绝为未授权,请向用户询问其登录时使用的准确 URL,并用其主机名重新关联。--app opencloud.org - 猜测子网 id。 绝不要臆造:部署会失败或指向错误的子网。它在控制台的引擎 Settings 页面上;请询问用户。
- 使用匿名身份部署。 默认本地身份是 anonymous,并非引擎管理员。你必须先关联并执行 。
icp identity default <your-identity-name> - 使用 。 这个生态使用
dfx,绝不用icp。正确顺序是dfx(步骤 1),然后icp identity link web <name> --app <console-domain>(步骤 3)。见icp deploy -e ic --subnet <subnet-id>skill。icp-cli - 跳过应用元数据。 没有 (步骤 2)时,canister 仍能部署并工作,但在控制台中显示为无名 principal 行。设置
__META_PROJECT才是产生具名应用、标签化 canister 和 "Open" 按钮的关键。__META_* - 值错误。 它按精确字符串
__META_MAIN_CANISTER匹配。布尔值、"true",或标记多个 canister,都会导致没有(或错误的)"Open" 按钮。请只标记一个入口 canister。"True" - 臆造图标变量。 图标变量是 (一个基于
__META_ICON_PATH解析的路径)。不要猜测__META_BASE_URL、__META_ICON或__META_LOGO——它们会被忽略,图标将静默永不出现。__META_ICON_LINK - 图标设在错误的 canister 上,或缺少 base URL。 图标只从 main canister 读取,并且需要 两者皆备:(有效的绝对
__META_BASE_URLURL)和https://。把图标路径设在附属 canister 上、省略 base URL,或给出非 https /__META_ICON_PATH的 base,都会导致图标不渲染。("Open" 按钮仍然可用——它会回退到 main canister 的网关 URL——所以错误的 base URL 损失的是图标和自定义 Open URL,而不是按钮。)data: - 假设浏览器与 CLI 共享 localhost。 会把委派返回到 CLI 主机上的
icp identity link web。如果 CLI 运行在远程沙箱而用户浏览器在另一台机器上,登录永远无法完成,后续命令会因授权错误失败——重跑关联多少次都无济于事。有 ICP MCP 工具时,请改用 ICP MCP 路径。没有时见步骤 1.0:优先选择本地会话(浏览器与 CLI 共享 loopback),或 ICP MCP 连接器;只有在用户两者都没有时才使用委派交接(127.0.0.1:<port>/icp identity delegation request/sign)。要在沙箱中构建之前询问,而不是之后。use - 指望委派交接能解决网络缺失。 交接转移的是签名权限,不是连通性——仍需要运行它的 shell 具备网络。如果 CLI shell 完全没有网络(沙箱设备 bridge:DNS 被阻断、HTTPS 失败),任何
icp deploy网络命令都无法在那里运行,无论关联还是部署。不要提议"在那之后把剩下的做完",也不要打隧道——交给用户一个脚本在其真实终端中运行(见步骤 1.0 中的"无网络 CLI 主机"),在那里正常关联流程可用,因为终端与浏览器共享 loopback。icp - 在 wasm 元数据中放入构建时间戳。 元数据会烘焙进 wasm,必须是确定性的——构建时间()每次构建都会变化,即使源码相同也会破坏可复现性,并导致每次部署 module hash 都变化。确定性的替代方案是最后一次提交的日期,
$(date)=service:git:updated_at——它是源码树的属性而非构建的属性。真正的部署时间来自网络记录的 canister 历史,绝不会来自元数据。$(git log -1 --format=%cI) - 在非 Git 项目中做 git 元数据替换。 在 git 仓库之外,不会让构建失败——它会悄悄烘焙垃圾:
$(git rev-parse HEAD)变成字面量service:git:sha,+dirty为空。先检查是否存在 git 仓库(service:git:origin能成功);如果没有,只设置带明确值的git rev-parse HEAD(或先service:version并提交再部署,如果确实需要版本控制)。git init - 让引擎应用在固定派生源之前收集登录。 Internet Identity principal 是按源区分的,因此日后添加自定义域名会把每个已有用户在新地址上变成陌生人——而且该修复无法事后应用,否则会孤立旧源下已创建的账户。任何使用 II 的应用首次部署时,把 设为提供前端的那个 canister 的地址,由 canister id 构造(
derivationOrigin),即使目前它是应用唯一的源。不要照抄https://<frontend-canister-id>.icp.net:它被允许指向自定义域名,而自定义域名正是绝不能成为派生源的东西。关于__META_BASE_URL那一半,见.well-known/ii-alternative-originsskill。user-sign-in - 试图从 CLI 或 API 部署或给控制台 proxy 充值。 没有对应的 命令,且按钮背后的控制台端点用 Internet Identity 登录产生的浏览器会话 cookie 认证(无 token 认证),因此 Agent 无法驱动它们。只有引擎的所有者才能部署。请把控制台步骤交给用户(engine → Integrations → Proxy canisters → Deploy a proxy)并等待 proxy canister id。它不需要充值步骤:它从引擎余额支付。Agent 可以全程无人值守地完成自行部署 proxy 的路径,但那是另一个 canister,授权方式也不同(步骤 5)。
icp - 把自行部署的 proxy 部署到引擎的子网上。 复用步骤 3 的 会把 proxy 放到
--subnet <engine-subnet-id>子网,在那里它持有 0 cycles,也不能发送携带 cycles 的消息,因此无法完成 proxy 唯一该做的事。省略CloudEngine,让它落在普通 Application 子网上。--subnet - 期望自行部署的 proxy 接受来自引擎 canister 的调用。 它只授权 controller。在用 把该 canister 的 principal 添加为 controller 之前,引擎 canister 调用它会得到
icp canister settings update <proxy> --add-controller <canister-id> -e ic;之后每新增一个 canister 都要再来一次。控制台 proxy 则授权引擎子网上的每个 canister,这才是它适合应用代码的原因。UnauthorizedUser - 删除签名应用派生密钥所依赖的 proxy。 删除按钮把未支取的 cycles 退回引擎余额,看起来像一次整洁清理。其实不是:阈值密钥是从 proxy 自身的 principal 派生的,所以删除它(或把应用重新指向另一个 proxy)会改变应用拥有的每一个 Bitcoin/Ethereum 地址,并把旧地址上的资金困住。在动一个应用已经用于签名的 proxy 之前,先阅读 中的派生规则。
cloud-engine-canisters - 混淆各种余额。 "canister 没有 cycles 了"在不同场景下含义不同:引擎 canister 按设计持有 0 cycles 且无法充值;引擎的余额不足应通过其 Billing 页面的 Add funds 解决;而转发调用返回的 指的是 proxy 的余额(对于从引擎余额充值的控制台 proxy 而言,这同样意味着要给引擎充值)。在给任何东西充值之前先确认是哪一个,并注意引擎余额耗尽会删除引擎。
InsufficientCycles - 部署依赖 proxy 的应用却没有 proxy id。 一个签名、派生 vetKey、读取汇率或调用 Bitcoin API 或 EVM/SOL RPC 的应用,用占位符、猜测的 id 或来自其他引擎的 id 都能部署成功,但在第一次代理调用时失败(,或密钥与地址属于别人的 proxy)。部署前索取 id("你需要什么"第 3 项)。如果引擎没有,所有者从控制台部署一个(步骤 5);绝不要用自行部署的 proxy 顶替。
UnauthorizedUser - 选错路径。 在拥有 ICP MCP 工具的沙箱(网页或移动端聊天,或云端编码会话)中,让用户切换到本地会话、或尝试 或委派交接,都会白白多绕一圈,而连接器本可省去这些:请使用 ICP MCP 路径。反过来也一样:在本地会话中,即使连接器也可用,也应关联 CLI 并用它部署,因为 CLI 能上传 asset canister 的文件,而连接器不能。
icp identity link web - 假设连接器以控制台 principal 签名。 Internet Identity principal 是按源区分的,在引擎处连接器以针对引擎平台域名派生的 principal 签名。它既不是用户的控制台 principal,也不是 CLI 身份,因此在你把该 principal 加入引擎成员之前,调用都会返回
proxy,即使你是引擎所有者。用UnauthorizedUser读取它,并把邀请链接交给用户(M3);你无法自行添加。不带get_app_principal的derivation_origin会因另一个原因得到同样的答案:它以匿名方式运行,所以每次调用都要传入canister_update_call返回的 derivation origin。open_app - 连接器会话仅有 Questions-only 权限。 在 Questions only 访问级别下,读取可用,所有改变状态的调用都会被网络拒绝,包括 和
create_canister。这不是引擎权限问题,邀请链接也解决不了。请让用户以 Actions & questions 重新连接(M0)。install_code - 直接调用管理 canister,或混淆两种 proxy。 连接器拒绝对 的调用;部署要走 engine-operator 的
aaaaa-aa方法(M5)。该方法不是步骤 5 的链上密钥 proxy canister,而控制台 proxy canister 既不能创建也不能安装 canister:它只转发链上密钥、Bitcoin 以及汇率 / RPC 服务。proxy - 创建 canister 时未把 engine-operator 列为 controller。 通过 执行
proxy总会把你加上,但只有当你在create_canister中列出 operator 时才会加上它。少了它,settings.controllers就再也无法触达该 canister(不能安装代码、不能改设置),所有者也无法用proxy删除它。在创建调用中列出 operator(M5,步骤 1)。deleteCanisters - 在 的
proxy中使用文本形式的 Candid。args是保存管理方法参数二进制 Candid 编码的args(以blob开头的字节),DIDL也以同样形式返回。把文本形式的result作为(record { … })传入,会让管理 canister 无法解码参数。请先用 Candid 库编码(M5)。args - 期望连接器完成一个需要对新建 canister 进行调用的部署。 连接器只能调用应用声明过的 canister,而引擎清单只声明了它的 operator。它能通过 安装你的 wasm,但无法调用你安装的 canister,因此无法上传 asset canister 的文件。请在 init 参数或环境变量中传入配置,或对这类应用改用 CLI 路径。
proxy - 用早于 0.4.3 的 certified-assets 提供自定义域名。 对于每个带自定义域名的应用 canister,引擎会写入 (HTTP 网关需要它才能提供该域名)和
/.well-known/ic-domains(Internet Identity 需要它才能接受该域名)。它通过 certified-assets 的/.well-known/ii-alternative-origins写入这些文件,而该功能在 0.4.3 才出现。在更老的 canister 上,控制台会警告引擎无法写入这些文件,域名也不可用。请固定使用upload_asset或更新版本。要修复已部署的应用,提升 recipe 版本并运行@dfinity/static-site@v0.4.3。如果同步随后以icp deploy -e ic停止,运行assets canister version mismatch(v0.4.x 到 v0.4.3 是补丁版本,状态保留),然后再次运行icp canister install <frontend> --mode upgrade -e ic。从 v0.3.x 升级则是破坏性变更:见icp deploy -e icskill 陷阱 11。引擎会替换应用在这两个路径上提供的任何内容,所以不要把它们构建进static-site。请在dir根目录的dir文件中列出两者:没有它,每次部署都会删除它们,直到引擎再次写入(10 分钟内)。_preserve
Additional References
附加参考
- Load 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.
cloud-engine-canisters - Load for general icp CLI usage (
icp-cli, 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.icp.yaml - Load for details of the Internet Identity sign-in that Step 1 triggers in the browser.
user-sign-in - Load for the
service-discoverabilitymanifest 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./.well-known/ic-architecture - ICP MCP connector setup (ChatGPT plugin, Claude, custom connector URL): https://mcp.internetcomputer.org/.
- Load for what vetKD is and how VetKeys are used, once a proxy is in place: its call code targets a normal subnet, so see
vetkeysfor the proxied form an engine needs.cloud-engine-canisters - Load for cycles on ordinary (non-engine) canisters: balances, freezing thresholds, and ICP-to-cycles conversion via the CMC.
cycles-management
- 加载 获取在引擎上运行代码的调用规则:绝不附加 cycles、bounded-wait 跨子网调用、直接 HTTPS 出站调用,以及面向携带 cycles 的跨子网目标(XRC、threshold 签名、vetKD)使用控制台 proxy。在编写或调试引擎 canister 代码之前先加载它。
cloud-engine-canisters - 加载 获取 icp CLI 的通用用法(
icp-cli、recipes、environments、bindings、identities)。除本云引擎部署流程之外的内容都要加载它——尤其是项目还无法构建或打包时。icp.yaml - 加载 获取步骤 1 在浏览器中触发的 Internet Identity 登录细节。
user-sign-in - 加载 获取决定 ICP MCP 连接器可调用哪些 canister 的
service-discoverability清单,包括你部署的应用如何声明自己的 canister,以及发布该清单所接受的 operator 条款。/.well-known/ic-architecture - ICP MCP 连接器设置(ChatGPT 插件、Claude、自定义连接器 URL):https://mcp.internetcomputer.org/。
- 加载 了解 vetKD 是什么以及 VetKeys 如何使用(proxy 就位之后):其调用代码面向普通子网,因此引擎所需的形式请见
vetkeys。cloud-engine-canisters - 加载 了解普通(非引擎)canister 上的 cycles:余额、冻结阈值,以及通过 CMC 的 ICP 转 cycles。
cycles-management