Installation

Choose your installation method: download pre-built binaries for your platform or build from source. Both paths are fully supported.

System Requirements

Tempest is a native desktop application built with Tauri and React. Minimum requirements vary by platform.

Windows
macOS
Linux

Installation from Pre-built Binaries

Pre-built installers are available for all platforms. Download from the GitHub Releases page.

Windows
macOS
Linux

Windows Installer (.exe)

Download the installer

From Releases, download the file named tempest_x.x.x_x64-setup.exe (where x.x.x is the version number).

Verify WebView2 Runtime (optional but recommended)

Tempest requires the WebView2 Runtime to render its UI. Check if it is already installed:

Press Win + R, type appwiz.cpl, and press Enter to open Programs and Features
Search for “WebView2” in the list

If not found, download and install from Microsoft Edge WebView2. Click “Evergreen Standalone Installer (x64)”. The installer runs silently in the background.

Run the installer

Double-click tempest_x.x.x_x64-setup.exe. The NSIS installer window appears. Follow the on-screen prompts. By default, Tempest installs to C:\Users\[YourUsername]\AppData\Local\Programs\Tempest.

Launch Tempest

After installation, Tempest appears in your Start Menu as “Tempest”. Click to launch. A frameless window opens with the workspace management interface.

Enable long paths (for large codebases)

If working with repositories containing very long file paths, Windows may limit path length to 260 characters by default. To enable long paths:

Set-ItemProperty -Path “HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem” -Name “LongPathsEnabled” -Value 1

Also configure Git:

git config —global core.longpaths true

Restart Tempest after this change.

Uninstalling

Go to Settings > Apps > Apps and features, search for “Tempest”, and click “Uninstall”. Configuration and workspace data are preserved in %APPDATA%\Tempest\ and can be manually removed if desired.

macOS Installer (.dmg)

Check architecture

Determine your Mac’s architecture:

arch

Output is either arm64 (Apple Silicon M1/M2/M3) or i386 (Intel). Tempest binaries are available for both.

Download the disk image

From Releases, download:

tempest.app.tar.gz for your architecture (universal binary)
Or the .dmg file if available (drag-and-drop installer)

Mount the disk image or extract the archive

If you downloaded the .dmg:

Double-click to mount
Drag the Tempest app icon to the Applications folder

If you downloaded the .tar.gz:

tar -xzf tempest.app.tar.gz
mv Tempest.app /Applications/

Grant security exceptions

On first launch, macOS may block the app due to notarization. To allow it:

Open Finder, navigate to Applications
Right-click Tempest.app, select “Open”
Click “Open” in the security prompt
The app launches. You won’t see this prompt again.

Alternatively, allow unsigned apps system-wide (not recommended):

sudo spctl —master-disable

Launch Tempest

Open Applications folder and double-click Tempest.app, or use Spotlight (Cmd+Space) and type “Tempest”.

Uninstalling

Drag Tempest.app to Trash. Configuration and workspace data are stored in ~/Library/Application Support/Tempest/ and can be manually deleted if desired.

Linux: AppImage Portable Executable

Download the AppImage

From Releases, download tempest_x.x.x_amd64.AppImage.

Make executable

chmod +x tempest_x.x.x_amd64.AppImage

Run directly

./tempest_x.x.x_amd64.AppImage

The app launches in a window. No installation required. You can keep the AppImage file anywhere (Documents, Downloads, a custom bin directory).

Optional: Install to system path

sudo mv tempest_x.x.x_amd64.AppImage /usr/local/bin/tempest
chmod +x /usr/local/bin/tempest

Then run with:

tempest

Optional: Create desktop shortcut

Create ~/.local/share/applications/tempest.desktop:

[Desktop Entry]
Type=Application
Name=Tempest
Exec=/path/to/tempest_x.x.x_amd64.AppImage
Icon=tempest
Categories=Development;Utility;

Then update the desktop database:

update-desktop-database ~/.local/share/applications/

The app appears in your application launcher.

Linux: .deb Package

Download the package

From Releases, download tempest_x.x.x_amd64.deb.

Install

sudo dpkg -i tempest_x.x.x_amd64.deb

If dependency errors appear, run:

sudo apt-get install -f

Launch

tempest

Or find “Tempest” in your application launcher.

Uninstall

sudo apt-get remove tempest

Building from Source

Build Tempest locally if you want the latest development features, plan to contribute, or prefer compiling on your machine.

Prerequisites

Install these tools first. The exact steps vary by platform.

Windows
macOS
Linux

Windows Prerequisites

Node.js 18 or later

Download from nodejs.org. Choose the LTS version (currently 22.x).
Run the installer. Accept all defaults (npm is included).
Verify installation:

node —version
npm —version

Both commands should print version numbers. Node 18.0.0 or later is required. Node 22+ is recommended.

Rust 1.77 or later

Download and run the Rust installer from rustup.rs.
Choose the default option (standard installation).
Verify installation:

