Internet Computer

What is a canister?

All help topics

A canister is the Internet Computer's unit of software: a WebAssembly module together with its own persistent state, run by every node of its subnet.

  • Code. Canisters are written in Motoko (a language made for the IC) or Rust and compiled to WebAssembly. A canister exposes public methods, described by a Candid interface, that people, frontends and other canisters call.
  • State. What a canister stores lives in its own memory and persists between calls: there is no separate database server. A canister handles its messages one at a time.
  • Canister id. Every canister has an id, which is also its principal. It is how you call it and its web address: https://CANISTER_ID.icp.net.
  • Controllers. The principals allowed to manage the canister: install or upgrade its code, change its settings, stop it, snapshot it or delete it. The identity that created it is a controller. If every controller is lost, so is control of the canister, so keep a backup controller.
  • Settings. Among them, environment variables the code reads at runtime. icp deploy sets one per canister of the project, such as PUBLIC_CANISTER_ID:backend, so canisters find each other without hardcoded ids. A value can be at most 128 characters.
Install, upgrade, reinstall
  • Install: put code into a new, empty canister.
  • Upgrade: replace the code and keep the data. icp deploy upgrades a canister that already exists.
  • Reinstall: replace the code and wipe all data (icp deploy --mode reinstall). Use it only when you mean to start over.

Whether data survives an upgrade depends on how the code keeps it: see "How does my canister keep its data across upgrades?".

On a cloud engine
  • A canister showing 0 cycles is normal. Engine canisters hold no cycles and can't be topped up, because nothing they do is charged.
  • The console's canister page shows its status and controllers. A snapshot (a copy of its code and data at one moment, to roll back to later) is taken by one of those controllers outside the console, for example with the icp CLI; the console has no snapshot control today. A snapshot before a risky upgrade is a cheap safety net.
  • To show several canisters as one named app in the console, give them the environment variables __META_PROJECT (the same value on each), __META_NAME, and __META_MAIN_CANISTER set to "true" on exactly one entry-point canister.
Learn more
Still stuck? Contact support