Uncloud

<div align="center"> <img src="./website/landing/images/logo-title.svg#gh-light-mode-only" alt="Uncloud logo"/> <img src="./website/landing/images/logo-title-dark.svg#gh-dark-mode-only" alt="Uncloud logo"/> <p><strong>▸ Deploy and scale containerised apps across servers without Swarm or Kubernetes overhead ◂</strong></p> <p> <a href="https://uncloud.run/docs"><img src="https://img.shields.io/badge/Docs-blue.svg?style=for-the-badge&logo=gitbook&logoColor=white" alt="Documentation"></a> <a href="https://discord.gg/eR35KQJhPu"><img src="https://img.shields.io/badge/discord-5865F2.svg?style=for-the-badge&logo=discord&logoColor=white" alt="Join Discord"></a> <a href="https://x.com/psviderski"><img src="https://img.shields.io/badge/follow-black?style=for-the-badge&logo=X&logoColor=while" alt="Follow on X"></a> <a href="https://github.com/sponsors/psviderski"><img src="https://img.shields.io/badge/Donate-EA4AAA.svg?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Donate"></a> </p> </div>

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 *.xxxxxx.uncld.dev for 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.

<a href="https://uncloud.wistia.com/medias/k47uwt9uau?wvideo=k47uwt9uau"> <img src="https://embed-ssl.wistia.com/deliveries/4fb71ea442905b81b1ad4e25fc02132e.jpg?image_crop_resized=900x526&image_play_button_rounded=true&image_play_button_size=2x&image_play_button_color=18181Be0" alt="Uncloud demo" width="450" height="263" /> </a> <br> <br>

📚 Want more examples? Check out the uncloud-recipes repository for community recipes and templates for deploying popular services on Uncloud.

💫 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

1. Install Uncloud CLI:

   brew install psviderski/tap/uncloud
   
   # or using curl (macOS/Linux)
   curl -fsS https://get.uncloud.run/install.sh | sh
   

   See Installation for more options.

2. Initialise your first machine:

   uc machine init root@your-server-ip
   

3. Deploy your app from a Docker image and publish its container port 8000 as HTTPS using app.example.com domain:

   uc run -p app.example.com:8000/https image/my-app
   

4. Create a DNS A record in your DNS provider (Cloudflare, Namecheap, etc.) that points app.example.com to 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 ✨

5. Clean up when you're done:

   uc ls
   # Copy the service name from the output and run the rm command:
   uc rm my-app-name
   

   If 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:

<details> <summary>Peek under the hood to see what happens when you run certain commands.</summary>

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