Installation and builds

Install the published preview on Windows x64, Linux x86_64, or macOS (Intel or Apple silicon), or build ShellCanvas from source.

Prerequisites

To install the release:

• Windows x64, Linux x86_64, or macOS on Intel or Apple silicon.
• On Windows, the Microsoft Edge WebView2 runtime, which Windows 11 includes. On older Windows it is often already present; if ShellCanvas opens a blank window, install the runtime from Microsoft and start it again.
• No Node.js, Rust or build tools. Use a package that matches your operating system and architecture.

To build from source, add:

• Node.js 22 or newer and Rust 1.93 or newer.
• The Tauri prerequisites for your platform, which include a C toolchain and, on Linux, the WebKitGTK development packages.
• Several gigabytes of free disk space for dependencies and build output.

Steps

Install a published package

1. Open the latest release and choose the package for your computer:

   Computer	Download
   Windows x64	.exe setup or .msi installer
   Linux x86_64	.AppImage, .deb, or .rpm
   macOS Intel	darwin-x86_64-...dmg
   macOS Apple silicon	darwin-aarch64-...dmg

2. Compare the file's SHA-256 hash with the matching line in SHA256SUMS.txt (Windows), SHA256SUMS-linux-x86_64.txt, SHA256SUMS-darwin-x86_64.txt, or SHA256SUMS-darwin-aarch64.txt on the same release. For example, use Get-FileHash <file> -Algorithm SHA256 in PowerShell, sha256sum <file> on Linux, or shasum -a 256 <file> on macOS.

3. Install the package. On Windows the EXE installs for your account without administrator rights. On Linux use the package manager for DEB/RPM, or mark the AppImage executable and run it. On macOS open the DMG and copy ShellCanvas to Applications. Windows installers are not code-signed, and macOS builds are not notarized; review any operating-system warning only after checking the download.

4. Start ShellCanvas. It opens a local desktop and makes no SSH connection until you add a host.

Build and run from source

git clone https://github.com/techartdev/ShellCanvas.git
cd ShellCanvas
npm ci
npm run desktop

npm run desktop builds the Rust core, starts the frontend dev server and opens the desktop with live reload. The first build compiles the whole Rust dependency tree and takes several minutes; later runs are much faster.

Useful variants:

Command	What it does
npm run dev	Browser design preview at http://127.0.0.1:1420 with clearly labelled sample data. It cannot make SSH connections.
npm run tauri -- build --debug --no-bundle	A debug executable with the frontend embedded, at target/debug/shellcanvas.exe on Windows.
npm run release:windows	Optimised build plus the NSIS and MSI installers.
npm run verify	Formatting, frontend tests, Rust tests and Clippy. Add -- --native to also build the desktop for your platform.

Build on macOS

npm run desktop works on current macOS once the Tauri prerequisites are installed. For an Intel Mac running Catalina 10.15, use the recorded path instead:

sh scripts/build-macos-legacy.sh

That script produces an explicit debug build with a dependency-specific startup workaround. Launch, window layout and Settings have been confirmed with it on that machine; SSH workflows on the Mac client have not been validated.

Expected result

ShellCanvas opens on an empty local desktop with a dock at the bottom and Add host in the top right. No connection is made until you add one, and nothing leaves your computer before that.

From a source build, npm run desktop keeps a terminal attached: frontend changes reload immediately, and Rust changes trigger a rebuild and restart.

Limitations

• Linux and macOS need broader hands-on testing. Packages and signed updater artifacts are published, and native app-frame probes passed on Linux and Apple silicon, but real SSH and installed-app sessions have not been validated across those clients.
• Updates require your choice. The desktop checks for signed updates and offers an explicit Update and close action; it never silently installs one. The first updater-capable version must be installed manually, and installed-version upgrades still need end-to-end validation on each package family.
• Windows installers are not code-signed; macOS builds are not notarized. Managed environments may block them. The updater signature checks package integrity but is separate from operating-system publisher signing.
• Debug and release builds share stored data on the same machine — saved hosts, preferences and installed apps — because they use the same application identifier. Running a development build against your everyday data is therefore not risk-free.
• The browser preview is not the product. It renders the interface with sample data for design work and cannot connect to a server.

Related guides

• Requirements and compatibility — the server side and the tested matrix.
• Your first connection — what to do once it starts.
• Build, test and contribute — the full verification workflow for contributors.