Skip to content

Getting Started

DasCondor edited this page Nov 16, 2026 · 3 revisions

Getting started

Documentation snapshot from README.md at commit 20d7c81. Check the current source for updates.

🌐 Play in the browser (sandbox demo)

https://dascondor.github.io/kubefactory/

The browser build is a sandbox: it runs the built-in simulated clusters only and connects to nothing. A browser cannot run kubectl or Docker, so managing real clusters needs the desktop build below. Every tool works against the simulation, including Porter's bundled app setups; his online app lists do not load there. Graphics start light (drawn in code, one shadow pass) so the demo opens at once on any device. Esc → Graphics → High switches to the real model library (about 13 MB, fetched once from the same site and checked against the catalog's checksums), 4x anti-aliasing and softer shadows; the page reloads to apply it, and ?gfx=high in the address opens it that way. Global illumination and reflections need the desktop build: WebGL cannot run them. On desktop, click the page to capture the mouse; touch devices have on-screen controls. It is rebuilt and redeployed on every push to main by .github/workflows/pages.yml.

See the mobile guide for touch controls and what the demo looks like when you turn a phone.

Four demo worlds

Start the simulation (the browser demo, the Demo edition, or --demo) and you pick a world. Switch any time from the pause menu, or name one up front with --demo=<id>. In every demo you are signed in as DasCondor. An explicitly selected desktop demo starts without inspecting kubeconfigs or probing Docker. To switch to local infrastructure, open Clusters and select Discover local connections, or add a kubeconfig in the connection wizard. Simulated actions do not send audit webhooks, and online app lists are disabled in a demo; Porter's bundled app setups remain available.

--demo= World What is running What is broken
kubernetes Kubernetes cluster a web shop: frontend, cart, checkout, database, monitoring checkout crash-loops; one image tag is mistyped
home-assistant Home Assistant Home Assistant, Mosquitto, Zigbee2MQTT, Z-Wave JS, ESPHome, Node-RED, Frigate, voice (Whisper, Piper), MariaDB, InfluxDB, Grafana Zigbee2MQTT cannot find its USB stick; one image tag is mistyped
dev-containers Dev containers a build farm: Gitea, CI server and runners, BuildKit, registry, compile cache, and a dev container each for C++, Rust, Go, Python and Node a heavy C++ build runs out of memory; one image tag is mistyped
media Media suite Plex, Jellyfin, shared and dedicated VPN gateways, Heimdall, and monitoring library-check has a sample image-pull failure and an unavailable service port

The broken ones are there for Bob: ask him to read the log and he finds the missing /dev/ttyUSB0 or the compiler killed for memory. The cloud-flavoured Kubernetes simulations (EKS, AKS, GKE, Rancher) are still at the cluster gates.

📥 Download

2.0.0-beta.2 is the current pre-release. The latest stable build (1.0.1, Windows only) and every earlier version are on the Releases page.

Platform Download Start it
Windows .zip, 59 MB install.ps1 or KubeFactory.exe
Linux x86_64 .tar.gz, 51 MB ./KubeFactory.x86_64
macOS (Apple Silicon, Intel) .zip, 91 MB KubeFactory.app (below)

Checking a download. Every package has a .sha256, the release has one SHA256SUMS, and every package carries a signed build-provenance attestation that ties it to this repository's release workflow and the exact commit:

gh attestation verify KubeFactory-2.0.0-beta.2-linux-x86_64.tar.gz -R DasCondor/kubefactory

None of the packages is signed with a Windows or Apple developer identity yet. Windows signing is free through SignPath Foundation once the project is approved (CODE_SIGNING); until then Windows SmartScreen asks for confirmation on first run. On macOS the app is ad-hoc signed but not notarized, so Gatekeeper blocks a downloaded copy until you clear the quarantine flag on the unpacked folder:

xattr -dr com.apple.quarantine KubeFactory-2.0.0-beta.2-macos

📦 Install (release build)

Linux: unpack KubeFactory-<version>-linux-x86_64.tar.gz and run ./KubeFactory.x86_64 from that folder. macOS: unzip, clear the quarantine flag (above), and open KubeFactory.app; keep the other files beside it. On both, the options below work the same way (./KubeFactory.x86_64 -- --demo).

