Luis LavenaandGitHub
48d2239f5d
* Connect to remote SSH nodes using SSH CLI Replace Go-native SSH implementation with SSH CLI execution to support diverse SSH configurations and agents. Implements 'uncloudd dial-stdio' subcommand that proxies gRPC connections over stdin/stdout, similar to Docker's approach. This change addresses compatibility issues with: - SSH agents exposing many keys (1Password, causing "too many authentication failures") - Tailscale SSH (which doesn't support advanced SSH channel types like direct-streamlocal) - Custom SSH configurations in ~/.ssh/config The dial-stdio approach reduces SSH feature requirements by streaming the unix socket connection over stdin/stdout instead of using SSH channel forwarding. Changes: - Add 'uncloudd dial-stdio' hidden subcommand for socket proxy - Add SSHCLIConnector using ssh command + dial-stdio - Update connection logic to use SSH CLI connector - Maintain backward compatibility with SSHKeyFile config Resolves #131 * Fix sshcli tests missing ConnectionTimeout Introduced short connection timeout on the first change but forgot to update tests to match. * Add SSHCLI field and update MachineConnection String() format - Add SSHCLI field to support ssh_cli YAML configuration - Update String() to use URI-like format (ssh://, ssh+cli://, tcp://) * Add Validate() method and tests for MachineConnection - Add Validate() to ensure connection methods are mutually exclusive - Add tests for validation and String() method * Unify SSH connector configs to use SSHConnectorConfig * Update connectCluster to support both SSH connector types * Restore Go SSH connector as default for machine init/add Revert provisionOrConnectRemoteMachine to use Go SSH connector: - Root users: reuse SSH connection from provisioning - Non-root users: establish new connection for group membership - Remove SSH CLI as default connector SSH CLI connector remains available via ssh_cli config field. * Add sshCLIDialer with DialContext method Implement proxy.ContextDialer for SSHCLIConnector using SSH -W flag. Each dial spawns a new SSH process for TCP forwarding, enabling independent connections separate from the gRPC dial-stdio connection. * Implement SSHCLIConnector.Dialer() method Return sshCLIDialer instead of error, enabling uc image push functionality with SSHCLIConnector. Validates connector is configured before returning dialer. * Fix half-closing implementation matchin Docker's approach * Use testify assertions for connection tests * Allow ssh+cli:// to be used with --connect This way I can skip the configuration file while testing things out, and confirm it works correctly: $ unset SSH_AUTH_SOCK $ ./uncloud --connect ssh://provision@blatta11 machine ls Error: connect to cluster: connect to machine: SSH login to provision@blatta11:22: connect using SSH agent: connect to SSH agent: dial unix: missing address $ ./uncloud --connect ssh+cli://provision@blatta11 machine ls NAME STATE ADDRESS PUBLIC IP WIREGUARD ENDPOINTS MACHINE ID blatta11 Up 10.210.0.1/24 - 100.64.0.22:51820, ... * Validates configuration before connecting to cluster * Do not tie client constructor with real validation No longer attempt to validate the connection when instantiating a new client. Later on we could validate it in different places. * Cleanup test and remove AI-slop There were some serious slop in those tests, so took the time to clean them up and kept only the relevant ones. There is some repetition between buildSSHArgs and buildDialArgs but can be tackled at a later stage. * Fix connection representation tests Prefix connection with ssh ssh+cli respectively. * Wait for stdout before returning Missed copy & pasta from Docker dial-stdio implementation (this happens when you stare at the code for too long that it burns your eyes).
Uncloud
Docker simplicity. Multi-machine power.
Uncloud is a lightweight clustering and container orchestration tool that lets you deploy and manage web apps across cloud VMs and bare metal with minimised cluster management overhead. It creates a secure WireGuard mesh network between your Docker hosts and provides automatic service discovery, load balancing, ingress with HTTPS, and simple CLI commands to manage your apps.
Unlike traditional orchestrators, there's no central control plane and quorum to maintain. Each machine maintains a synchronised copy of the cluster state through peer-to-peer communication, keeping cluster operations functional even if some machines go offline.
Uncloud is the solution for developers who want the flexibility of self-hosted infrastructure without the operational complexity of Kubernetes.
✨ Features
- Deploy anywhere: Combine cloud VMs, dedicated servers, and bare metal into a unified computing environment, regardless of location or provider.
- Docker Compose: Familiar Docker Compose format for defining services and volumes. No need to learn a new bespoke DSL.
- Zero-downtime deployments: Rolling updates without service interruption. Automatic rollback on failure is coming soon.
- Unregistry integration: Build and push your Docker images directly to your machines without an external registry. It will transfer only the missing layers, making it fast and efficient.
- Service discovery: Built-in DNS server resolves service names to container IPs.
- Persistent storage: Run stateful services with Docker volumes managed across machines.
- Zero-config private network: Automatic WireGuard mesh with peer discovery and NAT traversal. Containers get unique IPs for direct cross-machine communication.
- No control plane: Fully decentralised design eliminates single points of failure and reduces operational overhead.
- Imperative over declarative: Favoring imperative operations over state reconciliation simplifies both the mental model and troubleshooting.
- Managed DNS: Automatic DNS records
*.<id>.cluster.uncloud.runfor services with public access via managed Uncloud DNS service. - Automatic HTTPS: Built-in Caddy reverse proxy handles TLS certificate provisioning and renewal using Let's Encrypt.
- Docker-like CLI: Familiar commands for managing both infrastructure and applications.
- Remote management: Control your entire infrastructure through SSH access to any single machine in the cluster.
🎬 Quick demo
The screenshot below demonstrates how I use Uncloud to deploy https://uncloud.run website to 2 remote machines from
the compose.yaml file on my local machine.
It exposes the container port 8000/tcp as HTTPS on the domain uncloud.run, served by the Caddy reverse proxy on the
remote machines. All managed by Uncloud.
Here is a more advanced use case. Deploy a highly available web app with automatic HTTPS across multiple regions and on-premises in just a couple minutes.
💫 Why Uncloud?
Modern cloud platforms like Heroku and Render offer amazing developer experiences but at a premium price. Traditional container orchestrators like Kubernetes provide power and flexibility but require significant operational expertise. I believe there's a sweet spot in between — a pragmatic solution for the majority of us who aren't running at Google scale. You should be able to:
- Own your infrastructure and data: Whether driven by costs, compliance, or flexibility, run applications on any combination of cloud VMs and personal hardware while controlling your data and maintaining the cloud-like experience you love.
- Stay simple as you grow: Start with a single machine and add more whenever you need without changing your workflow. No worrying about highly-available control planes or complex YAML configurations.
- Build with proven primitives: Get production-grade networking, deployment primitives, service discovery, load balancing, and ingress with HTTPS out of the box without becoming a distributed systems expert.
- Support sustainable computing 🌿: Minimise system overhead to maximise resources available for your applications.
Uncloud's goal is to make deployment and management of containerised applications feel as seamless as using a cloud platform, whether you're running on a $5 VPS, a spare Mac mini, or a rack of bare metal servers.
🚀 Quick start
-
Install Uncloud CLI:
brew install psviderski/tap/uncloud # or using curl (macOS/Linux) curl -fsS https://get.uncloud.run/install.sh | shSee Installation for more options.
-
Initialise your first machine:
uc machine init root@your-server-ip -
Deploy your app from a Docker image and publish its container port 8000 as HTTPS using
app.example.comdomain:uc run -p app.example.com:8000/https image/my-app -
Create a DNS A record in your DNS provider (Cloudflare, Namecheap, etc.) that points
app.example.comto your server's IP address. Allow a few minutes for DNS propagation.That's it! Your app is now running and accessible at https://app.example.com ✨
-
Clean up when you're done:
uc ls # Copy the service name from the output and run the rm command: uc rm my-app-nameIf you want to fully uninstall Uncloud on a machine, run:
uncloud-uninstall
View the Documentation for more information.
⚙️ How it works
Check out the design document to understand Uncloud's design philosophy and goals.
Here is a diagram of an Uncloud multi-provider cluster of 3 machines:
Peek under the hood to see what happens when you run certain commands.
When you initialise a new cluster on a machine:
$ uc machine init --name oracle-vm ubuntu@152.67.101.197
Downloading Uncloud install script: https://raw.githubusercontent.com/psviderski/uncloud/refs/heads/main/scripts/install.sh
⏳ Running Uncloud install script...
✓ Docker is already installed.
⏳ Installing Docker...
...
✓ Docker installed successfully.
✓ Linux user and group 'uncloud' created.
✓ Linux user 'ubuntu' added to group 'uncloud'.
⏳ Installing Uncloud binaries...
⏳ Downloading uncloudd binary: https://github.com/psviderski/uncloud/releases/latest/download/uncloudd_linux_arm64.tar.gz
✓ uncloudd binary installed: /usr/local/bin/uncloudd
⏳ Downloading uninstall script: https://raw.githubusercontent.com/psviderski/uncloud/refs/heads/main/scripts/uninstall.sh
✓ uncloud-uninstall script installed: /usr/local/bin/uncloud-uninstall
✓ Systemd unit file created: /etc/systemd/system/uncloud.service
Created symlink /etc/systemd/system/multi-user.target.wants/uncloud.service → /etc/systemd/system/uncloud.service.
⏳ Downloading uncloud-corrosion binary: https://github.com/psviderski/corrosion/releases/latest/download/corrosion-aarch64-unknown-linux-gnu.tar.gz
✓ uncloud-corrosion binary installed: /usr/local/bin/uncloud-corrosion
✓ Systemd unit file created: /etc/systemd/system/uncloud-corrosion.service
⏳ Starting Uncloud machine daemon (uncloud.service)...
✓ Uncloud machine daemon started.
✓ Uncloud installed on the machine successfully! 🎉
Cluster "default" initialised with machine "oracle-vm"
Waiting for the machine to be ready...
Reserved cluster domain: xuw3xd.cluster.uncloud.run
[+] Deploying service caddy 1/1
✔ Container caddy-c47x on oracle-vm Started 0.9s
Updating cluster domain records in Uncloud DNS to point to machines running caddy service...
[+] Verifying internet access to caddy service 1/1
✔ Machine oracle-vm (152.67.101.197) Reachable 0.1s
DNS records updated to use only the internet-reachable machines running caddy service:
*.xuw3xd.cluster.uncloud.run A → 152.67.101.197
- The CLI SSHs into the machine and installs Docker, the
unclouddmachine daemon and corrosion service, managed by systemd. - Generates a unique WireGuard key pair, allocates a dedicated subnet
10.210.0.0/24for the machine and its containers, and configuresunclouddaccordingly. All subsequent communication happens withunclouddthrough its gRPC API over SSH. - Configures and starts
corrosion, a CRDT-based distributed SQLite database to share cluster state between machines. - Creates a Docker bridge network connected to the WireGuard interface.
- This machine becomes an entry point for the newly created cluster which is stored in the cluster config under
~/.config/uncloudon your local machine.
When you add another machine:
$ uc machine add --name hetzner-server root@5.223.45.199
Downloading Uncloud install script: https://raw.githubusercontent.com/psviderski/uncloud/refs/heads/main/scripts/install.sh
⏳ Running Uncloud install script...
✓ Docker is already installed.
✓ Linux user and group 'uncloud' created.
⏳ Installing Uncloud binaries...
⏳ Downloading uncloudd binary: https://github.com/psviderski/uncloud/releases/latest/download/uncloudd_linux_amd64.tar.gz
✓ uncloudd binary installed: /usr/local/bin/uncloudd
⏳ Downloading uninstall script: https://raw.githubusercontent.com/psviderski/uncloud/refs/heads/main/scripts/uninstall.sh
✓ uncloud-uninstall script installed: /usr/local/bin/uncloud-uninstall
✓ Systemd unit file created: /etc/systemd/system/uncloud.service
Created symlink /etc/systemd/system/multi-user.target.wants/uncloud.service → /etc/systemd/system/uncloud.service.
⏳ Downloading uncloud-corrosion binary: https://github.com/psviderski/corrosion/releases/latest/download/corrosion-x86_64-unknown-linux-gnu.tar.gz
✓ uncloud-corrosion binary installed: /usr/local/bin/uncloud-corrosion
✓ Systemd unit file created: /etc/systemd/system/uncloud-corrosion.service
⏳ Starting Uncloud machine daemon (uncloud.service)...
✓ Uncloud machine daemon started.
✓ Uncloud installed on the machine successfully! 🎉
Machine "hetzner-server" added to cluster
Waiting for the machine to be ready...
[+] Deploying service caddy 1/1
✔ Container caddy-d36c on hetzner-server Started 1.0s
Updating cluster domain records in Uncloud DNS to point to machines running caddy service...
[+] Verifying internet access to caddy service 2/2
✔ Machine hetzner-server (5.223.45.199) Reachable 0.2s
✔ Machine oracle-vm (152.67.101.197) Reachable 0.1s
DNS records updated to use only the internet-reachable machines running caddy service:
*.xuw3xd.cluster.uncloud.run A → 152.67.101.197, 5.223.45.199
$ uc machine ls
NAME STATE ADDRESS PUBLIC IP WIREGUARD ENDPOINTS
oracle-vm Up 10.210.0.1/24 152.67.101.197 10.0.0.95:51820, 152.67.101.197:51820
hetzner-server Up 10.210.1.1/24 5.223.45.199 5.223.45.199:51820, [2a01:4ff:2f0:128b::1]:51820
- The second machine gets provisioned just like the first. A non-root SSH user will need
sudoaccess. - Allocates a new subnet
10.210.1.0/24for the second machine and its containers. - Registers the second machine in the cluster state and exchanges WireGuard keys with the first machine.
- Both machines establish a WireGuard tunnel between each other, allowing Docker containers connected to the bridge network to communicate directly across machines.
- Configures and starts
corrosionon the second machine to sync the cluster state. - The second machine is added as an alternative entry point in the cluster config.
- If one of the machines goes offline, the other machine can still serve cluster operations.
If one more machine is added, the process repeats with a new subnet. The new machine needs to establish a WireGuard connection with only one of the existing machines. Other machines will learn about it through the shared cluster state and automatically establish a WireGuard tunnel with it.
When you run a service:
$ uc run -p app.example.com:8000/https image/my-app
[+] Running service my-app-1b3b (replicated mode) 1/1
✔ Container my-app-1b3b-tcex on oracle-vm Started
my-app-1b3b endpoints:
• https://app.example.com → :8000
• https://my-app-1b3b.xuw3xd.cluster.uncloud.run → :8000
- CLI picks a machine to run your container.
unclouddthat the CLI communicates with usesgrpc-proxyto forward the request to the target machine to launch a container there.unclouddon the target machine starts the Docker container in the bridge network and stores its info in the cluster's distributed state.- The container gets a cluster-unique IP address from the bridge network (in the
10.210.X.2-254range) and becomes accessible from other machines in the cluster. - Caddy reverse proxy which runs in
globalmode on each machine watches the cluster state for new services and updates its configuration to route traffic to the new container.
Look ma, no control plane or master nodes to maintain! Just a simple overlay network and eventually consistent state sync that lets machines work together. Want to check on things or make changes? Connect to any machine either implicitly using the CLI or directly over SSH. They all have the complete cluster state and can control everything. It's like each machine is a full backup of your control plane.
🏗 Project status
Uncloud is currently in active development and is not ready for production use. Features may change significantly and there may be breaking changes between releases.
We'd love your input! Here's how you can contribute:
- 🐛 Found a bug? Open an issue
- 💡 Have questions, ideas, or need help?
- Start a discussion or join an existing one in the Discussions.
- Join our Discord community where we discuss features, roadmap, implementation details, and help each other out.
🙏 Inspiration & Acknowledgements
I'm grateful to the following projects that inspired Uncloud's design and implementation:
- Kamal — for proving that even in the declarative era of Kubernetes there is a place for simple deployment tools that use imperative commands without complex orchestration. Kamal powers the multi-billion dollar company 37signals where it was created, and that's truly inspiring!
- Fly.io — for inspiring my vision for what self-hosted infrastructure should feel like, proving that developer experience and powerful infrastructure can coexist beautifully.
- Tailscale — for pioneering the vision of decentralised flat mesh networking with an amazing user experience that feels like magic.
- Talos Linux and KubeSpan — for the machine API design using grpc-proxy and for its elegant approach to secure WireGuard-based overlay networking with zero configuration.
- Docker Swarm Classic and Rancher 1.x — for showing the power of simplicity and pragmatism in container orchestration and that not every problem needs the complexity of Kubernetes.
Special thanks to the Corrosion project by Fly.io for providing the distributed SQLite database used to share Uncloud's cluster state.
📫 Stay updated
- Join our Discord server for real-time discussions, support, and updates.
- Follow @psviderski on X/Twitter.
- Subscribe to my newsletter to follow the progress, get early insights into new features, and be the first to know when it's ready for production use.
- Watch this repository for releases.
💖 Sponsors
These companies and projects are helping Uncloud with their generous sponsorship and/or services:
❤️ Contributors
Thank you @cedws for being the first contributor to Uncloud! 🎉