Browse OpenForge documentation
ClusterDeck · OSS Project

ClusterDeck

A macOS desktop tool that discovers frequently recreated VM/Kubernetes environments and automates SSH and kubeconfig access around stable Profiles

macOSTauriRustReactTypeScriptSSHKuberneteskubeconfigProxyJump
RepositoryGitHub ↗
Documentation3 sections
Updated2026-10-27T00:00:00.000Z
ECOSYSTEM ROLE
Workstation Access Layer

Treats frequently recreated VM and Kubernetes environments as stable Profiles rather than IP addresses, automating SSH, Bastion/ProxyJump and kubeconfig access from the workstation.

Profile-oriented accessSSH & ProxyJumpkubeconfig normalization
PROJECT CONFORMANCE

Repository evidence checklist

3 present · 6 missing

Present means an explicit repository or site artifact was observed. Missing means this audit did not observe that artifact; it does not prove the underlying practice does not exist. Tracked links point to the closest existing backlog owner and do not create issues automatically.

CONTRIBUTING
Missing
CODE_OF_CONDUCT
Missing
SECURITY.md
Missing
SBOM evidence
Missing
Provenance / attestation
Missing
GitHub Release
Present
Evidence observed
Project detail docs
Present
3 sections
Evidence observed
Community contributor signal
Present
3 contributors
Evidence observed
repository audit not indexed
Problem

Frequently recreated VM and Kubernetes labs change IP addresses, forcing users to rebuild SSH aliases, bastion/ProxyJump paths, remote kubeconfigs, and local contexts by hand

Approach

Keep a stable Profile identity while automating host discovery → SSH bootstrap → alias/ProxyJump → kubeconfig fetch/normalization → Kubernetes connectivity verification in one macOS desktop workflow

ENGINEERING EVIDENCE

Show reviewable engineering evidence instead of relying on headline numbers.

User model
Profile-first

Keeps a stable environment identity while VM or cluster IP addresses change.

Access path
SSH + Bastion

Orchestrates connectivity, public-key bootstrap, aliases, and ProxyJump with native OpenSSH behavior.

Kubernetes
kubeconfig sync

Fetches remote kubeconfig, normalizes endpoint/context names, and stores per-Profile local configuration.

Verification
3 layers

Separates SSH, kubeconfig, and Kubernetes API connectivity so failures are visible at the correct boundary.

START HERE

You do not need to read the README from top to bottom.

ENGINEERING PRINCIPLES
Source-driven

Keep project explanations grounded in repository source, architecture, tests, releases, and operating records.

Independently useful

Even inside one ecosystem, keep boundaries independently installable, verifiable, and releasable whenever possible.

Evidence over claims

Prefer reproducible verification, incident knowledge, upgrade gates, and operating evidence over feature-count claims.

Overview

ClusterDeck is a macOS-first desktop tool for keeping local access to frequently recreated VM and Kubernetes environments stable.

It is not a general Kubernetes management console. Its boundary is the workstation access layer: discover a remote environment, make SSH access usable, fetch and normalize kubeconfig, then verify Kubernetes connectivity.

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

Design

  • Tauri 2 + Rust for filesystem, process execution, SSH orchestration, and kubeconfig handling.
  • React + TypeScript for a compact Profile/Host/Connect/Status UX.
  • Native OpenSSH first instead of reimplementing SSH behavior.
  • Profile-oriented identity so users think in environments rather than changing IP addresses.
  • ClusterDeck-owned configuration under ~/.clusterdeck/ without rewriting unrelated user SSH/Kubernetes configuration.

Security boundary

Bootstrap passwords are one-time inputs and should not be stored or logged. Generated kubeconfigs use restrictive permissions, and destructive merges to user-managed SSH/Kubernetes configuration are avoided.

Outside ~/.clusterdeck/, ClusterDeck touches exactly four things, each opt-in or confined to its own marked block:

  • Login Keychain — trusting a cluster's CA (opt-in per discovered endpoint, or from Settings → Trusted CAs) adds it to your login keychain (never System), scoped to the SSL/TLS trust policy only. Inspect or remove it in Keychain Access.app or from ClusterDeck itself.
  • /etc/hosts — off by default, opt-in per Profile. When enabled, writes stay inside one marked block per profile (# >>> ClusterDeck BEGIN (profile: <id>) >>>) via an admin-privileged prompt.
  • Local DNS (v0.5.0, opt-in per Profile) — with host_mapping: local_dns, ClusterDeck writes only marker-owned /etc/resolver/<zone> files (# managed by ClusterDeck (profile: <id>)) via an admin-privileged prompt and runs a loopback-only DNS responder on 127.0.0.1:15353 as the user LaunchAgent com.clusterdeck.dns. It exists for setups where Safari and URLSession ignore /etc/hosts.
  • ~/.ssh/config — gets a single Include ~/.clusterdeck/ssh/*.conf line; per-profile SSH options live in that included directory, not in your own config.

Download

The latest release, v0.5.0 (2026-10-26), ships as macOS Apple Silicon (aarch64) and Intel (x64) .dmg files (per the CHANGELOG, the Intel build is compiled on an Apple Silicon CI runner and has not been launched on Intel hardware). It is an unsigned, ad-hoc build: there is no Apple Developer ID certificate yet, so macOS shows an "unidentified developer" warning on first launch — right-click the app and choose Open to run it anyway.

v0.5.0 adds built-in local DNS, an app-managed SSH tunnel for bastion-only cluster APIs, and local VM inventory (Colima, VirtualBox, VMware Fusion, Vagrant) with a Demo mode (InfraDeck absorbed into ClusterDeck).

MVP

  1. Profile CRUD
  2. Multi-host discovery and SSH bootstrap
  3. SSH alias generation
  4. Bastion / ProxyJump
  5. Remote kubeconfig fetch and normalization
  6. Per-Profile kubeconfig storage
  7. Kubernetes connectivity verification
  8. Minimal-click macOS UI

Cross-platform and provider-specific discovery remain later phases.

Development

pnpm install
pnpm tauri dev
pnpm build
cargo check --manifest-path src-tauri/Cargo.toml

Running from source remains the recommended path; the .dmg is a secondary distribution channel, not a replacement for it.

Documentation

TopicPage
OverviewOverview
ArchitectureArchitecture
Getting StartedGetting Started