How to Install Uncloud on Debian: Deploy Containers Across Any Host

Uncloud is a lightweight tool for deploying and managing containerised web applications across a fleet of cloud VMs and bare-metal machines, without the operational weight of a full orchestrator like Kubernetes. It stitches your machines together into a secure WireGuard mesh, runs a built-in Caddy reverse proxy for automatic HTTPS, and gives you cluster-wide DNS-based service discovery — all driven from a single uc binary.

The clever part is that there is no central control plane to babysit. Each machine keeps its own copy of the cluster state and gossips changes to its peers, so there is no master node to lose and no etcd cluster to nurse back to health. You get much of the convenience of a managed platform while keeping the simplicity of plain Docker and Docker Compose.

Uncloud is young and moves fast, so it is not packaged in the official Debian repositories. Rather than downloading release tarballs by hand and wiring up your own update mechanism, the unofficial deb.griffo.io repository ships an up-to-date prebuilt package that installs and upgrades cleanly with apt.

Install the Latest Uncloud on Debian: The Short Version

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

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?

  • 🕸️ Control-plane-free clustering — machines form a decentralised WireGuard mesh and gossip state, so there is no master node to lose.
  • 🔒 Automatic HTTPS — a bundled Caddy reverse proxy provisions and renews TLS certificates for your services.
  • 🧭 Built-in service discovery — cluster-wide DNS lets containers reach each other by name across any machine.
  • 📦 Docker Compose support — describe your stack in familiar compose.yaml files and deploy it unchanged.
  • ♻️ Zero-downtime rollouts — rolling updates keep a service reachable while new container versions come up.
  • 🌍 Mix cloud and bare metal — combine a Hetzner box, a home server and a Raspberry Pi in the same cluster.
  • ⚡ Single static binary — the whole CLI is one uc executable with no runtime dependencies.
  • 🔧 Docker-native — it drives the Docker Engine you already know rather than replacing it.

Why Use the deb.griffo.io Repository?

The deb.griffo.io repository makes living with Uncloud far less fiddly:

  • Easy installation and updates through the APT package manager you already use.
  • Automatic dependency management — APT pulls in anything the package needs.
  • Always tracks upstream releases so you get new uc versions shortly after they ship.
  • No compiling from source and no juggling Go toolchains or release archives.
  • Works across supported Debian releases, from Bookworm through Sid.

Prerequisites

Before you begin, make sure you have:

  • A Debian-based system (Bookworm 12, Trixie 13, or Sid)
  • sudo privileges
  • curl installed (sudo apt install curl if it is missing)
  • Docker Engine installed and running on any machine you intend to add to a cluster

Step 1: Add the deb.griffo.io Repository

Add the signing key and the repository to APT. Run the following block in your terminal:

# 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

Here is what each step does:

  1. Keyrings directory — creates /etc/apt/keyrings with sane permissions to hold the signing key.
  2. GPG key — downloads the repository key and stores it de-armoured where APT can find it.
  3. Repository entry — writes the source list, using lsb_release -sc to fill in your Debian codename automatically.
  4. Update — refreshes APT so it sees the newly added packages.

Step 2: Update the Package List

If you skipped the final line above, refresh the package index now:

sudo apt update

Step 3: Install Uncloud

Install the package with APT:

sudo apt install uncloud

APT downloads the latest Uncloud build along with any dependencies.

Step 4: Verify the Installation

Confirm the CLI is on your PATH. Note the binary is uc, not uncloud:

uc --version

You should see something similar to:

uc version 0.9.2
commit: 4f2ac1b

A quick uc --help lists the available subcommands.

Getting Started with Uncloud

With uc installed, you can build a cluster and deploy your first service. Everything below runs from your workstation and talks to your machines over SSH.

Initialise Your First Machine

Point Uncloud at a fresh server to bootstrap a single-machine cluster. It installs the agent, sets up WireGuard and starts the Caddy proxy:

# Bootstrap the cluster on your first host
uc machine init root@203.0.113.10

Uncloud connects over SSH, provisions the machine and records the cluster context locally so subsequent commands know where to talk.

Add More Machines

Grow the cluster by joining additional hosts. Each new machine is woven into the same encrypted mesh:

# Add a second machine and give it a friendly name
uc machine add --name hetzner-fsn root@203.0.113.20

# List every machine in the cluster
uc machine ls

Deploy a Service

Run a container and expose it to the internet with automatic HTTPS. The -p flag maps a public hostname to a container port and asks Caddy to terminate TLS:

# Deploy a container reachable at https://app.example.com
uc run -p app.example.com:8000/https your-registry/my-app:latest

# See what is running
uc ls

# Remove a service when you are done
uc rm my-app

Point your app.example.com DNS record at one of your machines and Caddy handles the certificate for you.

Deploy from a Compose File

If you already describe your stack with Compose, Uncloud can deploy it directly:

# Deploy the stack defined in the current directory's compose file
uc deploy -f compose.yaml

This makes it easy to migrate an existing single-host Docker Compose project onto a multi-machine cluster with minimal changes.

Inspect and Iterate

Day-to-day operations lean on a small, memorable set of verbs:

# List services and their placement
uc ls

# List machines and their status
uc machine ls

# Redeploy after pushing a new image tag (rolling, zero-downtime)
uc run -p app.example.com:8000/https your-registry/my-app:v2

Keeping Uncloud Updated

Because Uncloud came from APT, upgrading is the same as any other package:

sudo apt update && sudo apt upgrade

This pulls the newest uc build whenever the repository is refreshed. It is worth keeping the CLI and your machine agents on compatible versions, so upgrade your workstation and redeploy after major releases.

Other Tools from deb.griffo.io

The repository carries plenty of other self-hosting and DevOps tools. If you are running Uncloud, these pair naturally with it:

  • Lazydocker — a terminal UI for Docker and Docker Compose, ideal for eyeballing containers on each host.
  • k9s — a slick terminal UI for those moments when a workload does end up on Kubernetes.
  • Headscale — a self-hosted Tailscale control server for private access to your fleet.
  • Forgejo — a lightweight self-hosted Git forge to store the images and Compose files you deploy.

Troubleshooting

GPG or Key Issues

If APT complains that the repository is not signed or the key has expired, re-add the signing key:

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

# Re-download and install it
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 reports that the package is unavailable:

  1. Make sure you ran sudo apt update after adding the repository.
  2. Check that your Debian release is supported (Bookworm, Trixie, or Sid).
  3. Confirm the source is present: cat /etc/apt/sources.list.d/deb.griffo.io.list

uc machine init Cannot Reach the Host

Cluster bootstrap runs entirely over SSH, so most early failures are connection problems. Verify you can reach the machine directly with ssh root@203.0.113.10 first, check that the user has permission to manage Docker, and ensure the WireGuard UDP port is not blocked by a cloud firewall or security group. Uncloud also expects a working Docker Engine on the target — install it before running uc machine init.

Uninstalling

To remove Uncloud:

# 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

Removing the CLI does not tear down clusters you have already created; use uc rm and clean up your machines before uninstalling if you want a clean slate.

Conclusion

Uncloud hits a sweet spot between raw docker run and a full Kubernetes deployment. You keep the familiarity of Docker and Compose while gaining a secure mesh, automatic HTTPS and cluster-wide DNS across as many machines as you like — with no control plane to maintain.

Installing it from deb.griffo.io means one apt install to get started and one apt upgrade to stay current, which is exactly the kind of low-friction setup that suits a tool designed to keep operations lightweight.

Frequently Asked Questions

How do I install the latest Uncloud on Debian?

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 Debian. 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 Ubuntu?

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

Which Debian releases are supported?

Bookworm 12, Trixie 13 and Sid. 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.