Windows: unzip KubeFactory-<version>-win64.zip, then:

powershell -ExecutionPolicy Bypass -File install.ps1

That installs for the current user (no admin rights) to %LOCALAPPDATA%\Programs\KubeFactory and adds Start Menu entries: KubeFactory, KubeFactory (simulation) and KubeFactory (read-only). -Quiet skips the desktop shortcut for IT rollouts. Upgrading keeps your edited config files. uninstall.ps1 removes it (-Purge also removes settings and audit logs). You can also just run KubeFactory.exe from the unzipped folder.

Command-line options go after --:

Command Does
KubeFactory.exe --kubeconfig <file> connect to the cluster in that kubeconfig (YAML or JSON)
KubeFactory.exe -- --demo built-in simulated cluster (safe to break)
KubeFactory.exe -- --sim=aws-eks-prod or azure-aks-staging, gke-analytics, rancher-edge
KubeFactory.exe -- --context=<name> a specific kubeconfig context
KubeFactory.exe -- --read-only look, don't touch
KubeFactory.exe -- --docker --context=<n> a Docker host, by its Docker context
KubeFactory.exe -- --remote=wss://host:7666 a KubeFactory server (token in KF_REMOTE_TOKEN)
KubeFactory.exe --headless -- --server be a server for the others (SERVER)
KubeFactory.exe -- --kubectl-cli use kubectl instead of the built-in client

With no options it connects to your current kube context, then Docker, then the simulation. KubeFactory.console.exe is the same game with a console window, for troubleshooting. check-requirements.ps1 checks for the optional cloud CLIs.

🎮 Editions

The same game also comes in two narrower builds. They install side by side with the full game (KubeFactory Docker, KubeFactory Demo).

Edition Opens on Never touches
KubeFactory Docker your local Docker engine: every container is a machine, Compose projects are namespaces kubectl / any Kubernetes cluster
KubeFactory Demo the built-in simulated clusters, with every tool unlocked kubectl and Docker: it connects to nothing

The Docker edition falls back to the simulation while the Docker engine is not running. Build them with tools\package.ps1 -Edition docker / -Edition demo, or run them from source with play.bat --edition=docker / --edition=demo.

💻 Run from source

Command Does
tools\setup.ps1 checks / installs the software below (including the engine)
play.bat starts the game; same options as above, without the leading --
play.bat --edition=docker or demo the Docker or Demo edition
tools\package.ps1 runs the tests and builds the release zip and checksum in dist (-Edition docker or demo builds that edition)
tools\dev-cluster.ps1 a 3-node Kubernetes cluster in Docker containers (kind), with sample workloads, two of them broken on purpose
tools\dev-cluster.ps1 -Delete removes it
tools\dev-users.ps1 multi-user setup and two test logins on that cluster

🧰 Software

Software Needed for Install
Godot 4.3 (portable, in engine\) running the game tools\setup.ps1 downloads it
Go 1.25+ building the companion from source (tools\build-agent.ps1; -Fetch gets a private copy) winget install GoLang.Go
Microsoft Edge or Google Chrome LiveView Edge ships with Windows
kubectl optional: only for --kubectl-cli and the admin commands in docs/ADMIN.md winget install Kubernetes.kubectl
Docker Desktop local containers, dev cluster winget install Docker.DockerDesktop
kind dev cluster in Docker winget install Kubernetes.kind
AWS CLI EKS login, CloudWatch logs winget install Amazon.AWSCLI
Azure CLI + kubelogin AKS login, Azure Monitor logs winget install Microsoft.AzureCLI Microsoft.Azure.Kubelogin
Google Cloud SDK + gke-gcloud-auth-plugin GKE login, Cloud Logging winget install Google.CloudSDK
curl (ships with Windows) Grafana Loki logs -

Rancher needs nothing extra: download the cluster's kubeconfig from the Rancher UI. tools\setup.ps1 -Cloud installs the three cloud CLIs.

Clone this wiki locally