ClusterDeck

A lightweight macOS-first desktop app for discovering, bootstrapping, and connecting to VM and Kubernetes environments.

English | 한국어

ClusterDeck is designed for environments that are frequently created, deleted, or re-addressed. It keeps a human-friendly Profile name stable while automating SSH access, optional SSH key bootstrap, Bastion/ProxyJump access, remote kubeconfig retrieval, and Kubernetes connectivity verification.

Current Status

ClusterDeck is an early MVP / source-first project. The repository currently documents and implements the workstation-access flow around Profiles, SSH, bastion/ProxyJump, kubeconfig retrieval/normalization, and Kubernetes connectivity checks.

The supported first-time path is development from source with Tauri. Do not treat packaged-app distribution, broad fleet management, or a general Kubernetes administration console as established product capabilities unless a release or repository documentation explicitly says so.

A GitHub Actions release pipeline now exists (.github/workflows/release.yml): pushing a v* tag builds a macOS .dmg (ad-hoc signed — there is no Apple Developer ID certificate yet, so macOS shows an "unidentified developer" warning on first launch) and opens it as a draft GitHub Release. No release has been published from this pipeline yet, so packaged-app distribution is still not an established path — development from source remains how to run ClusterDeck today.

What ClusterDeck Changes on Your Mac

ClusterDeck asks macOS for permission before touching anything outside its own data directory (~/.clusterdeck/). It never overwrites a file it doesn't own — it only ever writes inside a clearly marked block and leaves everything else in that file untouched. Specifically:

• Login Keychain (CA certificates) — when you choose to trust a cluster's internal CA (an opt-in action per discovered endpoint, or from Settings → Trusted CAs), ClusterDeck adds that certificate to your login keychain (never the System keychain), scoped only to the SSL/TLS trust policy. macOS will show its own authorization prompt (password or Touch ID) each time. You can inspect what's trusted in Keychain Access.app at any time, or remove it from ClusterDeck itself (Settings → Trusted CAs, or the "Remove" action on a trusted endpoint) — both properly untrust the certificate rather than just forgetting it locally.
• /etc/hosts — off by default, opt-in per Profile. When enabled, ClusterDeck writes cluster-internal domain entries inside a single marked block (# >>> ClusterDeck BEGIN (profile: <id>) >>> … # <<< ClusterDeck END (profile: <id>) <<<) via a macOS admin-privileged prompt. It only ever edits its own block for that profile.
  • Optional Gateway public address (IP): for clusters whose gateway sits behind an external load balancer (private nodes), discovered endpoints map to this IP instead of the cluster's private address.
• Local DNS (/etc/resolver/<zone>) — opt-in per Profile (host_mapping: local_dns). Recommended over /etc/hosts for full macOS Safari/Network.framework compatibility and zero-prompt record updates. Writes dedicated /etc/resolver/<zone> files pointing to a loopback-only authoritative responder (127.0.0.1:15353) run via a user LaunchAgent. See Local DNS User Guide.
• ~/.ssh/config — ClusterDeck adds one Include ~/.clusterdeck/ssh/*.conf line and keeps its own per-profile SSH options in that included directory, rather than writing directly into your config.

If you ever want to remove everything ClusterDeck has added: untrust its CAs from Keychain Access.app (or ClusterDeck's own Settings), delete the marked block(s) from /etc/hosts if you opted in, remove any marked files from /etc/resolver/, remove the Include line from ~/.ssh/config, and delete ~/.clusterdeck/.

Core Flow

IP / Host Discovery
        ↓
SSH Connectivity
        ↓
SSH Bootstrap (optional)
        ↓
SSH Alias / ProxyJump
        ↓
Remote kubeconfig Fetch
        ↓
kubeconfig Normalization
        ↓
Local Profile
        ↓
Kubernetes Connectivity Check

Screenshots

Connected profile — SSH/kubeconfig/Kubernetes status for a synced profile, plus discovered cluster endpoints with their CA trust status:

Settings — trusted CAs and the read-only Local Runtime discovery section for Colima/Lima/Vagrant:

New profile — host discovery and the opt-in bastion / bootstrap / kubeconfig / /etc/hosts settings:

Initial Scope

• macOS-first desktop application
• Tauri 2 + Rust backend
• React + TypeScript frontend
• Multi-VM host Profiles
• SSH key bootstrap and alias management
• Bastion / ProxyJump support
• Remote kubeconfig fetch and normalization
• kubectl connectivity verification
• Local VM inventory observation across Colima, VirtualBox, VMware Fusion, and Vagrant
• One-click profile creation from detected multi-node VM environments
• Built-in local DNS responder via /etc/resolver for zero-prompt record updates and full Safari compatibility
• In-app demo mode for trying ClusterDeck without host hypervisors

ClusterDeck is not intended to become a general Kubernetes administration console.

Infrastructure & VM Inventory

ClusterDeck incorporates the multi-provider VM inventory capabilities previously developed in InfraDeck (ADR-0008). It observes local virtual machines and environments, presents resource capacity totals (CPU, RAM, disk in GiB), and enables a one-click "Set up cluster" flow that auto-saves a ready-to-connect profile.

This is the beginning of the README. Read the rest at the original. Read the full README ↗