v0.18.0

This page mirrors the GitHub release, which also includes the full list of commits.

The main highlights of this release are pre-deploy hooks for running database migrations and a redesigned deployment plan output that makes uc deploy much nicer to read and understand.

On top of that, 0.18.0 also:

makes the system ssh CLI the default connection method (with fallback to the Go implementation)
adds Compose support for pid, shm_size, and the new x-context extension to pin a Compose file to a cluster
brings new docs, a bunch of quality-of-life improvements and bug fixes, read on for the full details!

Pre-deploy hooks

⚠️ This requires both uc and the daemon to be upgraded to v0.18.0

Changes: f4581ea, 1c8b770, 772b31b, 0e820f9

You can now run a one-off command before deploying a service using the new x-pre_deploy Compose extension. This is ideal for database schema migrations, uploading static assets to a CDN, cache invalidation, and any other setup task that needs to run once before new code goes live.

compose.yaml
services:
  web:
    build: ..
    environment:
      DATABASE_URL: postgres://postgres:${DB_PASSWORD}@db:5432/postgres
    x-pre_deploy:
      # Apply Django migrations from the built image before deploying new app containers.
      command: python manage.py migrate
    depends_on:
      - db

Here is how it's displayed in the deploy plan when you run uc deploy:

The hook command runs in a new container that inherits the service's image, environment variables, volumes, placement, and compute resources.

If the command exits successfully, the deployment continues with a normal rolling update. If it fails or times out, the deployment stops immediately and uc deploy displays the latest hook logs to help you diagnose the issue.

pre-deploy-hook

Container tables in uc ps and uc inspect now also list pre-deploy hook containers.

See the docs:

Pre-deploy hooks guide for more details and examples
x-pre_deploy reference for all available attributes

Restyled deployment plans

Changes: 0f4c211, f5a77b8, b4b1232

The deployment plan output that you see when running uc deploy, uc scale, and uc caddy deploy has been redesigned with consistent styling, clearer operation verbs, and a header and the prompt showing the target context.

We hope this makes it easier for you to understand what changes will be made and to which cluster before you confirm the deployment.

System `ssh` is now the default connection method

Change: 06c2bc5

The ssh+cli:// connection method that uses your system's ssh CLI is now the default for new connections, so the prefix can be omitted:

# Old
uc machine init ssh+cli://user@host
# New
uc machine init user@host

ssh_cli: can also be replaced with just ssh: in the config file (~/.config/uncloud/config.yaml):

config.yaml
contexts:
  prod:
    connections:
      - ssh: user@host

This will by default use your existing SSH config, agent, keys, ProxyJump, and ProxyCommand setup automatically. You can fall back to the Go native SSH implementation using ssh+go:// prefix.

Combined with the SSH control socket reuse introduced in v0.17.0, this makes most uc commands noticeably faster and removes a whole class of authentication friction.

The new Connecting to a cluster doc walks through all the supported connection schemes (ssh://, ssh+go://, tcp://, unix://), how uc picks a machine to talk to from your config, and how to connect without a config file for CI pipelines and scripts.

Cluster context selection in Compose

Change: 1525d18

You can now pin a Compose file to a specific context using the new x-context extension. This prevents accidentally deploying to the wrong cluster when you switch contexts.

compose.yaml
x-context: prod

services:
  web:
    image: myapp

When x-context is set, uc deploy will use that context regardless of your currently selected one in the Uncloud config. The deployment plan output also displays the target context so you always know where your changes are going.

See x-context reference for more details.

Compose `pid` namespace support

PR: #276. Thanks to @miekg for the contribution ❤️

You can now configure the PID namespace mode for service containers. The most common use case is pid: host, which lets a container see and interact with processes on the host. This is useful for monitoring agents, debuggers, and similar tooling.

services:
  monitoring:
    image: agent
    pid: host

Compose `shm_size` support

Change: 8ae38cf

You can now set shm_size, the size of the /dev/shm shared memory tmpfs. This is useful for databases like Postgres, headless Chromium, and other workloads that need a larger shared memory segment.

services:
  postgres:
    image: postgres:18
    shm_size: 256mb

Documentation

Connecting to a cluster: a complete guide to cluster contexts, connection resolution and all supported types, and how to connect without a config file
CLI configuration file: a full reference for the ~/.config/uncloud/config.yaml file, covering contexts, connections, and all supported fields
Pre-deploy hooks: a guide for the new feature, with examples for database migrations and other one-off setup tasks
Compose extensions: a dedicated reference page for all Uncloud-specific Compose extensions

Improvements

The uc CLI and the daemon now exchange versions on every gRPC call and error if they are incompatible. This is a groundwork to make better user experience when releasing breaking changes in the future (#260). Thanks to @jabr for the contribution ❤️
New uc exec accepts an optional -- separator before the command, matching Docker and other CLIs (#301). Thanks to @nick-potts for the contribution ❤️
New uc docs --manual flag generates manual pages for uc, making it easier for distribution maintainers to package manpages alongside the binary (#302). Thanks to @miekg for the contribution ❤️
The daemon now exposes a gRPC method to fetch journald logs from a machine, laying the groundwork for an upcoming uc machine logs command (#282). Thanks to @miekg for the contribution ❤️
Warnings are now printed for detected unsupported Compose features (#288). Thanks to @miekg for the contribution ❤️
New --auto-confirm flag for uc scale which now always asks for confirmation before changing replica counts
New --ulimit flag for uc run to set resource limits
bumped Go to 1.26.1 and modernized the codebase using Go 1.26 (#278)
Migrated TUI components to lipgloss/v2, bubbletea/v2, and huh/v2

Bug fixes

Fixed uc deploy crash in an initialised but empty git repository (#275). Thanks to @tonyo for the contribution ❤️
Fixed ucind downloading the wrong Corrosion architecture on arm64 (#285). Thanks to @miekg for the contribution ❤️
Fixed output contamination in the SSH CLI executor by separating stdout and stderr (#270)
Fixed trying other machine connections when the first one fails for the new default ssh type. Fixed the TUI progress spinner.

Upgrade to 0.18.0

Uncloud CLI locally

To upgrade the Uncloud CLI (uc) locally:

# Homebrew (macOS, Linux)
brew upgrade uncloud

# Install script (macOS, Linux)
curl -fsS https://get.uncloud.run/install.sh | sh

Machine daemon

To upgrade the Uncloud daemon on your machines, run the following commands on each machine:

# AMD64
curl -fsSL -o uncloudd.tar.gz https://github.com/psviderski/uncloud/releases/download/v0.18.0/uncloudd_linux_amd64.tar.gz
# ARM64
# curl -fsSL -o uncloudd.tar.gz https://github.com/psviderski/uncloud/releases/download/v0.18.0/uncloudd_linux_arm64.tar.gz
tar -xf uncloudd.tar.gz
sudo install uncloudd /usr/local/bin/uncloudd
rm uncloudd uncloudd.tar.gz
sudo systemctl restart uncloud

Pre-deploy hooks​

Restyled deployment plans​

System ssh is now the default connection method​

Cluster context selection in Compose​

Compose pid namespace support​

Compose shm_size support​

Documentation​

Improvements​

Bug fixes​

Upgrade to 0.18.0​

Uncloud CLI locally​

Machine daemon​