Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation

Wassette is available for Linux, macOS, and Windows. Choose the installation method that best suits your platform and workflow.

Quick Start

For the fastest installation experience, we recommend:

  • Linux/macOS: Use our one-liner install script
  • macOS: Use Homebrew
  • Windows: Use WinGet
  • Nix users: Use Nix flakes

Installation by Platform

The easiest way to install Wassette on Linux is using our automated install script:

curl -fsSL https://raw.githubusercontent.com/microsoft/wassette/main/scripts/install.sh | bash

This script will:

  • Automatically detect your system architecture (x86_64 or ARM64)
  • Download the latest Wassette release
  • Install the binary to ~/.local/bin
  • Configure your shell PATH for immediate access

Homebrew

If you prefer using Homebrew on Linux:

brew install wassette

Wassette is available in homebrew/core, so no tap is required. Bottles are published for both x86_64 and ARM64 Linux.

Manual Download

You can also download the latest Linux release manually from the GitHub Releases page and add it to your $PATH.

Homebrew Tap (Alternative)

brew install wassette installs from homebrew/core and is the recommended path on both macOS and Linux. This repository also maintains its own formula, which you can use if you need a version that is not yet in homebrew/core:

brew tap microsoft/wassette https://github.com/microsoft/wassette
brew install microsoft/wassette/wassette

Note the fully qualified formula name: Homebrew resolves the bare name wassette to homebrew/core even when the tap is installed, so brew install wassette will not pick up the tap’s formula.

Verifying the Installation

After installation, verify that Wassette is properly installed and accessible:

wassette --version

This should display the installed version of Wassette.

Supported Platforms

Wassette supports the following platforms:

Operating SystemArchitectureSupport
Linuxx86_64 (amd64)✅ Full support
LinuxARM64 (aarch64)✅ Full support
macOSIntel (x86_64)✅ Full support
macOSApple Silicon (ARM64)✅ Full support
Windowsx86_64✅ Full support
WindowsARM64✅ Full support
Windows Subsystem for Linuxx86_64, ARM64✅ Full support

Next Steps

Once Wassette is installed, you’ll need to configure it with your AI agent:

  1. Configure with your AI agent: Follow the MCP clients setup guide for instructions on integrating Wassette with:

    • Visual Studio Code
    • Cursor
    • Claude Code
    • Gemini CLI

  2. Load your first component: Try loading a sample component to verify everything works:

    Please load the time component from oci://ghcr.io/microsoft/time-server-js:latest

  3. Explore examples: Check out the examples directory for sample components in different languages.

Troubleshooting

Command not found

If you get a “command not found” error after installation:

  • Linux/macOS: Ensure ~/.local/bin is in your PATH. You may need to restart your terminal or run:

    export PATH="$HOME/.local/bin:$PATH"

  • Windows: Ensure the installation directory is in your system PATH. You may need to restart your terminal or log out and back in.

Permission denied

If you encounter permission errors:

  • Linux/macOS: Ensure the binary has execute permissions:

    chmod +x ~/.local/bin/wassette

  • Windows: Run PowerShell as Administrator when installing with WinGet.

Other Issues

For additional help:

  • Check the FAQ for common questions and answers
  • Visit our GitHub Issues page
  • Join our community discussions

Upgrading

To upgrade to the latest version of Wassette:

  • Homebrew: brew update && brew upgrade wassette
  • WinGet: winget upgrade Wassette
  • Install script: Re-run the install script
  • Nix: nix profile upgrade github:microsoft/wassette
  • Manual: Download the latest release and replace your existing binary