# Deploy To Cloud Engine

> Deploys a built Internet Computer project to a cloud engine (OpenCloud). From a sandboxed chat or cloud session with the ICP MCP connector (ChatGPT, Claude, https://mcp.internetcomputer.org/mcp): install the wasm through the engine-operator's `proxy`. Otherwise with the icp CLI: `icp identity link web` (defaults to https://opencloud.org), `icp deploy` on the engine's subnet. Also: `__META_*` for a named console app, version metadata (service:git:sha), and the proxy canister for Bitcoin/Ethereum signing, VetKeys or exchange rates (paid from the engine's balance, or `icp new --subfolder proxy`). Use when shipping to a cloud engine; on mention of OpenCloud, an engine subnet id, ICP MCP deploys, or linking the icp CLI; when sign-in never completes from a sandbox; when naming, versioning or giving an icon to a console app; when funding a proxy or picking which balance to top up (failing proxied calls: cloud-engine-canisters). Do NOT use for a mainnet deploy with no engine (icp-cli) or canister logic.

- Skill: `jiayaoqijia/deploy-to-cloud-engine-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add jiayaoqijia/deploy-to-cloud-engine-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiayaoqijia/deploy-to-cloud-engine-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: Apache-2.0
- Author: jiayaoqijia (https://skillmd.com/u/jiayaoqijia)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/jiayaoqijia/deploy-to-cloud-engine-2

---


# Deploy to Cloud Engine

## What This Is

A **cloud engine** is a user-owned slice of Internet Computer capacity, administered from a web console (by default `https://opencloud.org`). Each engine runs on a single **subnet**. This skill takes a project that already builds and gets it deployed onto that engine, from a coding agent or an AI chat app.

This skill only covers the cloud-engine-specific steps: choosing how to deploy, signing in as an identity the engine accepts, and putting the canisters on the engine. For everything else about the CLI (`icp.yaml`, recipes, environments, bindings, identities), load the **`icp-cli`** skill.

## Choose the Deploy Route First

There are two ways onto an engine. Pick one **before you write any code**: the route decides how the deploy signs in and what you can ship.

- **ICP MCP connector.** DFINITY's official MCP server for the Internet Computer. It is available natively in ChatGPT (the plugin **Internet Computer (ICP)** by DFINITY Stiftung) and in Claude, and any MCP-capable app can add it as a custom connector at `https://mcp.internetcomputer.org/mcp` (setup steps: https://mcp.internetcomputer.org/). It signs as the user with the Internet Identity session they authorized in the chat app, so nothing needs a local CLI, a browser on your machine, or a loopback. You deploy a wasm through the engine's engine-operator canister. See **"ICP MCP Route"**.
- **icp CLI.** `icp identity link web`, then `icp deploy --subnet`. The full toolchain (recipes, asset canisters, `icp.yaml`), but the sign-in completes only when `icp` runs on the same machine as the user's browser. See **Steps 1 to 4**.

Decide like this:

1. **You run in a sandbox and the ICP MCP tools are available to you** (`open_app`, `get_app_principal`, `canister_update_call`, …) → **use the ICP MCP route.** A sandbox is a web or mobile chat (ChatGPT, Claude on the web or a phone) or a cloud coding session. Do not ask the user to move to a local session, and do not attempt `icp identity link web` or the delegation handoff there.
2. **Otherwise → the CLI route: link the CLI** (Step 1).
   - **Local session** (a coding agent on the user's own computer: Claude Code, Codex CLI, Cursor, or the local environment of the Claude desktop app): link the CLI and deploy with it, even when the ICP MCP tools are also available. The normal link flow works there, and the CLI can ship what the connector cannot, such as the files of an asset canister (see "What the connector cannot do").
   - **Sandbox without the ICP MCP tools**: the CLI sign-in cannot finish there (see Step 1.0). Tell the user before you build anything, and ask them to start a local session instead. If their chat app can add MCP connectors, adding the ICP MCP connector is the other way. A cloud session cannot move to their computer later, so ask before you build, not after, and wait for the answer. Continue in the sandbox with the CLI only when the user has neither option. Then do the delegation handoff in Step 1.0 **first**, and build only after the sandbox CLI signs as the user: do not leave the sign-in for deploy time.

Before running any `icp` command you are unsure of, run `icp <subcommand> --help` (e.g. `icp identity link --help`, `icp deploy --help`) to confirm the command and flags exist. Do not infer flags. Authoritative reference: https://cli.internetcomputer.org/llms.txt

## What You Need

Two values, and a third for some apps. Look for them first in `icp.yaml` or earlier in the conversation. One has a default; the others you must ask for:

1. **Console origin** — the URL the user signs in to their cloud engine console with. **Defaults to `https://opencloud.org`** (the main OpenCloud console). Its host is the `--app` value in Step 1, so the linked CLI identity derives the **same principal that administers the engine**. Use the default, but say so and give the user a chance to override before linking:
   - Say: "I'll link the CLI against `https://opencloud.org`, the default console. If you sign in to your engine console at a different URL, tell me now."
   - Only use a different origin when the user names one — never substitute another URL on your own; the `--app` domain determines the derived principal (see Pitfall 2).
   - On the ICP MCP route there is no `--app`; the console origin is where you look the engine up and where the owner confirms access (M1, M3).
2. **Subnet id** (CLI route): the subnet the engine deploys to, required by `icp deploy --subnet`. There is **no default**; never guess it. The user finds it on the engine's **Settings** page in the console (under the engine's identifiers), or copies it from the console's command palette. If absent, **ask and do not proceed without it**:
   - Ask: "What is your engine's subnet id? It is on your engine's Settings page in the console."
   - On the ICP MCP route you need the **engine id** instead (M1). The operator creates canisters on its own engine, so there is no subnet to pass.
3. **Proxy canister id**: only if the app calls threshold ECDSA/Schnorr, vetKD, the exchange-rate canister, the Bitcoin API, or the EVM/SOL RPC canisters (look for a `PROXY_CANISTER_ID` variable, or a call to a `proxy` method). There is **no default**, you cannot create the console proxy yourself, and a self-deployed one is no substitute (Step 5). If absent, **ask before deploying**:
   - Ask: "This app needs your engine's proxy canister. If the engine has one, send me its id (engine → Integrations → Proxy canisters). If not, the engine owner can deploy one there with Deploy a proxy: it is paid from the engine's balance, no card. Then send me its id."

Record them so you do not re-ask within the session.

## Prerequisites

- CLI route: `icp` on `$PATH` — see the **`icp-cli`** skill to install. Verify with `icp --version` (this skill's commands are verified against 0.3.0 and 1.0.2). If the installed version differs, confirm the flag set with `icp <cmd> --help` before running — flags have changed across major versions.
- A project that already builds. If it does not build or package yet, set that up first (see the `icp-cli` skill), then return here.
- **No project yet, and no description of one?** Ask the user what to build before you write any code or create any files: "What app do you want to build?" Do **not** pick a sample app (a guestbook, a counter, a to-do list) on your own. A prompt that only says "build and deploy an app" is a request to ask, not a request to choose.
- CLI route, macOS: `icp` stores its data under `~/Library/Application Support/org.dfinity.icp-cli/`. If the shell cannot write there (`Operation not permitted` from macOS TCC, e.g. when commands run through a bridge), redirect the data to an unprotected path for the session — `HOME=/tmp/icp-home icp …` — and keep that same `HOME` on **every** subsequent `icp` command, or the later commands will not see the linked identity.
- ICP MCP route: the connector's tools in your tool list, connected with **Actions & questions** access (M0).

## ICP MCP Route

For a sandboxed agent that has the ICP MCP tools (see "Choose the Deploy Route First"). No `icp` CLI, no loopback, no delegation handoff. Steps 1 and 3 are the CLI route and do not apply. Step 2 (naming the app) and Step 5 (the proxy canister for chain-key services) still do: M6 shows how to set their variables without `icp.yaml`.

The engine-operator canister's own API guide is the authoritative, current walkthrough of the calls below: read it in M2 before you call anything.

### M0. The connector and its access level

If the tools are missing and the user's app can add MCP connectors, ask them to add it: in ChatGPT the plugin **Internet Computer (ICP)** by DFINITY Stiftung, in Claude its connector, and in any other MCP-capable app a custom connector at `https://mcp.internetcomputer.org/mcp`. The steps are at https://mcp.internetcomputer.org/.

On connecting, the user signs in with Internet Identity, picks how long the session lasts, and picks an access level. A deploy needs **Actions & questions**. With **Questions only**, reads work, but the network rejects every state-changing call, so `create_canister` and `install_code` fail. If an update call is rejected that way, ask the user to reconnect with Actions & questions. Sessions expire by design: reconnecting later is normal.

### M1. Find the engine

You need three values: the engine's **id**, its **engine-operator canister id** (`engine_operator_id`), and its **platform domain** (`platform_domain`, like `<engine-name>--<slug>.opencloud.org`).

- Ask the user for the engine id. It is in the console URL (`/console/engines/<engine-id>/…`) and on the engine's **Settings** page.
- `open_app` on the console origin (`https://opencloud.org`) lists the engine registry canister. Read its public `getEngineViews` query with `(vec { "<engine-id>" })`; the record carries `engine_operator_id` and `platform_domain`. Signed as the user, its `listVisibleEngines` query returns the engines they own, with the same fields.

A new or renamed engine's platform domain takes about ten minutes to register. Do not open or fetch it before then: a lookup that finds no record can be cached as missing for up to 30 minutes, and the domain keeps failing for you after it is live. Reach the engine through its operator's `https://<engine_operator_id>.icp.net` host instead, which works as soon as `engine_operator_id` is set. `GET https://icp.net/custom-domains/v1/<platform_domain>` answers `registration_status` `registered` once the platform domain serves: give the user that address from then on.

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

1. `open_app` on `https://<engine_operator_id>.icp.net`. The engine-operator publishes the engine's `/.well-known/ic-architecture` manifest, so it comes back as `[declared]`; that is what lets the connector call it. The connector refuses calls to any canister an app does not declare. Check that the `derivation_origin` it returns is `https://<platform_domain>`. If it is the icp.net origin, the operator does not hold the engine's domain yet: wait a minute and `open_app` again before M3, or the principal you get there changes later.
2. `get_canister_api_doc` on the operator, and read its section **"Creating a canister and installing a wasm"**.
3. `get_canister_candid` on the operator, and check that its service has a `proxy` method. If it has none, the engine still runs an engine-operator from before the ICP MCP route existed: tell the user, and use the CLI route.

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

Internet Identity derives a principal per origin. At the engine, the connector signs as the principal derived for the engine's **platform domain** (the origin in its `/.well-known/ii-derivation-origin`). That is **not** the principal the user signs in to the console with, nor a CLI identity linked against the console origin. So the engine does not know it yet, even when the user owns the engine.

1. `get_app_principal` with the `derivation_origin` that `open_app` returned in M2 gives you that principal, `P`. Its reply also says whether the session is query-only: if it is, stop and have the user reconnect with Actions & questions (M0). If the user has several accounts at the engine, pick one with `account` and keep passing the same one, since each account is a different principal.
2. Check whether it is a member: the operator's public `getRole` query with `(record { principal_id = opt principal "<P>" })`. Any role is enough, because every role has the `CreateCanister` permission that `proxy` needs.
3. If the role is null, you cannot add `P` yourself. Give the user (the engine owner, or an engine admin) this link. It opens the engine's invite dialog with the grant filled in, so they only sign in and confirm:

   ```
   https://opencloud.org/console/engines/<engine-id>/team?modal=invite-member&principal=<P>&role=developer
   ```

   Use their console origin instead of `https://opencloud.org` if it differs. `developer` is enough to deploy: do not ask for `admin`. Wait for them to confirm, then repeat step 2.

Renaming the engine changes its platform domain, and with it `P`: the new principal needs the invite again.

### M4. Build a wasm the connector can ship

The connector installs a **wasm module** and nothing else.

- **Build it where you can.** In a code sandbox with the toolchain, `icp build` needs no sign-in (see `icp-cli`), and its recipe bakes in Step 2's version metadata as usual. Or use a prebuilt `.wasm` / `.wasm.gz` the user attaches. Canister code follows the engine's call rules: load `cloud-engine-canisters`.
- **Keep it small.** The module travels inside the tool call as a Candid blob, so build for release and gzip it: the operator accepts a gzipped module. Above about 2 MB, it has to go up in chunks (M5, step 4).

#### What the connector cannot do

The connector calls only canisters that an app declares, and the engine's manifest declares only its operator. So your new canister is reachable only through the operator's relayed management calls (M5): the connector **cannot call the new canister's own methods**. That rules out anything that needs calls after the install, such as uploading the files of an asset canister (`@dfinity/static-site`, `@dfinity/asset-canister`). Pass configuration in the init argument (`arg`), or as environment variables (M6). If the app needs an asset upload, it needs the CLI route: tell the user.

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

The connector may not call the IC management canister (`aaaaa-aa`) directly. The engine-operator's **`proxy` method** calls it for you, as the caller you sign as. Do not confuse it with the **proxy canister** of Step 5: that one relays chain-key calls for your app's code, and has nothing to do with deploying.

Each step is one `canister_update_call` with `canister_id` the engine-operator, `method = "proxy"`, `app_url` the app URL and `derivation_origin` the derivation origin that `open_app` returned in M2 (plus the same `account` as in M3, if you chose one). **Always pass `derivation_origin`**: without it the call runs anonymously, and `proxy` answers `UnauthorizedUser`. The `args` are:

```candid
(record {
  canister_id = principal "aaaaa-aa";
  method = "<management method name>";
  args = blob "<the method's argument, Candid-encoded>";
  cycles = 0;
})
```

`args` holds the **binary** Candid encoding (bytes starting with `DIDL`) of the management method's argument, written as a `blob "…"` literal with `\xx` escapes. It is not textual Candid: encode it with a Candid library in your code sandbox. A success is `variant { Ok = record { result = blob "…" } }`, where `result` is the method's reply in binary Candid. The argument and reply types are in https://docs.internetcomputer.org/references/ic.did.

1. **Create.** `method = "create_canister"`, and `args` encodes:

   ```candid
   (record { settings = opt record { controllers = opt vec { principal "<engine-operator-id>" } } })
   ```

   List the engine-operator as a controller. You (`P`) are added as a controller automatically, but without the operator `proxy` can never reach the canister again: no install, no settings, and no `deleteCanisters` for the owner either. If the code reads an environment variable when it initializes (such as `PROXY_CANISTER_ID`), add `environment_variables` to these `settings` now: it must be in place before step 2 (see M6). `result` decodes to `(record { canister_id : principal })`.
2. **Install.** `method = "install_code"`, and `args` encodes:

   ```candid
   (record {
     mode = variant { install };
     canister_id = principal "<canister id from step 1>";
     wasm_module = blob "<wasm bytes, gzipped or not>";
     arg = blob "DIDL\00\00";
     sender_canister_version = null;
   })
   ```

   `arg` is the binary-Candid init argument; `DIDL\00\00` passes none. `result` decodes to `()`.
3. **Replace the code later.** The same call with `mode = variant { upgrade = null }` keeps the stable memory; `variant { reinstall }` wipes all state. A canister built with enhanced orthogonal persistence (current Motoko) rejects `upgrade = null`: upgrade it with `variant { upgrade = opt record { wasm_memory_persistence = opt variant { keep } } }`. Use `keep` **only** for such a build: the IC rejects it when the new module lacks the `enhanced-orthogonal-persistence` custom section (a Rust canister, or classical-persistence Motoko), so those keep `upgrade = null`. (The operator's guide says other canisters ignore `keep`; the IC interface spec says otherwise, and the spec wins.)
4. **A module over about 2 MB** (the single-message limit) goes up with `upload_chunk`, then installs with `install_chunked_code`.

The operator relays only `create_canister`, `canister_status`, `update_settings`, `install_code`, `upload_chunk`, `clear_chunk_store`, `install_chunked_code`, `start_canister` and `stop_canister`, and only on canisters that list you as a controller. Any other method, the operator itself, and protected canisters come back as `Err` `CallFailed` with a `reason`, as does any `proxy` call on a canister while an `update_settings` on it is in flight: retry once it completes. `cycles` is ignored, since the engine charges nothing. `Err` `UnauthorizedUser` means the call was not signed by a member: check that you passed `derivation_origin`, then go back to M3.

### M6. Name the app, and pass configuration

Step 2's `__META_*` variables, and `PROXY_CANISTER_ID` from Step 5, are canister environment variables. With no `icp.yaml` to carry them, you set them yourself, and **when** matters:

- **A variable the code reads at init or upgrade** (`PROXY_CANISTER_ID`, a key name, any configuration) must be set **before** the `install_code` that reads it. Otherwise init sees it missing, and traps or bakes in a fallback that a later upgrade does not undo. Put it in `create_canister`'s `settings` (M5, step 1), or set it with `update_settings` between steps 1 and 2. Before an upgrade or reinstall that should see a new value, set that value first.
- **Display-only metadata** (`__META_*`) is read by the console, not by your code, so it can follow at any time. `__META_BASE_URL` needs the canister id, so it comes after step 1 anyway.

Either way it is `update_settings` through `proxy`, with `args` encoding:

```candid
(record {
  canister_id = principal "<canister id>";
  settings = record {
    environment_variables = opt vec {
      record { name = "__META_PROJECT"; value = "My App" };
      record { name = "__META_NAME"; value = "App" };
      record { name = "__META_MAIN_CANISTER"; value = "true" };
    };
  };
})
```

The list **replaces** the canister's whole set of variables, so send all of them every time. The rules for their values are in Step 2.

### M7. Verify

- `canister_status` through `proxy`, with `args` encoding `(record { canister_id = principal "<canister id>" })`, shows `status = variant { running }` and the installed `module_hash`.
- A canister that serves HTTP is reachable at `https://<canister-id>.icp.net`. On an all-in-one engine it is under the engine's own domain instead: the operator's guide names which.
- The canister appears on the engine's **Your apps and services** page in the console.

Report the canister id(s), and the URL if any, back to the user.

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

The CLI must sign as the **same identity that administers the engine** — that is the principal you log in to the console with.

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

`icp identity link web` completes the sign-in via a redirect to `http://127.0.0.1:<port>` **on the machine where the CLI runs**. The browser in which the user completes the Internet Identity sign-in must be able to reach that loopback address. Determine the environment before linking:

- **CLI and browser on the same machine, with network** (local development, or a terminal-integrated agent on the user's own machine) → use the normal link flow below.
- **CLI in a remote or isolated sandbox, with network** (the agent runs in the cloud; the user's browser is on a different machine) → the normal flow **cannot** work: the sign-in URL carries a `callback=http://127.0.0.1:<port>` bound to the sandbox, the user's browser resolves `127.0.0.1` to its *own* machine, and the delegation never reaches the CLI. Later commands then fail with authorization errors. If you have the ICP MCP tools, stop here and use the ICP MCP route. Otherwise ask the user to switch to a local session, or to add the ICP MCP connector (see "Choose the Deploy Route First"). Use the **delegation handoff** below only if they can do neither.
- **CLI shell with no network at all** (e.g. a sandboxed device bridge on the user's own machine: DNS blocked, HTTPS requests fail, writes limited to `/tmp`) → **no** `icp` network command can run there — not the link, and not `icp deploy` either. The delegation handoff does not help: it only moves signing authority, not network access. Do not retry, tunnel, or proxy. Prepare the project and hand the user **one script** to run in their real terminal — see "No-network CLI host" below.

When in doubt, probe before linking: `curl -sI https://<console-origin>` failing (or DNS not resolving) from the CLI shell means the no-network case.

**Never** present a sandbox `127.0.0.1` URL to the user as something to open in their browser — it is unreachable from their machine. And do not invent a headless flag on `icp identity link web`: as of icp-cli 1.0.2 it has none (confirm with `icp identity link web --help`).

### Delegation handoff (CLI host and browser on different machines)

`icp identity delegation` transfers signing authority from an identity linked on the **user's** machine to a session key on the **CLI host**, without the browser ever reaching the CLI host. It requires `icp` installed on the user's machine too, and exists in icp-cli 1.0.x — verify with `icp identity delegation --help` on both machines. If the user's machine has `icp` and you can run commands there, the simplest path is to run this whole skill there instead; otherwise:

1. **On the CLI host (sandbox)** — create a pending identity with a fresh session key:

   ```bash
   icp identity delegation request <your-identity-name>
   ```

   It prints the session **public** key as a PEM to stdout. Give that PEM block to the user. (If the default `--storage keyring` fails in a headless sandbox, retry with `--storage plaintext`.)

2. **On the user's machine** — the user links there if not already linked (`icp identity link web <local-name> --app <console-domain>` — the normal flow works locally), saves the PEM to a file, and signs a delegation to it:

   ```bash
   icp identity delegation sign --identity <local-name> --key-pem session-key.pem --duration 8h > delegation.json
   ```

   `--duration` takes e.g. `30m`, `8h`, `1d`; optionally `--canisters <ids>` restricts the delegation. The user sends `delegation.json` back. If `sign` fails with `delegation for identity <name> has expired or will expire within 5 minutes`, the local web session has lapsed — run `icp identity reauth <local-name>` (the normal browser flow, which works locally) and retry.

3. **On the CLI host** — complete the pending identity and activate it:

   ```bash
   icp identity delegation use <your-identity-name> --from-json delegation.json
   icp identity default <your-identity-name>
   icp identity principal   # must print the user's console principal
   ```

Treat `delegation.json` as a **time-limited credential**: whoever holds the sandbox's session key can sign as the user's console principal until it expires. Keep the duration short and re-run the handoff when it lapses.

### No-network CLI host — hand the user one script

If the CLI shell cannot reach the network, the user's real terminal is the deploy machine — and because their terminal and browser share a loopback there, the **normal** link flow works; no delegation handoff is needed. Your job shifts to preparation:

1. Get the built project into a directory the user's terminal can reach.
2. Write one script at the project root that does the whole network-bound sequence — adapt this template (fill in the real identity name, console domain, and subnet id; do not leave placeholders):

   ```bash
   #!/usr/bin/env bash
   set -euo pipefail
   icp --version
   icp identity list | grep -E '^\*? *<your-identity-name> ' >/dev/null || icp identity link web <your-identity-name> --app <console-domain>
   icp identity default <your-identity-name>
   icp deploy -e ic --subnet <subnet-id>
   ```

3. Ask the user to run it in their terminal, complete the Internet Identity sign-in when the browser opens, and paste the output back.
4. Verify from the pasted output (canister ids, frontend URL) and continue — a re-deploy for the Step 2 `__META_*` variables goes through the same script.

### Normal link flow (CLI and browser share a loopback)

First check what already exists:

```bash
icp identity list      # names + principals; * marks the active identity
```

The list does **not** show which console (if any) an identity was linked against — that cannot be determined from the CLI. Decide like this:

- **Only `anonymous` (or plain local identities) listed** — no web-linked identity exists; run the link command below.
- **An identity the user recognizes as their engine identity** (by name or principal) — set it active (below) and skip to Step 2.
- **Unsure** — ask the user, or simply relink under a new name; linking again is cheap and safe.

To link, run this, substituting a name the user picks — `<your-identity-name>` is any local label, not a fixed value (do not hardcode something like `my-engine-admin`); reuse the **same** name in every command below:

```bash
icp identity link web <your-identity-name> --app <console-domain>
```

- `<console-domain>` is the host of the console origin, with no scheme, port or path: `opencloud.org` for the default console, `beta.opencloud.org` for `https://beta.opencloud.org`. The console derives its principal from the host it serves, so this is the domain to name. Do not take it from `/.well-known/ii-derivation-origin`: that file serves the ICP MCP route and can name another host.
- Never omit `--app`. Without it, Internet Identity derives the principal for `cli.id.ai`, which is **not** your console, and the engine rejects every deploy as unauthorized.
- Do not use `--auth <console-origin>` for the OpenCloud console. It reaches the same principal, but through the console's own `/cli` page, so the user signs in on two screens instead of one. Use `--auth <console-origin>` (no `--app`) only when the user says their console signs in with its own Internet Identity rather than `id.ai`, as a test deployment does.
- The command first waits at a **"Press Enter to log in"** prompt before anything happens. Run it interactively when you can; in a non-interactive shell (e.g. a background process) pipe a real newline:

  ```bash
  printf '\n' | icp identity link web <your-identity-name> --app <console-domain>
  ```

  Do **not** redirect stdin from `/dev/null` — the bare EOF does not satisfy the prompt, and the command sits on "Press Enter to log in" indefinitely with no browser ever opening.
- After Enter it opens a **browser tab**. The **user** completes the Internet Identity sign-in there. Wait for them to confirm before continuing — you cannot complete the sign-in for them.
- On first use, id.ai can stop at a **"CLI access disabled"** screen. That is the expected first run, not an error. Tell the user to turn on **CLI access** for their identity in the Internet Identity settings, then run the link command again from the start: the old sign-in URL is single-use. See the `agent-web-identity` skill, Pitfall 1.
- `--app` must be the **exact** console host, e.g. `opencloud.org`. Another domain derives a *different* principal, and the engine will reject the deploy as unauthorized.
- This is a **one-time, per-machine** step.

Then make it the active identity and verify:

```bash
icp identity default <your-identity-name>
icp identity default     # prints the active identity name
icp identity principal   # prints the principal the deploy will sign as
```

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

By default, CLI-deployed canisters appear on the engine console's **Your apps and services** page as bare rows labelled only by their principal id. A set of **canister environment variables** makes the console group them into a single named application with readable per-canister labels, an "Open" button, and an icon. Set them once in your project config:

- `__META_PROJECT` — the application name. Canisters that share the **same** value are grouped into one named app, so set an identical value on every canister of the app.
- `__META_NAME` — the per-canister display label (e.g. `Backend`, `Frontend`).
- `__META_MAIN_CANISTER` — the literal string `"true"` on exactly one canister (the entry point, usually the frontend/asset canister). This marks the app's **main canister**: the console reads `__META_BASE_URL` and `__META_ICON_PATH` only from it, and the "Open" button targets it.
- `__META_BASE_URL` — an **absolute `https://` URL**, set on the main canister (e.g. the frontend canister's URL `https://<frontend-canister-id>.icp.net`, or a custom domain). When present and valid, it is the URL the "Open" button opens; when absent or not `https`, the "Open" button falls back to the main canister's gateway URL. It is also the base that `__META_ICON_PATH` resolves against.
- `__META_ICON_PATH` — the path to the app icon, resolved against `__META_BASE_URL` to form the icon the console renders (e.g. `/favicon.svg` → `https://<base>/favicon.svg`). Set it on the **main** canister, alongside `__META_BASE_URL`.

The icon and "Open" link are read **only from the main canister** (the one marked `__META_MAIN_CANISTER: "true"`) — `__META_BASE_URL` / `__META_ICON_PATH` on any other canister are ignored.

On the ICP MCP route there is no project config: set the same variables with `update_settings` (M6). On the CLI route, set them under each canister's `settings.environment_variables` — this is valid alongside a recipe. With per-canister `canister.yaml` files:

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

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

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

```yaml
# icp.yaml — canisters defined inline
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.

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

Internet Identity derives a principal **per origin**. An app reached at both its canister address and a custom domain signs the same person in as two different users.

The engine console names the app's **canister address** as the origin to derive from. It cannot be renamed or removed, so it survives adding, changing, or dropping a custom domain. It is the address of the canister that **serves your frontend** (the asset/static-site canister the browser loads the app from), built from that canister's id:

```
https://<frontend-canister-id>.icp.net
```

That is usually the canister you marked `__META_MAIN_CANISTER: "true"`, but that flag is a console display setting, not a guarantee. If you marked a backend canister, still derive from the frontend canister. A backend canister cannot be a derivation origin: the browser is never on it, and it cannot serve the `.well-known/ii-alternative-origins` file Internet Identity fetches from that origin to validate the claim.

Build the value from the canister id, **not** from `__META_BASE_URL`. The two match only while `__META_BASE_URL` still points at the canister address. Pointing it at a custom domain is normal and supported (see the icon notes above), and the two then differ. A custom domain is the one value that must never become the derivation origin.

**Do this before the app has users, not after.** A domain that has already collected sign-ins cannot be repointed at a derivation origin without orphaning every account created under it. If the app might ever get a custom domain, set `derivationOrigin` on the first deploy even while the canister address is the only origin — it costs nothing then and cannot be applied retroactively without losing accounts.

For the mechanics — the `derivationOrigin` option and the `.well-known/ii-alternative-origins` file, including the `_headers` entry the `@dfinity/static-site` recipe needs — load the **`user-sign-in`** skill.

Caffeine apps are the exception: Caffeine owns their address, so it is not the app's to derive from. The console withholds the canister-address row for them.

### Version metadata (recommended)

Embed build provenance into each canister's wasm so tooling and the console can show what version is running (console support is rolling out; the metadata is already readable — see the verify note below). Add this **by default on every deploy** — do not wait for the user to ask. All official recipes (motoko, rust, static-site, asset-canister, prebuilt) accept a `metadata` list under the recipe `configuration`; each entry is baked into the wasm as a custom section. Values are interpolated into a shell command at build time, so `$(…)` command substitution works. (Verified by live builds against `@dfinity/motoko` v4.1.0 and v5.0.0 on icp-cli 1.0.2.)

**Git project** (check first: `git rev-parse HEAD` succeeds):

```yaml
recipe:
  type: "@dfinity/motoko@v5.0.0"
  configuration:
    metadata:
      - name: service:git:sha
        value: $(git rev-parse HEAD)$(git diff --quiet HEAD 2>/dev/null || echo +dirty)
      - name: service:git:origin
        value: $(git remote get-url origin)
      - name: service:git:updated_at
        value: $(git log -1 --format=%cI)
      - name: service:version
        value: $(node -p "require('./package.json').version" 2>/dev/null || echo 1.0.0)
```

**Non-git project** — the git substitutions above do **not** fail the build; they silently bake garbage (`service:git:sha` becomes the literal `+dirty`, `service:git:origin` comes out empty). Use only an explicit version, and bump it on each subsequent deploy:

```yaml
metadata:
  - name: service:version
    value: "1.0.0"
```

Notes:

- Use these exact names (`service:git:sha`, `service:git:origin`, `service:git:updated_at`, `service:version`) — they are the agreed convention the console will read; differently named entries will not be picked up.
- Prefer command results over literals where possible: `+dirty` on the sha flags uncommitted changes, so a deploy is traceable to its exact source state.
- Values must be **deterministic** for a given source tree: sha, origin, the last commit's date, a version string. Never embed a build time (`$(date)`) or other build-time-varying values. The commit date (`%cI`) is allowed because it is a property of the commit, not of the build — but note it means "code last changed", not "last deployed": deploying an old commit shows the old date. The deploy time itself comes from the canister history the network records automatically.
- If the project has no `package.json` (or no version field), the fallback `1.0.0` applies; replace it with the project's real versioning scheme when one exists.
- The sections are injected as `icp:private`, readable by the canister's controllers (you, and the console acting as you) via read_state — no canister call needed. Verify after deploy, with the linked identity active: `icp canister metadata <canister-name> service:git:sha -e ic`.

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

From the project root:

```bash
icp deploy -e ic --subnet <subnet-id>
```

- `-e ic` targets mainnet (the engine runs on an IC subnet); `--subnet <subnet-id>` pins the deploy to **your engine's** subnet. Confirm the exact flags with `icp deploy --help` before running if unsure.
- Deploying consumes capacity on the engine; make sure the engine has room.

**Alternative: packaged upload.** If the project is distributed as a built `.icp` package and a direct `icp deploy` is not available, the user can upload the bundle instead: engine → **Your apps and services** → **Upload a bundle**, which walks through uploading the `.icp` bundle. The page's other button, **Build with agents**, gathers the other ways in: a coding agent, Caffeine, the CLI instructions this skill automates, and OpenSaaS for ready-made apps.

## Step 4 — Verify

- The `icp deploy` output reports the deployed canister ids.
- The canisters appear on the engine's **Your apps and services** page in the console; each canister's detail view offers an "Open in browser" link.
- If you set the metadata in Step 2, the canisters are grouped under your `__META_PROJECT` name with their `__META_NAME` labels, and the main canister shows an "Open" button — instead of bare principal rows. With `__META_BASE_URL` + `__META_ICON_PATH`

…(truncated)
