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

2026-04-24

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.

#product#task-management#discord
2026-04-24

VieChoice 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.

#product#education#ai