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 0.1.13 or newer on Windows, Linux or macOS, 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

Review a recommended app

On Installed, the Recommended by ShellCanvas section shows curated app repositories, including Canvas Assistant. Choose Review on a suggestion to fetch its current package and inspect the version and requested access; nothing installs until you approve the normal app review. Recommendations come from the ShellCanvas catalog on main and can change without a desktop release. Curation does not authenticate the app publisher.

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, Linux and macOS. Native frame probes passed on all three, including Apple silicon; broader live sessions on Linux and macOS remain to be tested. Native adapters additionally need a package for your OS and CPU architecture.
• 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.
• Recommended repositories are suggestions, not publisher verification. There is no rollback tooling or publisher-authenticated marketplace yet.
• An update cannot silently gain access. New permissions require your approval, and running windows keep their old grants until they close.

Related guides

• Extension permissions and trust — what each permission means.
• Canvas Assistant — installing a real app from GitHub.
• App installation and permissions — when an install is refused.
• Build your first app — making one of your own.