Operations and management capabilities
This reference separates who runs an operation from what it needs. Run as You uses your signed-in identity, or the explicit wallet flow. Run as an Agent uses the selected Agent and needs current compatibility, capability support, active membership, and the target authority the operation requires.
Management route and role matrix
Section titled “Management route and role matrix”Read-write below means an active Read-write or Admin member. A minimum role never substitutes for the Agent being a controller of a protected target.
| Operation family | Run as You | Run as an Agent / minimum role | Verify with |
|---|---|---|---|
| Current management status | Browser, subject to target status visibility | Read-write for fresh management work plus applicable target access | Returned target, timestamp, status, hash, and settings |
| Live canister information and named management metadata | Agent-required management methods; independent browser evidence may still be available | Read-write plus target access | Returned change history or exact named metadata |
| Management consumption metrics | Browser controller | Read-write plus target controller | Returned cumulative counters for the exact target |
| Start, stop, delete | Browser controller | Read-write plus target controller | Live lifecycle or authoritative absence after deletion |
| Install, upgrade, reinstall, uninstall | Browser controller | Read-write plus target controller | Live module hash, lifecycle, and application checks |
| Resource settings and operational visibility | Browser controller | Read-write plus target controller | Full current settings read-back |
| Controller-list change | Browser controller | Admin plus target controller | Authoritative controller list and retained recovery access |
| Snapshot capture, restore, delete | Browser controller | Read-write plus target controller | Live snapshot record or restored target state |
| Snapshot listing, metadata and bytes; transfer workflow | Browser under required snapshot/management authority | Admin; exact target checks still apply | Snapshot identity, metadata, byte ranges, and restored state |
| Preserve-ID migration | Your authorized lifecycle flow | Admin plus required authority on both targets | NNS status and post-migration placement/state |
Snapshot slot replacement and capture-with-uninstall run as You only. Follow Snapshots before selecting those options.
Explicit browser and wallet routes
Section titled “Explicit browser and wallet routes”| Surface | Execution boundary |
|---|---|
| Logs | Browser-direct log read, using the target’s log visibility rules |
| Calls | Public boundary-node request evidence; read-only |
| API | Browser calls to arbitrary target Candid methods; target method authorization applies |
| Web and domains | Browser-facing asset/gateway workflow; DNS and required asset publication have separate steps |
| Manual canister funding and creation | OISY-authorized official ICP protocol flow; reviewed wallet account, destination, amount, and fees |
| Automation reserve funding | Wallet-authorized funding plus Agent-side confirmation and accounting |
| Automatic canister top-up | Agent-owned workflow under funding policy, action authority, and target-controller checks |
Run as an Agent never silently turns a blocked supported management action into a call as You. Read the route indicator for browser-only work. An OISY signature authorizes the reviewed wallet operation; it is separate from your Internet Identity application principal.
Retained reads and administration
Section titled “Retained reads and administration”| Work | Required Agent access |
|---|---|
| Permitted retained Registry, metrics, dashboards, reports, Timeline, and Monitor views | Active read access or the explicitly enabled authenticated viewer surface |
| Registry and dashboard content writes | Active Read-write or Admin |
| Fresh management reads | Active Read-write or Admin plus applicable target access |
| Interactive AI | Active Read-write or Admin and current AI policy |
| People, audit/Activity, operation-ledger reconciliation, Agent policy/configuration | Active Admin |
| Job receipt lookup | Active members see their own jobs; Admin sees all |
The authenticated viewer surface is an allowlisted subset. It does not expose People, audit, arbitrary live management calls, or AI conversations. See roles and Agent API for details.
Selected Agent management limits
Section titled “Selected Agent management limits”These bounds constrain individual requests; they do not guarantee that every request within the bound succeeds on the target.
| Input | Maximum |
|---|---|
| Inline Wasm module | 2,000,000 bytes |
| Install argument | 1,000,000 bytes |
| One uploaded Wasm chunk | 1,048,576 bytes |
| Ordered chunk hashes per chunked install | 10,000 |
| One snapshot read or upload chunk | 1,048,576 bytes |
| Snapshot ID | 128 bytes |
| Snapshot runtime globals | 10,000 |
| Snapshot certified data | 32 bytes |
| Explicit viewers per log, snapshot, or status visibility list | 10 nonanonymous principals |
| Recent canister changes requested through the Agent | 20 |
For funding bounds, use the exact product policy. For wire types, use the Candid download.
Outcome and replay semantics
Section titled “Outcome and replay semantics”A known rejection before dispatch can allow a corrected submission. An uncertain response after dispatch requires reconciliation first. Snapshot restoration, code changes, controller updates, migration, and payments each have their own verification path in the linked task guides.
Deployment contract
Section titled “Deployment contract”The deployment guide covers the operator workflow. The browser accepts Wasm or gzip uploads up to 100 MiB, with the same limit on decoded Wasm. Gzip is decoded and inspected in memory; only decoded bytes are staged. The summary reports upload size, chunk plan, decoded module hash, and target; its size tooltip provides exact uploaded and decoded byte counts.
A saved draft binds workspace, network, caller, transport, and Agent. It retains mode, upgrade options, file name and size, module and argument SHA-256 hashes, and the pre-deploy snapshot ID. It contains neither Wasm nor argument bytes. A chunk journal for an upload run as You additionally binds the exact target and staged payload. Resume requires the original identity and browser, matching payloads, and fresh chunk-store, module, status, and snapshot evidence.
Install checkpoints bind workspace, network, caller, Run as, Agent, and endpoint. Chunk cleanup for an upload run as You retains the staging journal until authoritative version, hash, and empty-store evidence permit reconciliation. Agent cleanup uses its durable operation identity. Neither route replays an ambiguous mutation.
Deletion and cycle recovery
Section titled “Deletion and cycle recovery”The reviewed deletion workflow requires an active Admin when run through an Agent, beyond the minimum role of a generic management method in the matrix. The Agent must control the target. Deleting the selected Agent itself runs as You only: the immutable owner must be an actual controller, all three funding accounts must be observed empty, and unresolved funding blocks preparation.
The review binds target, executor, ledger recipient, gross cycles, live fee, recovery budget, installed module hash, and management version. The recovery budget is 1 TC plus the freezing reserve; the recipient receives the reviewed gross deposit less the ledger fee. Remaining canister cycles are lost after deletion.
Execution records its identity before external effects, stops the target, takes an original snapshot when code exists, and installs only the authenticated current withdrawal module. That module checks live fee, executor-controller authority, and recovery budget before depositing. Deletion follows verified deposit receipt and exact ledger evidence. The retained budget pays recovery and management calls.
The module’s immutable 32-byte memo is retained with its initialized intent. Deposit and verification use those exact bytes from the authenticated receipt. A frontend re-encoding, caller-chosen memo, or unrelated block is not proof of withdrawal. Repeated inspection submits no new deposit.
Restoration is allowed before financial dispatch, or after authoritative preflight failure proves no deposit was dispatched. It loads the original snapshot, or removes withdrawal code if the original canister was empty. Originally running code can resume only after restore and Start acknowledgments. Cancellation before replacement leaves an acknowledged Stop in effect.
The snapshot captures the stopped application; running state can change before Stop completes. Unknown Stop never adopts a newer version or repeats Stop; later version drift blocks replacement. Uncertain snapshot load, original-runtime Start, deposit, and deletion remain for reconciliation rather than replay.
Receipts for operations run as You bind the original workspace, network, endpoint, caller, and target; Agent execution retains a backend job. Receipts contain no credentials, private arguments, or Wasm. Restoring an Agent snapshot retains its prepared self-deletion job and does not release mutation containment. Empty-account checks do not lock out later credits: stop external funding and recheck all three accounts before removal. Follow the deletion guide.