How to Install Uncloud on Ubuntu: Lightweight Multi-Host Container Deployment

Uncloud lets you deploy and manage containerised web applications across several machines — cloud VMs, a home lab, bare metal — without adopting the full complexity of a Kubernetes cluster. It joins your hosts into an encrypted WireGuard mesh, ships a built-in Caddy reverse proxy for automatic HTTPS, and provides cluster-wide DNS so services can find each other by name, all from a single uc command.

What sets it apart is the absence of a central control plane. Every machine holds its own view of the cluster and gossips changes to the others, so there is no master node to keep alive and no distributed datastore to operate. You keep working with plain Docker and Docker Compose, but gain the ability to spread services across a whole fleet.

Because Uncloud is evolving quickly, it has not made its way into Ubuntu’s official archives. Instead of fetching release binaries manually and cobbling together your own upgrade path, the unofficial deb.griffo.io repository provides a maintained package you can install and update with ordinary apt commands.

Install the Latest Uncloud on Ubuntu: The Short Version

If you only came for the commands, this adds the repository and installs the latest Uncloud .deb package on Ubuntu:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null
sudo apt update
sudo apt install uncloud

The rest of this guide explains what each command does, how to verify the install, how to keep Uncloud up to date, and what to check when something goes wrong.

What Makes Uncloud Special?

  • 🕸️ No control plane — hosts form a decentralised WireGuard mesh and share state via gossip, so there is nothing central to fail.
  • 🔒 HTTPS out of the box — an embedded Caddy proxy obtains and renews TLS certificates automatically.
  • 🧭 Cluster-wide DNS — services discover each other by name across every machine in the mesh.
  • 📦 Compose-friendly — deploy existing compose.yaml stacks without rewriting them.
  • ♻️ Rolling deployments — updates roll out with zero downtime for the service.
  • 🌍 Cloud and bare metal together — mix providers and on-prem hardware in one cluster.
  • ⚡ One static binary — the entire uc CLI is a single dependency-free executable.
  • 🔧 Built on Docker — it orchestrates the Docker Engine you already run rather than replacing it.

Why Use the deb.griffo.io Repository?

Managing Uncloud through deb.griffo.io keeps the whole lifecycle inside APT:

  • Easy installation and updates using the package manager Ubuntu already ships.
  • Automatic dependency management so nothing has to be resolved by hand.
  • Always tracks upstream releases, delivering new uc versions soon after they land.
  • No building from source and no wrangling Go toolchains or tarballs.
  • Works across supported Ubuntu releases, from Jammy onwards.

Prerequisites

Before starting, make sure you have:

  • An Ubuntu system (Jammy 22.04 LTS, Noble 24.04 LTS, or newer)
  • sudo privileges
  • curl installed (sudo apt install curl if needed)
  • Docker Engine installed and running on every host you want in the cluster

Step 1: Add the deb.griffo.io Repository

Register the signing key and repository with APT by running the following block:

# Create the keyrings directory
sudo install -d -m 0755 /etc/apt/keyrings

# Download and install the repository GPG key
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

# Add the repository (auto-detects your distro codename)
echo "deb [signed-by=/etc/apt/keyrings/deb.griffo.io.gpg] https://deb.griffo.io/apt $(lsb_release -sc 2>/dev/null) main" | sudo tee /etc/apt/sources.list.d/deb.griffo.io.list > /dev/null

# Update the package list
sudo apt update

Breaking that down:

  1. Keyrings directory — creates /etc/apt/keyrings to store the repository’s signing key securely.
  2. GPG key — fetches the key and writes it in the binary format APT expects.
  3. Repository entry — adds the source, with lsb_release -sc inserting your Ubuntu codename automatically.
  4. Update — reloads the package index so Uncloud becomes visible to APT.

Step 2: Update the Package List

If you did not run the final command above, refresh the index now:

sudo apt update

Step 3: Install Uncloud

Install the package with a single command:

sudo apt install uncloud

APT fetches the latest release and resolves any dependencies for you.

Step 4: Verify the Installation

Check that the CLI is available. Remember the binary is uc, not uncloud:

uc --version

Expected output looks roughly like:

uc version 0.9.2
commit: 4f2ac1b

Run uc --help at any time to browse the full command list.

Getting Started with Uncloud

Once uc is installed you can spin up a cluster and deploy a service. The commands below run from your Ubuntu workstation and reach your machines over SSH.

Bootstrap a Cluster

Start by initialising a single host. Uncloud installs its agent, configures WireGuard and launches the Caddy proxy on the target machine:

# Initialise the cluster on your first host
uc machine init root@198.51.100.5

The CLI connects over SSH, provisions the server and stores the cluster context locally for later commands.

Join Additional Machines

Expand the cluster by adding more hosts. Each joins the same encrypted mesh:

# Add another machine with a memorable name
uc machine add --name oracle-arm root@198.51.100.9

# List all machines in the cluster
uc machine ls

Deploy and Expose a Service

