How to Install Unregistry on Ubuntu: Registry-Free Docker Image Pushes

Unregistry is a compact tool that pushes Docker images straight to a remote server over SSH, with no external registry in the loop. It writes images directly into the remote Docker daemon’s containerd storage and sends only the layers the target does not already have, so pushes are fast and you never have to touch Docker Hub, GHCR or a registry you run yourself.

You drive it through a Docker CLI plugin named docker pussh (the double “s” is deliberate). Build an image, run docker pussh myimage:latest user@host, and moments later it is sitting on the remote machine ready to run. For self-hosters and small teams this deletes an entire component from the deployment story — there is simply no registry to operate, secure or pay for.

As a young and specialised tool, Unregistry is not part of Ubuntu’s official archives. The unofficial deb.griffo.io repository packages the docker-pussh plugin so you can install and update it with apt, rather than manually placing a script into your Docker CLI plugins directory.

Install the Latest Unregistry on Ubuntu: The Short Version

If you only came for the commands, this adds the repository and installs the latest Unregistry .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 unregistry

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

What Makes Unregistry Special?

  • 🚫 Registry-free deploys — push images directly to a host over SSH, bypassing Docker Hub, GHCR and self-hosted registries.
  • 📦 Only missing layers move — incremental, layer-aware transfers keep pushes fast and light on bandwidth.
  • 🔌 First-class Docker plugin — surfaces as docker pussh, behaving like a built-in subcommand.
  • 🔐 Secured by SSH — leans on your existing keys and SSH config, with no extra credentials to store.
  • 🗄️ Direct containerd storage — images arrive in the remote daemon’s store, ready to docker run.
  • 🏗️ Architecture targeting — choose a platform with --platform for cross-arch pushes.
  • 🪶 Minimal moving parts — a single client plugin plus a short-lived helper image on the server.
  • 🔑 Full SSH flexibility — custom keys, ports and config files are all honoured per push.

Why Use the deb.griffo.io Repository?

Pulling the plugin from deb.griffo.io is far tidier than managing it yourself:

  • Easy installation and updates via the APT package manager.
  • Automatic dependency management so requirements come along for the ride.
  • Always tracks upstream releases of the docker-pussh plugin.
  • No hand-editing of ~/.docker/cli-plugins.
  • Works across supported Ubuntu releases, from Jammy onwards.

Prerequisites

Before you start, 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 installed locally, plus SSH access to a remote host that also runs Docker

Step 1: Add the deb.griffo.io Repository

Register the signing key and repository with APT using the block below:

# 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

Step by step:

  1. Keyrings directory — creates /etc/apt/keyrings to store the signing key.
  2. GPG key — downloads the key and writes it in APT’s binary format.
  3. Repository entry — adds the source, using lsb_release -sc to insert your Ubuntu codename.
  4. Update — reloads the package index so APT can see the package.

Step 2: Update the Package List

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

sudo apt update

Step 3: Install Unregistry

Install the package with one command:

sudo apt install unregistry

This drops the docker-pussh plugin in place and registers it with your Docker client.

Step 4: Verify the Installation

The plugin binary is docker-pussh, but it runs through Docker as docker pussh. Confirm it is available:

docker pussh --help

You should see usage output along these lines:

Usage: docker pussh [OPTIONS] IMAGE[:TAG] [USER@]HOST[:PORT]

Push a Docker image to a remote host over SSH without an external registry.

Options:
  -i FILE            SSH private key to use
  -F FILE            SSH config file to use
  --platform STRING  Push a specific platform (e.g. linux/amd64)
  -h, --help         Show this help message

If Docker says pussh is not a command, jump to troubleshooting below.

Getting Started with Unregistry

With the plugin registered, a push is a single command that runs entirely over SSH.

Push Your First Image

Build an image, then push it to a remote host. Unregistry launches a temporary helper on the target, ships the missing layers, and cleans up after itself:

# Build the image locally
docker build -t web-api:latest .

# Push it directly to the remote host
docker pussh web-api:latest deploy@198.51.100.5

When the push completes, the image is present in the remote Docker daemon and docker run web-api:latest works there straight away — no pull step required.

Reuse Your SSH Config

If your hosts live in ~/.ssh/config, refer to them by alias, or point at a specific config file with -F:

# 'staging' is a Host entry in your SSH config
docker pussh web-api:latest staging

# Use a dedicated SSH config file
docker pussh web-api:latest staging -F ~/.ssh/config.staging

Choose a Key or Custom Port

Every SSH connection option is available. Supply a key with -i, or append a non-default port to the host:

# Push with an explicit private key
docker pussh web-api:latest ubuntu@198.51.100.5 -i ~/.ssh/deploy_key

# Push to a host on a non-standard SSH port
docker pussh web-api:latest deploy@198.51.100.5:2222

Target a Single Platform

For multi-arch images, pick the platform that should land on the remote:

# Push only the arm64 build
docker pussh web-api:latest deploy@198.51.100.5 --platform linux/arm64

Pin the Helper Image

The remote side uses a small helper image during the push. Pin it to a specific version with UNREGISTRY_IMAGE when you need reproducibility:

UNREGISTRY_IMAGE=ghcr.io/psviderski/unregistry:0.4.3 \
  docker pussh web-api:latest deploy@198.51.100.5

A tidy deployment loop then looks like: build locally, docker pussh to the box, and docker compose up -d over SSH to bring the new image up.

Keeping Unregistry Updated

Because the plugin came from APT, keeping it current is routine:

sudo apt update && sudo apt upgrade

That tracks the upstream docker-pussh releases. After upgrading the client, let it fetch a matching helper image on your next push, or pin one explicitly with UNREGISTRY_IMAGE as shown earlier.

Other Tools from deb.griffo.io

The repository carries plenty of tools that fit a registry-free workflow. A handful that complement Unregistry:

  • Lazydocker — a terminal UI for Docker to review the images you have pushed.
  • Uncloud — deploy containers across several hosts once the images have landed.
  • k9s — a Kubernetes terminal UI for when a cluster enters the picture.
  • Forgejo — a self-hosted Git forge for the source behind your images.

Troubleshooting

GPG or Key Issues

If APT flags 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 unregistry fails to find the package:

  1. Make sure 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

Push Fails Because the Remote Docker Is Unreachable

docker pussh needs a working Docker Engine on the far end, reachable over SSH by the user you connect as. If a push stalls or errors while starting the helper, first confirm you can ssh deploy@198.51.100.5 docker ps successfully. On Ubuntu servers the deploy user often needs to be in the docker group (sudo usermod -aG docker deploy, then reconnect). Also check that outbound SSH to the target is not blocked by ufw or a cloud security group.

Uninstalling

To remove Unregistry:

# Remove the package
sudo apt remove unregistry

# 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

Images already pushed to remote hosts remain untouched; uninstalling only stops you pushing new ones.

Conclusion

Unregistry strips a whole tier of infrastructure out of container deployment. Rather than running a registry, pushing to it and pulling on the other side, you push images directly to the Ubuntu servers that will run them, over your existing SSH access, sending only the layers they lack.

Installing it from deb.griffo.io keeps things effortless: the docker pussh plugin is one apt install away and stays fresh with a routine apt upgrade, with no scripts to copy or plugin directories to hand-manage.

Frequently Asked Questions

How do I install the latest Unregistry on Ubuntu?

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

Is there a .deb package for Unregistry?

Yes. deb.griffo.io publishes Unregistry 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 Unregistry to the latest version?

Run sudo apt update && sudo apt upgrade. Once Unregistry 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 Unregistry 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 Unregistry 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 Unregistry project.