GitHub - vachanmn123/pixieterm-desktop: PixieTerm's Desktop Client

4 min read Original article ↗

A secure, cross-platform SSH terminal manager built with Wails v2, combining a Go backend with a modern React frontend.

Features

  • Secure SSH Management: Connect to remote hosts via SSH with encrypted credential storage
  • Terminal Emulation: Full-featured terminal powered by xterm.js
  • Credential Security: Master password-protected encryption using AES-GCM and system keyring
  • SSH Key Management: Store and manage SSH private keys securely
  • Session Management: Track and manage multiple SSH sessions
  • Modern UI: Clean, responsive interface built with shadcn/ui and Tailwind CSS

Technology Stack

Backend

  • Go 1.25: Core application logic
  • Wails v2.11: Desktop framework bridging Go and React
  • go-keyring: Secure credential storage using system keychain
  • golang.org/x/crypto: SSH client and encryption

Frontend

  • React 19: UI framework
  • TypeScript 6: Type-safe development
  • Vite 8: Fast build tooling
  • Redux Toolkit: Global state management
  • TanStack React Query: Server state and data fetching
  • Tailwind CSS v4: Utility-first styling
  • shadcn/ui: Component library (Radix Nova)
  • xterm.js: Terminal emulator

Prerequisites

  • Go 1.25+: Download Go
  • Bun: Install Bun (Note: This project uses Bun, not npm/yarn)
  • Wails CLI: Install with go install github.com/wailsapp/wails/v2/cmd/wails@latest

Platform-Specific Requirements

macOS: Xcode Command Line Tools

Linux: Standard build tools

# Debian/Ubuntu
sudo apt-get install build-essential libgtk-3-dev libwebkit2gtk-4.0-dev

# Fedora
sudo dnf install gtk3-devel webkit2gtk3-devel

Windows: No additional requirements (Go + Wails CLI is sufficient)

Installation

  1. Clone the repository
git clone <repository-url>
cd pixieterm-desktop
  1. Install frontend dependencies
cd frontend
bun install
cd ..
  1. Install Go dependencies

Development

Start Development Server

This starts the Wails dev server with hot reload for both Go and React. The app will automatically reload when you make changes.

Frontend-Only Development

If you're only working on UI components without Go integration:

Access at http://localhost:5173

Development with Browser DevTools

Connect to http://localhost:34115 in your browser to call Go methods from browser devtools.

Building

Production Build

Creates a redistributable package in the build/bin directory.

Platform-Specific Builds

# macOS (creates .app bundle)
wails build -platform darwin/universal

# Windows (creates .exe)
wails build -platform windows/amd64

# Linux (creates binary)
wails build -platform linux/amd64

Frontend Preview

Preview the production frontend build:

cd frontend
bun run build
bun run preview

Project Structure

pixieterm-desktop/
├── frontend/              # React + TypeScript frontend
│   ├── src/
│   │   ├── components/    # React components
│   │   │   └── ui/        # shadcn/ui components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── lib/           # Utility functions
│   │   ├── pages/         # Page components
│   │   └── store/         # Redux store and slices
│   └── wailsjs/           # Auto-generated Wails bindings
├── managers/              # Go backend managers
│   ├── api.go             # API client with auto-token refresh
│   ├── auth.go            # Authentication manager
│   ├── encryption.go      # AES-GCM encryption
│   ├── hosts.go           # SSH hosts management
│   ├── keys.go            # SSH keys management
│   └── secureStore.go     # Keyring storage
├── app.go                 # Main Wails app struct
├── main.go                # Go entry point
└── wails.json             # Wails configuration

Architecture

Backend Managers

The Go backend uses a manager pattern for separation of concerns:

  • AuthManager: Handles user authentication and session management
  • APIManager: HTTP client with automatic token refresh
  • EncryptionManager: AES-GCM encryption/decryption with master password
  • HostsManager: SSH host configuration and connection management
  • KeysManager: SSH private key storage and retrieval
  • SecureStoreManager: Interface to system keyring (Keychain on macOS)

Frontend State

  • Redux Toolkit: Global app state (auth, sessions)
  • React Query: Server state and data fetching with caching
  • useState: Component-local UI state

Security Model

  1. Master password is never stored - only used to derive encryption keys
  2. Sensitive data encrypted with AES-GCM before storage in system keyring
  3. API tokens stored securely and automatically refreshed
  4. SSH credentials encrypted at rest

Configuration

Edit wails.json to configure the application:

  • Window size and behavior
  • Build settings
  • Asset handling

Full configuration reference: Wails Project Config

Testing

Note: No test framework is currently configured.

To add testing:

  • Frontend: Consider Vitest + React Testing Library
  • Backend: Use Go's built-in testing: go test ./...

Contributing

When contributing:

  1. Use bun for all package operations (not npm/yarn)
  2. Follow existing code style (see AGENTS.md for detailed guidelines)
  3. Never edit frontend/wailsjs/ - these are auto-generated
  4. Always handle errors explicitly in both Go and TypeScript
  5. Write clear commit messages describing the "why"

Common Issues

Wails bindings not updating

# Bindings are auto-generated when running:
wails dev

Package installation issues

Make sure you're using Bun, not npm:

cd frontend
bun install  # Correct
npm install  # Don't use this

Build errors

Ensure all prerequisites are installed and up to date:

wails doctor  # Check Wails installation
go version    # Should be 1.25+
bun --version # Should be installed

Resources

License

This project is licensed under the MIT License - see the LICENSE file for details.