Installation

Kassie can be installed in multiple ways. Choose the method that works best for you.

Curl Install Script (Recommended)

Quick installation via curl for Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/KashifKhn/kassie/main/install.sh | sh

This script will:

1. Detect your OS and architecture
2. Download the latest release from GitHub
3. Install to /usr/local/bin or ~/.local/bin
4. Configure your PATH automatically
5. Verify the installation

To install a specific version:

curl -fsSL https://raw.githubusercontent.com/KashifKhn/kassie/main/install.sh | sh -s -- --version 0.1.1

To skip PATH modification:

curl -fsSL https://raw.githubusercontent.com/KashifKhn/kassie/main/install.sh | sh -s -- --no-modify-path

Go Install

If you have Go installed (1.24+):

go install github.com/kashifKhn/kassie@latest

Make sure $GOPATH/bin is in your PATH:

export PATH=$PATH:$(go env GOPATH)/bin

To install a specific version:

go install github.com/kashifKhn/kassie@v0.1.1

Homebrew (Coming Soon)

Coming Soon

Homebrew tap is planned for a future release. Use the curl install script or Go install for now.

# Coming soon
brew tap KashifKhn/kassie
brew install kassie

Pre-built Binaries

Download pre-built binaries from GitHub Releases:

Asset Naming

Release assets use the format: kassie_VERSION_OS_ARCH.tar.gz
Example: kassie_0.1.1_linux_amd64.tar.gz

Linux (amd64)

curl -L https://github.com/kashifKhn/kassie/releases/download/v0.1.1/kassie_0.1.1_linux_amd64.tar.gz | tar -xz
chmod +x kassie
sudo mv kassie /usr/local/bin/

Linux (arm64)

curl -L https://github.com/kashifKhn/kassie/releases/download/v0.1.1/kassie_0.1.1_linux_arm64.tar.gz | tar -xz
chmod +x kassie
sudo mv kassie /usr/local/bin/

macOS (Intel)

curl -L https://github.com/kashifKhn/kassie/releases/download/v0.1.1/kassie_0.1.1_darwin_amd64.tar.gz | tar -xz
chmod +x kassie
sudo mv kassie /usr/local/bin/

macOS (Apple Silicon)

curl -L https://github.com/kashifKhn/kassie/releases/download/v0.1.1/kassie_0.1.1_darwin_arm64.tar.gz | tar -xz
chmod +x kassie
sudo mv kassie /usr/local/bin/

Windows (amd64)

Download the .zip file from releases and extract it.

Or using PowerShell:

Invoke-WebRequest -Uri https://github.com/kashifKhn/kassie/releases/download/v0.1.1/kassie_0.1.1_windows_amd64.zip -OutFile kassie.zip
Expand-Archive -Path kassie.zip -DestinationPath .
Move-Item kassie.exe C:\Windows\System32\

Docker

Web UI Under Development

Docker images currently support TUI and server modes. Web UI support is coming in Phase 5.

Run Kassie in a container:

TUI

docker run -it ghcr.io/kashifkhn/kassie:latest tui

With a custom config file:

docker run -it \
  -v ~/.config/kassie:/root/.config/kassie \
  ghcr.io/kashifkhn/kassie:latest tui

Server Mode

docker run -p 50051:50051 -p 8080:8080 \
  ghcr.io/kashifkhn/kassie:latest server

Building from Source

If you want to build Kassie yourself:

Prerequisites

• Go 1.24+
• Node.js 20+ (for web UI)
• protoc (Protocol Buffer compiler)
• Make

Clone and Build

# Clone repository
git clone https://github.com/kashifKhn/kassie.git
cd kassie

# Setup dependencies
make setup

# Generate protobuf code
make proto

# Build full binary (includes web UI)
make build

# Binary will be at ./kassie
./kassie version

Build Options

Build server only (no web assets):

make build-server

Build web UI only:

make web

Development build (faster, no optimization):

go build -o kassie cmd/kassie/main.go

Verification

After installation, verify that Kassie is working:

kassie version

Expected output:

Kassie v0.3.0
Commit: 23a21f1
Built: September 8, 2026

Test connectivity:

kassie tui --help

Platform-Specific Notes

macOS Gatekeeper

If you download a binary directly, macOS may block it:

xattr -d com.apple.quarantine /usr/local/bin/kassie

Or right-click the binary, select "Open", and confirm.

Linux: No sudo Required

Install to user directory without sudo:

mkdir -p ~/bin
mv kassie ~/bin/kassie
export PATH=$PATH:~/bin

Add the export to your ~/.bashrc or ~/.zshrc.

Windows: Add to PATH

Add Kassie to your PATH via System Properties:

1. Search for "Environment Variables"
2. Edit "Path" under User variables
3. Add the directory containing kassie.exe

Upgrading Kassie

Kassie includes a built-in upgrade command that makes updating to newer versions easy and safe.

Self-Upgrade Command

Upgrade to the latest version:

kassie upgrade

The upgrade process will:

1. Check for the latest release on GitHub
2. Download and verify the new version
3. Create a backup of your current binary
4. Install the new version
5. Verify the installation works
6. Automatically rollback if anything fails

Check for Updates

To only check if an update is available without installing:

kassie upgrade --check

Output:

🎯 Kassie Upgrade
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Current version: v0.1.0
  Latest version:  v0.1.1
  ✓ Update available

Upgrade to Specific Version

Install or downgrade to a specific version:

kassie upgrade --version v0.1.0

This is useful for:

• Downgrading if a new version has issues
• Installing a specific tested version in production
• Testing different versions

Force Reinstall

Reinstall the current version (useful for fixing corrupted installations):

kassie upgrade --force

JSON Output

For scripting and automation:

kassie upgrade --check --json

Output:

{
  "current_version": "v0.1.0",
  "latest_version": "v0.1.1",
  "update_available": true,
  "platform": {
    "os": "linux",
    "arch": "amd64"
  }
}

Upgrade via Curl Script

The install script also works for upgrades:

curl -fsSL https://raw.githubusercontent.com/KashifKhn/kassie/main/install.sh | sh

Upgrade with Homebrew (Coming Soon)

Once Homebrew tap is available:

brew upgrade kassie

Upgrade with Go Install

If installed via go install, simply run:

go install github.com/kashifKhn/kassie@latest

Next Steps

Now that Kassie is installed:

• Getting Started - Quick tutorial
• Configuration - Set up your profiles
• TUI Usage - Learn the terminal interface

Troubleshooting

Command not found

If you get "command not found" after installation:

Go Install: Ensure $GOPATH/bin is in your PATH:

echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc

Curl Install: The script should automatically configure PATH. If not:

echo 'export PATH=$PATH:~/.local/bin' >> ~/.bashrc
source ~/.bashrc

Permission Denied

If you get permission errors:

chmod +x /path/to/kassie

SSL Certificate Errors (Go Install)

If go install fails with SSL errors:

go env -w GOPRIVATE=github.com/kashifKhn/kassie
go install github.com/kashifKhn/kassie@latest

For more help, see Troubleshooting.