rustc —version
cargo —version

Both should print version 1.77.0 or later. Rust updates itself automatically via rustup.

Git

Download from git-scm.com.
Run the installer and accept defaults.
Verify:

git —version

WebView2 Runtime

Download and install from Microsoft Edge WebView2. Choose “Evergreen Standalone Installer (x64)”. The installer runs silently.

Visual C++ Build Tools (if missing)

Some Rust crates require the MSVC compiler. If you see errors like “Microsoft Visual C++ 14.0 or greater is required”, download the Visual C++ Build Tools from Microsoft. Choose “Desktop development with C++”. This is a 1.5 GB download; installation takes 5 minutes.

Linux Prerequisites (Ubuntu 22.04 LTS and Debian-based)

System packages

sudo apt-get update
sudo apt-get install -y 

libwebkit2gtk-4.1-dev 

libappindicator3-dev 

librsvg2-dev 

patchelf 

libxdo-dev 

curl

These libraries are required for Tauri and native windowing. Breakdown:

libwebkit2gtk-4.1-dev: WebKit rendering engine
libappindicator3-dev: System tray integration
librsvg2-dev: SVG rendering
patchelf: Binary patching for bundled libraries
libxdo-dev: X11 window management

Node.js 18 or later

Install via NodeSource repository (for latest LTS):

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs

Or use the Ubuntu default (older version):

sudo apt-get install -y nodejs npm

Verify:

node —version
npm —version

Should show Node 18.0.0 or later.

Rust 1.77 or later

Install via rustup:

curl —proto ‘=https’ —tlsv1.2 -sSf https://sh.rustup.rs | sh

Follow the prompts (default settings are fine). Then add Rust to your PATH:

source $HOME/.cargo/env

Verify:

rustc —version
cargo —version

Should show Rust 1.77.0 or later.

Git

sudo apt-get install -y git

Verify:

git —version

Clone and Build

Once prerequisites are installed, clone the repository and build:

Clone the repository

git clone https://github.com/gsvprharsha/tempest cd tempest

Install npm dependencies

npm install

This installs React, Tauri CLI, TypeScript, Vite, and other JavaScript dependencies. Typically takes 1-2 minutes.

Build workspace assets (Atlas)

npm run setup

This builds the Atlas workspace (code intelligence and token-graph features) and bundles them into resources. Required before running or building.

Build for production

npm run build

This step:

Compiles TypeScript and bundles the React UI with Vite
Compiles the Rust backend with Tauri
Creates platform-specific installers

Build time is 3-10 minutes depending on your machine.

Windows
macOS
Linux

Installers are created in src-tauri\target\release\bundle\nsis\:

tempest_x.x.x_x64-setup.exe (NSIS installer)
tempest_x.x.x_x64-setup.exe.sig (updater signature file)

Also created in src-tauri\target\release\:

tempest.exe (portable executable)

Installers are created in src-tauri/target/release/bundle/:

dmg/ contains Tempest_x.x.x_x64.dmg (disk image installer)
macos/ contains Tempest.app.tar.gz (compressed app bundle)

Installers are created in src-tauri/target/release/bundle/:

appimage/ contains tempest_x.x.x_amd64.AppImage (portable)
deb/ contains tempest_x.x.x_amd64.deb (package)

Run the build output

Windows
macOS
Linux

.\src-tauri\target\release\tempest.exe

A frameless Tempest window should appear with the workspace management interface.

Development Mode (with Hot Reload)

To iterate quickly on code changes:

Install prerequisites (same as above)

Ensure Node.js 18+, Rust 1.77+, and platform-specific tools are installed.

Clone and setup

git clone https://github.com/gsvprharsha/tempest cd tempest npm install npm run setup

Start development server

npm run dev

This command:

Starts the Vite dev server on http://localhost:1420
Launches the Tauri app window
Enables hot module replacement (HMR): React components, styles, and TypeScript changes reload instantly

The Rust backend recompiles automatically if you edit src-tauri/ files. The process takes a few seconds.

Edit and develop

React files in src/ reload instantly
Rust files in src-tauri/ trigger a rebuild
The window stays open and reflects changes

To stop, press Ctrl+C in the terminal.

Verifying Installation

After installation (binary or build), verify that Tempest works:

Launch the app

Open Tempest using your platform’s standard launch method (Start Menu on Windows, Applications on macOS, application launcher on Linux, or command line).

Check the welcome screen

You should see a frameless window with:

“Workspaces” header with workspace management options
Option to create a new workspace or open an existing one
Dark or light theme applied (based on system preferences)

Create a test workspace

Click “New Workspace” or similar button
Choose a local directory (or let Tempest create one)
Click “Create”

The workspace loads. You should see workspace tabs and options to run agents.

Check system info

If a system info or about screen exists, verify:

Tempest version matches the build you installed/created
Platform is correct (Windows, macOS, or Linux)

