Ghost Shell
A native SSH & SFTP desktop client by Ghost Compiler
Download · Install · Develop · How it works
| App name | Ghost Shell |
| Publisher | Ghost Compiler |
| Bundle ID | com.ghostcompiler.ghost-shell |
| Platforms | Windows · macOS · Linux |
Ghost Shell is a local-first SSH client. Your hosts, keys, and passwords live in an encrypted vault on your machine. The app unlocks once per session (or automatically via OS keychain / session file), then gives you host management, an encrypted keychain, interactive terminal tabs, session logs, and vault import/export.
┌─────────────────────────────────────────────────────────────┐
│ React UI (Vite) │
│ hosts · keychain · terminal · logs · import/export · login │
└───────────────────────────┬─────────────────────────────────┘
│ Tauri IPC (invoke + channels)
┌───────────────────────────▼─────────────────────────────────┐
│ Rust backend (src-tauri) │
│ vault · secure_store · ssh · google_drive · supabase │
└───────────────────────────┬─────────────────────────────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
vault.enc OS keychain Remote SSH/SFTP
(AES-256-GCM) session unlock (russh)
- Frontend — React pages under
src/pages/, shared UI insrc/components/, global state insrc/provider/. - Backend — Rust commands in
src-tauri/src/lib.rs; SSH sessions stream terminal I/O over Tauri channels. - Storage — Encrypted
vault.encin the app data directory; optional cloud sync via Supabase (credentials baked in at CI build time).
flowchart TD
A[App launch] --> B{Vault exists?}
B -->|No| C[Setup — create master passphrase]
B -->|Yes| D[try_auto_unlock]
D -->|Success| E[Dashboard unlocked]
D -->|Fail| F[Unlock screen — passphrase or reset]
C --> E
F -->|Unlock| E
F -->|Reset| C
E --> G[Hosts / Keys / Terminal / Logs / Settings]
G --> H[Open SSH session]
H --> I{Credentials stored?}
I -->|Yes| J[Connect]
I -->|No| K[Auth prompt — password or key passphrase]
K -->|Save toggle on| L[Store credential in vault after success]
K --> J
J --> M[Interactive xterm terminal]
- No vault file exists → user is sent to Login / Setup.
- User creates a master passphrase (minimum strength enforced in UI).
- Rust derives a key (PBKDF2 + AES-256-GCM) and creates
vault.enc. - Session key is saved to OS keychain (with
session.datfallback on Windows).
vault_exists→try_auto_unlockreads keychain / session file.- If auto-unlock succeeds → dashboard opens immediately.
- If it fails → Keychain unlock screen (passphrase recovery or wipe).
| Area | What it does |
|---|---|
| Hosts | Add/edit/delete servers; optional stored password; assign SSH keys |
| Keychain | Generate or import keys; optional passphrase storage |
| Terminal | Tabbed SSH sessions (xterm.js); reconnect; session persistence |
| Logs | Full session scrollback (7-day retention); reconnect from history |
| Import / Export | Encrypted .enc vault backup and restore |
| Settings | Theme, cloud sync, wipe data |
- User opens a host →
TerminalProvidercreates a session tab. - Rust loads host + key from vault →
ssh_connectvia russh. - Status events (
resolve→tcp→handshake→auth→pty→connected) stream to the terminal. - If credentials are missing → modal prompts for password or key passphrase (optional Save passphrase toggle).
- Keystrokes are batched to Rust; output streams back over a channel.
- On cancel → session shows Connection canceled by user; on bad credentials → Authentication failed.
- Master passphrase never stored in plaintext.
- Host passwords and key passphrases stored inside the encrypted vault.
- Auto-unlock uses OS keychain (
GhostShellservice) or encrypted session file. - Production builds disable browser devtools / right-click inspect.
- Vault export uses the same encryption as the live vault (or backup passphrase on import).
CI builds run on every push; releases are published from main, version tags (v*), or manual workflow dispatch.
| Platform | Architecture | File |
|---|---|---|
| Windows | x64 | Ghost Shell_<ver>_x64-setup.exe |
| Windows | ARM64 | Ghost Shell_<ver>_arm64-setup.exe |
| Windows | x64 / ARM64 | Ghost Shell_<ver>_<arch>_en-US.msi |
| macOS | Apple Silicon | Ghost Shell_<ver>_aarch64.dmg |
| macOS | Intel | Ghost Shell_<ver>_x64.dmg |
| macOS | Universal | Ghost Shell_<ver>_universal.dmg |
| Linux | x86_64 | .AppImage · .deb · .rpm |
<ver> is the semver from package.json (e.g. 1.0.0).
Note: All release builds are unsigned. Your OS may warn on first launch — see Installation below.
- Download
Ghost Shell_<ver>_x64-setup.exe(orarm64on ARM PCs). - If SmartScreen shows "Windows protected your PC", click More info → Run anyway.
- Complete the installer.
Silent MSI install (IT / managed):
msiexec /i "Ghost Shell_1.0.0_x64_en-US.msi" /qn- Open the
.dmgand drag Ghost Shell to Applications. - Clear quarantine (unsigned builds):
xattr -dr com.apple.quarantine "/Applications/Ghost Shell.app" - On macOS 15+, use System Settings → Privacy & Security → Open Anyway if Gatekeeper blocks the first launch.
AppImage:
chmod +x "Ghost Shell_1.0.0_amd64.AppImage"
./"Ghost Shell_1.0.0_amd64.AppImage"Debian / Ubuntu:
sudo apt install "./Ghost Shell_1.0.0_amd64.deb"Fedora / RHEL:
sudo dnf install "./Ghost Shell-1.0.0-1.x86_64.rpm"- Node.js 20+ (CI uses 24)
- Rust stable + Tauri prerequisites
Create a .env file in the project root for local dev (not committed):
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
VITE_GITHUB=https://github.com/GhostCompilerVite embeds VITE_* variables at build time. CI injects the Supabase keys from the PROD GitHub environment instead.
All project tasks go through scripts/ghost.js:
npm run ghost dev # install deps + Tauri dev (Ctrl+R restart, Ctrl+C quit)
npm run ghost build # build for current OS
npm run ghost build win:64 # Windows x64 (.exe + .msi)
npm run ghost build linux # Linux AppImage + deb + rpm
npm run ghost build mac # all macOS targets
npm run ghost icon # regenerate icons from src/assets/app-icon.png| Target | Output |
|---|---|
(none) / linux |
Current OS installers |
win:64 |
Windows x64 .exe + .msi |
win:arm |
Windows ARM64 .exe + .msi |
win |
Both Windows architectures |
mac:intel / mac:arm / mac:universal |
macOS .dmg |
mac |
All macOS variants |
Final artifacts are flattened into build/; intermediates (src-tauri/target, dist) are removed automatically.
build/
├── Ghost Shell_1.0.0_x64-setup.exe
├── Ghost Shell_1.0.0_x64_en-US.msi
├── Ghost Shell_1.0.0_amd64.AppImage
├── Ghost Shell_1.0.0_amd64.deb
└── Ghost Shell-1.0.0-1.x86_64.rpm
ghost-shell/
├── .github/workflows/build.yml # CI: parallel builds + releases
├── scripts/
│ └── ghost.js # dev / build / icon CLI
├── src/ # React frontend
│ ├── pages/ # hosts, keychain, logs, login, …
│ ├── provider/ # security, terminal, theme
│ ├── components/ # UI + terminal-view
│ └── layouts/ # dashboard shell
├── src-tauri/ # Rust / Tauri backend
│ ├── src/ # vault, ssh, secure_store, …
│ ├── tauri.conf.json # shared bundle + branding
│ ├── tauri.windows.conf.json # NSIS / WiX settings
│ └── tauri.linux.conf.json # deb / rpm metadata
└── package.json
Workflow: .github/workflows/build.yml
| Job | Runner | Produces |
|---|---|---|
linux |
ubuntu-22.04 |
AppImage, deb, rpm |
windows-x64 |
windows-latest |
NSIS .exe, WiX .msi |
windows-arm64 |
windows-latest |
NSIS .exe, WiX .msi |
macos-* |
macos-latest |
DMG per architecture |
All build jobs use the PROD GitHub environment. Required secrets:
| Secret | Purpose |
|---|---|
VITE_SUPABASE_URL |
Supabase project URL (baked into release builds) |
VITE_SUPABASE_PUBLISHABLE_KEY |
Supabase publishable key (baked into release builds) |
Release job runs when:
- A
v*tag is pushed, or mainbuilds succeed, or- Manual dispatch with Publish release enabled
Artifacts are merged and uploaded to GitHub Releases as v<package.json version>.
Release installers are not code-signed:
| Platform | What to expect |
|---|---|
| Windows | SmartScreen "Windows protected your PC" — click More info → Run anyway |
| macOS | Gatekeeper block on first open — clear quarantine or use Open Anyway in System Settings |
| Linux | Packages install normally; no publisher signature |
Code signing (Windows Authenticode, Apple notarization, Linux GPG) is on the roadmap for a future release.
| Layer | Technology |
|---|---|
| Shell | Tauri 2 (Rust) |
| SSH | russh |
| Terminal | xterm.js |
| Frontend | React 19 · Vite · React Router |
| UI | Tailwind CSS 4 · shadcn/ui |
| Crypto | AES-256-GCM vault · PBKDF2 · OS keychain |
| Cloud sync | Supabase |
- Cross-platform shell, routing, theming
-
ghostdeveloper CLI + parallel CI - SSH terminal sessions + session logs
- Encrypted vault, keychain, host management
- Import / export, auto-unlock, Supabase cloud sync
- SFTP file browser & transfers
- Code signing & notarization (Windows, macOS, Linux)
- Fork the repo and create a feature branch.
npm run ghost dev— make your changes.npm run ghost buildon your platform.- Open a PR with a clear description.
Source-available under the Ghost Shell License.
You may use, modify, and redistribute the source. The product name Ghost Shell, the publisher Ghost Compiler, and the copyright notice must be preserved. Rebranding requires prior written permission.
