xcluster: a control plane for your homelab
I built a platform to manage my whole homelab from the browser: SSH terminal, Docker, Wake-on-LAN, monitoring. Written in Go.
My homelab has a few machines: they run Docker, host services, and now and then become a Kubernetes cluster. Managing them meant opening a terminal, SSH-ing into each one, checking CPU, restarting a container, then doing it all again for the next machine.
5 machines, 5 terminal sessions. I’d forget which machine was running what. Which ones were off. To wake one, I had to remember its MAC address.
So I wrote xcluster.
What xcluster is
A dashboard to control every machine in the homelab from the browser. Not a monitoring tool, but a real control plane: SSH into machines, run commands, manage Docker, wake/shutdown/reboot, all from one place.
What I enjoyed most while building it
A real web terminal
Not a textbox pretending to be a terminal. xcluster proxies a WebSocket to an SSH connection with full PTY allocation. That means the terminal you open in the browser works just like iTerm: tab completion, vim, htop, tmux, Ctrl+C, all of it.
The backend takes a WebSocket frame, pipes it into the SSH session, and pipes the output back. Gorilla WebSocket handles the connection, golang.org/x/crypto/ssh handles the SSH protocol. Each terminal session runs in its own goroutine, so nothing blocks the main thread.
Multi-auth SSH
Not every machine authenticates the same way. xcluster supports:
- Password: plain old password, encrypted at rest with AES-256-GCM
- PEM file: upload a private key, stored encrypted
- Default SSH key: uses the server’s
~/.ssh/id_rsa - xcluster key: auto-generates an ED25519 keypair and provisions it onto the target machine
All credentials are encrypted before they’re stored. Keys are derived from a server secret. Nothing is ever kept in plaintext.
Smart cluster operations
When you reboot a cluster, order matters. Rebooting the master before the workers means downtime. xcluster understands the topology: workers shut down first, the master last. Waking up is the reverse: master first.
Bulk operations have concurrency control, so it doesn’t hammer every machine at once.
Real-time metrics without an agent
No agent to install on target machines. xcluster SSHes in, runs cat /proc/stat, free -b, df -B1, parses the output and stores the metrics. A background cron job runs every 30 minutes. Pusher broadcasts the metrics to every connected dashboard, so they update live without a refresh.
Yes, it SSHes into every machine every 30 minutes to collect metrics. Not as elegant as Prometheus + node_exporter, but zero setup on the target machines. Plug and play.
Docker management over SSH
xcluster doesn’t need Docker socket access on remote machines. It SSHes in, runs docker ps, docker inspect, and parses the JSON output. Containers, images, volumes, networks: all managed through the SSH tunnel.
So you can manage Docker on a remote machine without exposing the Docker API to the network. Secure by default.
Architecture
Go backend: I picked Go for goroutines for concurrent SSH sessions, a small compiled binary (the Alpine image is ~20MB), strong typing, and excellent SSH libraries.
Structured by DDD: domain/machine, domain/cluster, domain/metric, domain/docker, domain/terminal. Each domain has handler → service → repository. A Dependency Injection container wires everything together.
React frontend: Vite + React 19 + TypeScript. The terminal UI uses xterm.js, the same library VS Code uses for its integrated terminal. Monaco Editor for config editing (YAML, JSON).
Type-safe SDK: the OpenAPI spec is auto-generated from the Go code (swag annotations). The CI pipeline converts it to TypeScript types and publishes an SDK package. The frontend imports the SDK for type-safe API calls. Change the API on the backend, and the types update on the frontend by themselves. Zero manual sync.
Roadmap
Being extended for Kubernetes:
- Kubernetes cluster provisioning (kubeadm, k3s)
- Pod/Deployment/Service management from the dashboard
- Helm chart deployment
- Log streaming from pods
- Resource metrics dashboard (CPU, memory per pod/node)
- kubectl proxy through the web terminal
Private
xcluster is a private project for now. If you’re interested, get in touch.
Related posts
Task Workspace: task management right inside Discord
I built a task management tool with two-way sync to Discord and Telegram. Here's why, and how it works.
2026-04-24VieChoice English: learn vocabulary with spaced repetition + AI
A free vocabulary learning platform built on spaced repetition and AI. This is the story behind the product.