psviderski/uncloud is tracked by TopGit as a developer tool, with 5.5k stars on GitHub, written primarily in Go. A lightweight tool for deploying and managing containerised applications across a network of Docker hosts. Bridging the gap between Docker and Kubernetes ✨
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
▸ Deploy and scale containerised apps across servers without Swarm or Kubernetes overhead ◂
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 we use Uncloud to deploy https://uncloud.run website to 2 remote machines from
the compose.yaml file on the local machine.
It exposes the container port 8000/tcp as HTTPS on uncloud.run domain, 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.
📚 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
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.
There's also a nightly rolling release available if you
want to try the latest features and fixes before they're included in an official release.
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.com domain:
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.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 ✨
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:
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 [email protected]
⏳ 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.
⏳ 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 and the uncloudd machine daemon, managed by systemd.
Generates a unique WireGuard key pair, allocates a dedicated subnet 10.210.0.0/24 for the machine and its
containers, and configures uncloudd accordingly. All subsequent communication happens with uncloudd
through its gRPC API over SSH.
Configures and starts corrosion, a CRDT-based distributed SQLite database to
share cluster state between machines, as a Docker container managed by uncloudd.
Creates a Docker bridge network connected to the WireGuard interface.
This machine becomes an entry point for the newly created cluster. Its address is stored as a connection info in the
cluster config at ~/.config/uncloud/config.yaml on your local machine.
When you add another machine:
$ uc machine add --name hetzner-server [email protected]
⏳ 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.
⏳ 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 sudo access.
Allocates a new subnet 10.210.1.0/24 for 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 the uncloud-corrosion container on 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 be used by uc to connect and run 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.
uncloudd that the CLI communicates with uses grpc-proxy to forward
the request to the target machine to launch a container there.
uncloudd on 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-254 range) and becomes
accessible from other machines in the cluster.
Caddy reverse proxy which runs in global
mode 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.
🧪 Interactive tutorials
To give you a chance to play with Uncloud without even leaving your browser, we're providing interactive tutorials and
playgrounds on the iximiuz Labs platform.
Available tutorials:
Setting up a new Uncloud cluster - the tutorial
walks you through creating a new cluster with two machines and then deploying a simple web service to it.
Deploying a Django web application - deploy
a Django web app from source code to a remote Linux server using Uncloud.
You can also launch the Uncloud playground where you
can play with an already initialized Uncloud cluster.
🏗 Project status
Uncloud is under active development and pre-1.0, so expect occasional breaking changes between releases. The core build,
push, and deploy workflows are stable, and much of the runtime relies on battle-tested projects: Docker, Caddy,
WireGuard, and Corrosion.
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 our newsletter to follow the journey of building Uncloud: progress
updates, user stories, and the occasional deep dive.
Watch this repository for releases.
💖 Sponsors
These companies and projects are helping Uncloud with their generous sponsorship and/or services:
The most recent commit recorded on psviderski/uncloud was 23 days ago, based on the GitHub push timestamp. The repository has 174 forks — one of the better signals of community interest.
How many stars does psviderski/uncloud have?
psviderski/uncloud has 5.5k GitHub stars — refresh the page for the live number, or check github.com/psviderski/uncloud. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is psviderski/uncloud open source?
Yes — psviderski/uncloud ships under the Apache-2.0 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/psviderski/uncloud.
What else is in the Developer Tools space?
psviderski/uncloud is tracked by TopGit under the Developer Tools category, alongside 9 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What is psviderski/uncloud?
psviderski/uncloud (psviderski/uncloud) is a Go project on GitHub. From the project's own README: A lightweight tool for deploying and managing containerised applications across a network of Docker hosts. Bridging the gap between Docker and Kubernetes ✨
What language is psviderski/uncloud written in?
psviderski/uncloud is written primarily in Go. GitHub's language field is based on the largest share of bytes in the default branch.
What license does psviderski/uncloud use?
psviderski/uncloud is released under the Apache-2.0 license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where do I read more about psviderski/uncloud?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/psviderski/uncloud is the definitive source.
Read full README in the tab above.
Still deciding about uncloud?
One click hands the question to an AI along with this page — see what it says about uncloud.
/uncloud
