ShellCanvas / docs

Appearance

Install and update apps ​

App Manager adds apps to your desktop from a package file or a public GitHub repository. Every install shows exactly what the app is and what it may access, and you approve it before anything runs.

Prerequisites ​

ShellCanvas on Windows, where installed apps are supported. Apps that need a host — files, a console, remote settings — also need a connected workspace, but installing one does not.

Steps ​

Install from a package file ​

  1. Open App Manager from the dock, then Add apps.
  2. Under From an app package, choose Choose package… and select a .shellcanvas.json file.
  3. Review the app: its title, version, identifier, which clients it supports, and the access it asks for, phrased in plain terms such as Open and control remote consoles. A package fingerprint is shown, with a note that it identifies the reviewed content and does not verify a publisher.
  4. Choose Install app. It appears in the launcher, the dock and the Installed list.

Install from GitHub ​

  1. In Add apps, under From GitHub, enter the repository as owner/repository and a branch, tag or commit.
  2. Choose Review app. ShellCanvas fetches the repository's shellcanvas.repo.json descriptor, downloads the package it names, checks the package's SHA-256 against the descriptor, and confirms that the identity matches before showing you the same review screen.
  3. Choose Install app.

Nothing is built or executed during installation: no npm scripts, no repository checkout, no tokens. Prefer a tag or commit over a branch — a branch that moves between the two downloads produces a hash mismatch, which is refused rather than bypassed.

Update ​

Open the app's entry in Installed and choose Check for update, which works for apps installed from GitHub. An update is reviewed like a new install, and newly requested permissions start unselected — you approve them deliberately.

Windows that are already open keep running the version and permissions they started with. The new version is used the next time the app opens.

Disable or remove ​

Disable stops new launches while leaving the app and its data in place. Remove deletes it, and is refused while any of its windows is open:

Close this app's running windows before removing it. Disable it to stop new launches while keeping those windows.

Removing an app retires its installation identity: a later reinstall starts with empty storage and no access to the previous installation’s saved connections. This does not itself erase the old local records or credential-store entries. Export any data you need and use the app’s connection-forgetting controls before removal if you want its saved credentials removed.

Expected result ​

Installed apps appear alongside the built-in ones in the launcher and the dock, run in their own windows, and can only do what you approved. An app that is not compatible with your platform is shown as Incompatible and cannot be enabled or launched.

Limitations ​

  • Installed apps run on Windows. App frames are validated there; on other native platforms they are gated off.
  • Public repositories only for the GitHub route. Private repositories need a package file instead.
  • Redirects are not followed, and the download has its own bounds: the descriptor at most 64 KiB, the package at most 32 MiB, four downloads at a time.
  • A hash is not a signature. It proves the bytes match the descriptor, not who wrote them. Install apps you have reason to trust.
  • No marketplace, no rollback tooling, no publisher verification yet.
  • An update cannot silently gain access. New permissions require your approval, and running windows keep their old grants until they close.

ShellCanvas documentation

© 2026 ShellCanvas