Run a container and publish it with automatic TLS. The -p flag binds a public hostname to a container port and asks Caddy to handle certificates:

# Deploy a service reachable at https://api.example.com
uc run -p api.example.com:3000/https your-registry/my-api:latest

# List running services
uc ls

# Remove a service
uc rm my-api

Point the DNS record for api.example.com at one of your machines and Caddy takes care of the certificate.

Deploy an Existing Compose Stack

If your application is already defined with Docker Compose, deploy it directly:

# Deploy the stack described by a compose file
uc deploy -f compose.yaml

This is the shortest path from a single-host Compose setup to a multi-machine deployment.

Everyday Operations

The routine commands are few and easy to remember:

# Inspect services and where they run
uc ls

# Inspect machines and their health
uc machine ls

# Ship a new image with a rolling, zero-downtime update
uc run -p api.example.com:3000/https your-registry/my-api:v2

Keeping Uncloud Updated

Since the CLI came from APT, updates are handled like any other Ubuntu package:

sudo apt update && sudo apt upgrade

That upgrades uc whenever a newer build is published. Try to keep your workstation CLI and the agents on your machines on compatible versions, and redeploy your services after a significant upgrade.

Other Tools from deb.griffo.io

The same repository offers a range of complementary DevOps and self-hosting tools. These sit well alongside an Uncloud setup:

  • Lazydocker — a terminal UI for Docker and Compose to inspect containers on each host.
  • k9s — a fast Kubernetes terminal UI for the times a workload lands on a cluster.
  • Headscale — a self-hosted Tailscale control server for private access to your fleet.
  • Forgejo — a lightweight self-hosted Git forge for your images and Compose definitions.

Troubleshooting

GPG or Key Issues

If APT reports an unsigned repository or an expired key, re-import the signing key:

# Remove the current key
sudo rm -f /etc/apt/keyrings/deb.griffo.io.gpg

# Fetch and install it again
curl -fsSL https://deb.griffo.io/EA0F721D231FDD3A0A17B9AC7808B4DD62C41256.asc | sudo gpg --dearmor --yes -o /etc/apt/keyrings/deb.griffo.io.gpg

sudo apt update

Package Not Found

If apt install uncloud cannot find the package:

  1. Confirm you ran sudo apt update after adding the repository.
  2. Verify your Ubuntu release is supported (Jammy, Noble, or newer).
  3. Check the source file: cat /etc/apt/sources.list.d/deb.griffo.io.list

Firewall Blocks the WireGuard Mesh

Because Uncloud relies on a WireGuard mesh, cluster members must be able to reach each other on the WireGuard UDP port. On a cloud VM this usually means opening that port in the provider’s security group; on a local machine, in ufw. If uc machine add succeeds but services cannot resolve each other by DNS, an over-zealous firewall between hosts is the usual culprit. Also confirm Docker Engine is installed and running on each host before initialising or joining.

Uninstalling

To remove Uncloud from your system:

# Remove the package
sudo apt remove uncloud

# Optionally remove the repository and key
sudo rm -f /etc/apt/sources.list.d/deb.griffo.io.list
sudo rm -f /etc/apt/keyrings/deb.griffo.io.gpg
sudo apt update

Uninstalling the CLI leaves any existing clusters running; tidy them up with uc rm and clean your machines beforehand if you want a fresh start.

Conclusion

Uncloud gives Ubuntu users a genuinely lightweight way to run containers across many machines. You keep Docker and Compose, and gain an encrypted mesh, automatic HTTPS and cluster-wide service discovery — without the burden of a control plane to maintain.

Installing it through deb.griffo.io fits that philosophy perfectly: one apt install to begin and one apt upgrade to stay current, so the tooling never becomes the thing you spend your time managing.

Frequently Asked Questions

How do I install the latest Uncloud on Ubuntu?

Add the deb.griffo.io APT repository and its signing key, then run sudo apt install uncloud. The repository tracks upstream Uncloud releases, so you get the latest packaged version rather than a build frozen when your distribution was released.

Is there a .deb package for Uncloud?

Yes. deb.griffo.io publishes Uncloud as a signed .deb for Ubuntu. You could download that .deb and install it by hand, but adding the repository is the better option: APT then resolves dependencies and picks up new versions on its own.

How do I update Uncloud to the latest version?

Run sudo apt update && sudo apt upgrade. Once Uncloud is installed from APT there is no separate updater to remember, since new releases arrive with the rest of your system updates.

How do I install Uncloud on Debian?

Exactly the same way; lsb_release -sc simply resolves to a different codename. There is a companion guide with the Debian specifics: How to install Uncloud on Debian.

Which Ubuntu releases are supported?

Jammy 22.04 LTS, Noble 24.04 LTS and newer. Because the repository line is built from lsb_release -sc, the matching suite is selected for you.

Resources

Disclaimer: The deb.griffo.io repository is an unofficial community project and is not affiliated with the official Debian or Ubuntu projects, or with the upstream Uncloud project.