Common Issues and Fixes

Windows: WebView2 Runtime Not Found

Symptom: App crashes on launch with “WebView2 Runtime not found” or similar error. Fix:

Download WebView2 Runtime from Microsoft Edge WebView2
Click “Evergreen Standalone Installer (x64)”
Run the installer and wait for completion
Restart Tempest

Windows: Long Paths in Repository

Symptom: Git operations fail with “path too long” or “file not found” errors when the repository contains deep directory structures. Fix: Enable long paths in Windows and Git:

Set-ItemProperty -Path “HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem” -Name “LongPathsEnabled” -Value 1
git config —global core.longpaths true

Restart your terminal and Tempest.

macOS: App Blocked by Security

Symptom: “Tempest cannot be opened because it is from an unidentified developer.” Fix:

Open Finder and navigate to Applications
Right-click Tempest.app and select “Open”
Click “Open” in the security dialog

The app launches and the warning does not appear again.

Linux: Missing WebKit Libraries

Symptom: App fails to start with errors referencing “libwebkit2gtk” or “appindicator”. Fix: Install system dependencies:

sudo apt-get install -y 

libwebkit2gtk-4.1-dev 

libappindicator3-dev 

librsvg2-dev 

libxdo-dev

Then restart Tempest.

Build Fails: Rust Compilation Error

Symptom: npm run build fails with Rust compiler errors. Fix:

Ensure Rust is up to date:

rustup update

Clean and rebuild:

cd src-tauri
cargo clean
cd ..
npm run build

This removes cached build artifacts and recompiles from scratch.

Build Fails: Node or npm Not Found

Symptom: Command not found when running npm install or npm run dev. Fix:

Verify installation:

node —version
npm —version

If not found, reinstall Node.js from nodejs.org.

On Windows PowerShell, if npm is not recognized after installation, restart PowerShell or use Command Prompt (cmd.exe).

Development Server Won’t Start

Symptom: npm run dev fails or hangs without output. Fix:

Kill any existing processes using port 1420:

Windows
macOS/Linux

netstat -ano | findstr :1420
taskkill /PID [PID] /F

Rebuild workspace assets:

npm run setup
npm run dev

Installer Won’t Run on Windows

Symptom: NSIS installer (.exe) fails to execute or displays error messages. Fix:

Ensure you have administrative privileges. Right-click the .exe and select “Run as administrator”.
Check disk space. The installer requires at least 1 GB free.
Disable antivirus temporarily (some antivirus software blocks installers).
Download the installer again. The file may be corrupted.

DMG Installer Won’t Open on macOS

Symptom: “.dmg appears as a blank folder or won’t mount.” Fix:

Delete the corrupt .dmg and download again.
Alternatively, extract the .app.tar.gz file instead:

tar -xzf Tempest.app.tar.gz
mv Tempest.app /Applications/

Next Steps

Quickstart

Run Tempest in development mode or create your first workspace.

Workspaces

Learn how to create and manage parallel agent workspaces.

Theme Customization

Customize colors and typography using CSS variables.

Building from Source

Deep dive into the development setup and build process.

​Installation

​System Requirements

​Installation from Pre-built Binaries

​Windows Installer (.exe)

​Uninstalling

​macOS Installer (.dmg)

​Uninstalling

​Linux: AppImage Portable Executable

​Linux: .deb Package

​Building from Source

​Prerequisites

​Windows Prerequisites

​macOS Prerequisites

​Linux Prerequisites (Ubuntu 22.04 LTS and Debian-based)

​Clone and Build

​Development Mode (with Hot Reload)

​Verifying Installation

​Common Issues and Fixes

​Windows: WebView2 Runtime Not Found

​Windows: Long Paths in Repository

​macOS: App Blocked by Security

​Linux: Missing WebKit Libraries

​Build Fails: Rust Compilation Error

​Build Fails: Node or npm Not Found

​Development Server Won’t Start

​Installer Won’t Run on Windows

​DMG Installer Won’t Open on macOS

​Next Steps

Quickstart

Workspaces

Theme Customization

Building from Source

Installation

System Requirements

Installation from Pre-built Binaries

Windows Installer (.exe)

Uninstalling

macOS Installer (.dmg)

Uninstalling

Linux: AppImage Portable Executable

Linux: .deb Package

Building from Source

Prerequisites

Windows Prerequisites

macOS Prerequisites

Linux Prerequisites (Ubuntu 22.04 LTS and Debian-based)

Clone and Build

Development Mode (with Hot Reload)

Verifying Installation

Common Issues and Fixes

Windows: WebView2 Runtime Not Found

Windows: Long Paths in Repository

macOS: App Blocked by Security

Linux: Missing WebKit Libraries

Build Fails: Rust Compilation Error

Build Fails: Node or npm Not Found

Development Server Won’t Start

Installer Won’t Run on Windows

DMG Installer Won’t Open on macOS

Next Steps