docs: regenerate CLI reference

Co-authored-by: Miek Gieben <miek@miek.nl>

.github/workflows/go-tests.yml

@@ -14,12 +14,13 @@ on:
       - "**.proto"
       - "go.*"
       - "Makefile"
+      - "mise.toml"
       - "scripts/**"
       - "test/**"
 permissions:
   contents: read
 env:
-  MISE_VERSION: "2026.3.7"
+  MISE_VERSION: "2026.10.22"
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -42,9 +43,9 @@ jobs:
 
       - name: Generate docs
         run: |
-          make cli-docs
+          mise run docs:cli
           git diff --exit-code ||
-            (echo "Documentation is out of date. Please run 'make cli-docs' and commit the changes." && exit 1)
+            (echo "Documentation is out of date. Please run 'mise run docs:cli' and commit the changes." && exit 1)
 
       - name: Run tests
         run: |
@@ -70,7 +71,7 @@ jobs:
           version: ${{ env.MISE_VERSION }}
 
       # TODO: figure out how to properly lock all platforms in the lockfile and remove this hack.
-      # `mise lock` (mise run mise:lock) doesn't generate checksums for some of the tools, e.g. protoc*
+      # `mise lock` doesn't generate checksums for some of the tools, e.g. protoc*
       - name: Reset changes in mise.lock after fresh mise install
         run: git checkout mise.lock
 

.github/workflows/lint.yml

@@ -14,7 +14,7 @@ on:
 permissions:
   contents: read
 env:
-  MISE_VERSION: "2026.3.7"
+  MISE_VERSION: "2026.10.22"
 jobs:
   lint:
     runs-on: ubuntu-latest

.github/workflows/nightly-build.yml

@@ -8,7 +8,7 @@ permissions:
   contents: write
 
 env:
-  MISE_VERSION: "2026.3.7"
+  MISE_VERSION: "2026.10.22"
 
 jobs:
   nightly:

.mockery.yml

@@ -1,4 +1,10 @@
 packages:
+  github.com/docker/docker/client:
+    config:
+      dir: internal/machine/docker
+      pkgname: docker
+    interfaces:
+      APIClient:
   github.com/psviderski/uncloud/internal/machine/caddyconfig:
     interfaces:
       CaddyfileValidator:

HACKING.md

@@ -35,10 +35,11 @@ Build the CLI:
 go build -o uc ./cmd/uc
 ```
 
-Or build and run the CLI with a single command:
+Or build and run the CLI with mise. It forwards arguments, including help flags, directly to the CLI:
 
 ```shell
-go run ./cmd/uc --help
+mise uc --help
+mise uc image rm -h
 ```
 
 The Uncloud daemon (`uncloudd`) only supports Linux, so you need to cross-compile it if you're developing on macOS or
@@ -116,9 +117,31 @@ mise run proto
 Regenerate mocks:
 
 ```shell
-make mocks
+mise run mocks
 ```
 
+## Documentation
+
+Regenerate the CLI reference docs after changing commands or flags:
+
+```shell
+mise run docs:cli
+```
+
+To preview the documentation website, install its dependencies from the project root:
+
+```shell
+npm ci --prefix website
+```
+
+Then start the local development server:
+
+```shell
+mise run docs:dev
+```
+
+The server opens the site (http://localhost:3000/) in your browser and reloads it as you edit files in `website/`.
+
 ## Uncloud in Docker (UCinD)
 
 The [`ucind`](./cmd/ucind) CLI lets you run Uncloud clusters locally using Docker containers instead of real machines.

Makefile

@@ -21,10 +21,6 @@ corrosion-multiarch-image-push:
 ucind-multiarch-image-push:
 	docker buildx build --push --platform linux/amd64,linux/arm64 -t "$(UCIND_IMAGE)" --target ucind .
 
-.PHONY: mocks
-mocks:
-	@mockery
-
 .PHONY: test
 test:
 ifeq ($(TEST_NAME),)
@@ -69,7 +65,3 @@ _lint:
 # Explicitly set OS to Linux to not skip *_linux.go files when running on macOS.
 # Uncloud daemon won't likely support OS other than Linux anytime soon, so for now we can rely on that.
 	GOOS=linux golangci-lint run $(ARGS)
-
-.PHONY: cli-docs
-cli-docs:
-	go run ./cmd/uc docs

api/pb/common.go

@@ -4,8 +4,16 @@ import (
 	"bytes"
 	"fmt"
 	"net/netip"
+
+	"google.golang.org/grpc/status"
 )
 
+// Err returns the upstream error, preserving its gRPC status code.
+// It returns nil for nil metadata or an absent or successful status.
+func (m *Metadata) Err() error {
+	return status.ErrorProto(m.GetStatus())
+}
+
 func NewIP(addr netip.Addr) *IP {
 	// MarshalBinary always returns a nil error.
 	ip, _ := addr.MarshalBinary()

api/pb/common.pb.go

@@ -87,7 +87,8 @@ type Metadata struct {
 	MachineName string `protobuf:"bytes,5,opt,name=machine_name,json=machineName,proto3" json:"machine_name,omitempty"`
 	// Address of the machine the response came from.
 	MachineAddr string `protobuf:"bytes,1,opt,name=machine_addr,json=machineAddr,proto3" json:"machine_addr,omitempty"`
-	// error is set if the request to upstream failed. The rest of the response is undefined.
+	// error is set if the request to upstream failed. The rest of the response apart from this metadata message
+	// is undefined.
 	Error string `protobuf:"bytes,2,opt,name=error,proto3" json:"error,omitempty"`
 	// error as a gRPC Status message.
 	Status *status.Status `protobuf:"bytes,3,opt,name=status,proto3" json:"status,omitempty"`

api/pb/common.proto

@@ -18,7 +18,8 @@ message Metadata {
   // Address of the machine the response came from.
   string machine_addr = 1;
 
-  // error is set if the request to upstream failed. The rest of the response is undefined.
+  // error is set if the request to upstream failed. The rest of the response apart from this metadata message
+  // is undefined.
   string error = 2;
   // error as a gRPC Status message.
   google.rpc.Status status = 3;

api/pb/docker.proto

@@ -24,6 +24,7 @@ service Docker {
   // Docker auth credentials if necessary.
   rpc InspectRemoteImage(InspectRemoteImageRequest) returns (InspectRemoteImageResponse);
   rpc ListImages(ListImagesRequest) returns (ListImagesResponse);
+  rpc RemoveImage(RemoveImageRequest) returns (RemoveImageResponse);
 
   rpc CreateVolume(CreateVolumeRequest) returns (CreateVolumeResponse);
   rpc ListVolumes(ListVolumesRequest) returns (ListVolumesResponse);
@@ -179,6 +180,40 @@ message ListImagesRequest {
   bytes options = 1;
 }
 
+message RemoveImageRequest {
+  string id = 1;
+  bool force = 2;
+  bool prune_children = 3;
+  repeated ImagePlatform platforms = 4;
+}
+
+// ImagePlatform describes an OCI image platform.
+message ImagePlatform {
+  string architecture = 1;
+  string os = 2;
+  string os_version = 3;
+  repeated string os_features = 4;
+  string variant = 5;
+}
+
+message RemoveImageResponse {
+  // Must contain only one repeated messages field to allow broadcasting RemoveImage requests to multiple machines.
+  repeated MachineImageRemoval messages = 1;
+}
+
+message MachineImageRemoval {
+  Metadata metadata = 1;
+  repeated ImageRemoval results = 2;
+}
+
+// ImageRemoval reports an image deletion or an untagged image reference.
+message ImageRemoval {
+  // The image ID of an image that was deleted.
+  string deleted = 1;
+  // The image reference of an image that was untagged.
+  string untagged = 2;
+}
+
 message ListImagesResponse {
   // Must contain only one repeated messages field to allow broadcasting ListImages requests to multiple machines.
   repeated MachineImages messages = 1;

api/pb/docker_grpc.pb.go

@@ -32,6 +32,7 @@ const (
 	Docker_InspectImage_FullMethodName            = "/api.Docker/InspectImage"
 	Docker_InspectRemoteImage_FullMethodName      = "/api.Docker/InspectRemoteImage"
 	Docker_ListImages_FullMethodName              = "/api.Docker/ListImages"
+	Docker_RemoveImage_FullMethodName             = "/api.Docker/RemoveImage"
 	Docker_CreateVolume_FullMethodName            = "/api.Docker/CreateVolume"
 	Docker_ListVolumes_FullMethodName             = "/api.Docker/ListVolumes"
 	Docker_RemoveVolume_FullMethodName            = "/api.Docker/RemoveVolume"
@@ -59,6 +60,7 @@ type DockerClient interface {
 	// Docker auth credentials if necessary.
 	InspectRemoteImage(ctx context.Context, in *InspectRemoteImageRequest, opts ...grpc.CallOption) (*InspectRemoteImageResponse, error)
 	ListImages(ctx context.Context, in *ListImagesRequest, opts ...grpc.CallOption) (*ListImagesResponse, error)
+	RemoveImage(ctx context.Context, in *RemoveImageRequest, opts ...grpc.CallOption) (*RemoveImageResponse, error)
 	CreateVolume(ctx context.Context, in *CreateVolumeRequest, opts ...grpc.CallOption) (*CreateVolumeResponse, error)
 	ListVolumes(ctx context.Context, in *ListVolumesRequest, opts ...grpc.CallOption) (*ListVolumesResponse, error)
 	RemoveVolume(ctx context.Context, in *RemoveVolumeRequest, opts ...grpc.CallOption) (*emptypb.Empty, error)
@@ -217,6 +219,16 @@ func (c *dockerClient) ListImages(ctx context.Context, in *ListImagesRequest, op
 	return out, nil
 }
 
+func (c *dockerClient) RemoveImage(ctx context.Context, in *RemoveImageRequest, opts ...grpc.CallOption) (*RemoveImageResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(RemoveImageResponse)
+	err := c.cc.Invoke(ctx, Docker_RemoveImage_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 func (c *dockerClient) CreateVolume(ctx context.Context, in *CreateVolumeRequest, opts ...grpc.CallOption) (*CreateVolumeResponse, error) {
 	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
 	out := new(CreateVolumeResponse)
@@ -305,6 +317,7 @@ type DockerServer interface {
 	// Docker auth credentials if necessary.
 	InspectRemoteImage(context.Context, *InspectRemoteImageRequest) (*InspectRemoteImageResponse, error)
 	ListImages(context.Context, *ListImagesRequest) (*ListImagesResponse, error)
+	RemoveImage(context.Context, *RemoveImageRequest) (*RemoveImageResponse, error)
 	CreateVolume(context.Context, *CreateVolumeRequest) (*CreateVolumeResponse, error)
 	ListVolumes(context.Context, *ListVolumesRequest) (*ListVolumesResponse, error)
 	RemoveVolume(context.Context, *RemoveVolumeRequest) (*emptypb.Empty, error)
@@ -358,6 +371,9 @@ func (UnimplementedDockerServer) InspectRemoteImage(context.Context, *InspectRem
 func (UnimplementedDockerServer) ListImages(context.Context, *ListImagesRequest) (*ListImagesResponse, error) {
 	return nil, status.Errorf(codes.Unimplemented, "method ListImages not implemented")
 }
+func (UnimplementedDockerServer) RemoveImage(context.Context, *RemoveImageRequest) (*RemoveImageResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method RemoveImage not implemented")
+}
 func (UnimplementedDockerServer) CreateVolume(context.Context, *CreateVolumeRequest) (*CreateVolumeResponse, error) {
 	return nil, status.Errorf(codes.Unimplemented, "method CreateVolume not implemented")
 }
@@ -591,6 +607,24 @@ func _Docker_ListImages_Handler(srv interface{}, ctx context.Context, dec func(i
 	return interceptor(ctx, in, info, handler)
 }
 
+func _Docker_RemoveImage_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(RemoveImageRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(DockerServer).RemoveImage(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: Docker_RemoveImage_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(DockerServer).RemoveImage(ctx, req.(*RemoveImageRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 func _Docker_CreateVolume_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
 	in := new(CreateVolumeRequest)
 	if err := dec(in); err != nil {
@@ -760,6 +794,10 @@ var Docker_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "ListImages",
 			Handler:    _Docker_ListImages_Handler,
 		},
+		{
+			MethodName: "RemoveImage",
+			Handler:    _Docker_RemoveImage_Handler,
+		},
 		{
 			MethodName: "CreateVolume",
 			Handler:    _Docker_CreateVolume_Handler,

cmd/uc/caddy/config.go

@@ -3,8 +3,8 @@ package caddy
 import (
 	"context"
 	"fmt"
-	"os"
 
+	"charm.land/lipgloss/v2"
 	"github.com/alecthomas/chroma/v2/quick"
 	"github.com/psviderski/uncloud/internal/cli"
 	"github.com/psviderski/uncloud/internal/cli/completion"
@@ -15,7 +15,6 @@ import (
 
 type configOptions struct {
 	machine string
-	noColor bool
 }
 
 func NewConfigCommand() *cobra.Command {
@@ -33,8 +32,6 @@ func NewConfigCommand() *cobra.Command {
 
 	cmd.Flags().StringVarP(&opts.machine, "machine", "m", "",
 		"Name or ID of the machine to get the configuration from. (default is connected machine)")
-	cmd.Flags().BoolVar(&opts.noColor, "no-color", false,
-		"Disable syntax highlighting for the output.")
 
 	completion.MachinesFlag(cmd)
 
@@ -54,13 +51,9 @@ func runConfig(ctx context.Context, uncli *cli.CLI, opts configOptions) error {
 	}
 
 	// Print the Caddyfile with syntax highlighting.
-	if opts.noColor {
-		fmt.Print(config.Caddyfile)
-	} else {
-		if err = quick.Highlight(os.Stdout, config.Caddyfile, "caddy", "terminal256", "monokai"); err != nil {
-			// If highlighting fails, fall back to plain output.
-			fmt.Print(config.Caddyfile)
-		}
+	if err = quick.Highlight(lipgloss.Writer, config.Caddyfile, "caddy", "terminal256", "monokai"); err != nil {
+		// If highlighting fails, fall back to plain output.
+		lipgloss.Print(config.Caddyfile)
 	}
 
 	if config.LastReconciliationError != "" {

cmd/uc/context/show.go

@@ -22,15 +22,6 @@ func NewShowCommand() *cobra.Command {
 }
 
 func show(uncli *cli.CLI) error {
-	// discard errors, only show the current context, otherwise nothing
-	if uncli.Config == nil {
-		return nil
-	}
-
-	if len(uncli.Config.Contexts) == 0 {
-		return nil
-	}
-	fmt.Println(uncli.Config.CurrentContext)
-
+	fmt.Println(uncli.ContextOverrideOrCurrent())
 	return nil
 }

cmd/uc/deploy.go

@@ -18,7 +18,7 @@ import (
 	"github.com/psviderski/uncloud/pkg/client"
 	"github.com/psviderski/uncloud/pkg/client/compose"
 	"github.com/psviderski/uncloud/pkg/client/deploy"
-	"github.com/psviderski/uncloud/pkg/client/deploy/operation"
+	"github.com/psviderski/uncloud/pkg/client/operation"
 	"github.com/spf13/cobra"
 )
 

cmd/uc/image/ls.go

@@ -13,6 +13,7 @@ import (
 	"github.com/charmbracelet/colorprofile"
 	"github.com/containerd/platforms"
 	"github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/pkg/stringid"
 	"github.com/docker/go-units"
 
 	"github.com/psviderski/uncloud/internal/cli"
@@ -90,9 +91,14 @@ func list(ctx context.Context, uncli *cli.CLI, opts listOptions) error {
 
 	machines := cli.ExpandCommaSeparatedValues(opts.machines)
 
-	clusterImages, err := clusterClient.ListImages(ctx, api.ImageFilter{
-		Machines: machines,
-		Name:     opts.nameFilter,
+	var clusterImages []api.MachineImages
+	err = tui.RunSpinner(ctx, "Listing images...", func(ctx context.Context) error {
+		var err error
+		clusterImages, err = clusterClient.ListImages(ctx, api.ImageFilter{
+			Machines: machines,
+			Name:     opts.nameFilter,
+		})
+		return err
 	})
 	if err != nil {
 		return fmt.Errorf("list images: %w", err)
@@ -102,7 +108,7 @@ func list(ctx context.Context, uncli *cli.CLI, opts listOptions) error {
 	var rows []imageRow
 
 	for _, machineImages := range clusterImages {
-		if err := machineImages.Error(); err != nil {
+		if err := machineImages.Metadata.Err(); err != nil {
 			tui.PrintWarning(fmt.Sprintf("failed to list images on machine '%s': %s",
 				machineImages.Metadata.MachineName, err))
 			continue
@@ -116,49 +122,7 @@ func list(ctx context.Context, uncli *cli.CLI, opts listOptions) error {
 			store = "containerd"
 		}
 
-		// Process each image for this machine.
-		for _, img := range machineImages.Images {
-			// Show the first 12 chars without 'sha256:' as the image ID like Docker does.
-			id := strings.TrimPrefix(img.ID, "sha256:")[:12]
-
-			name := "<none>"
-			if len(img.RepoTags) > 0 && img.RepoTags[0] != "<none>:<none>" {
-				name = img.RepoTags[0]
-			}
-
-			imgPlatforms, _ := imagePlatforms(img)
-			formattedPlatforms := formatPlatforms(imgPlatforms)
-
-			created := ""
-			createdAt := time.Unix(img.Created, 0)
-			if !createdAt.IsZero() {
-				created = units.HumanDuration(time.Now().UTC().Sub(createdAt)) + " ago"
-			}
-
-			size := units.HumanSizeWithPrecision(float64(img.Size), 3)
-
-			// Check if the image is in use by any containers. Only supported by Docker API >=1.51
-			inUse := "-"
-			if img.Containers != -1 { // -1 means the info is not available.
-				if img.Containers > 0 {
-					inUse = lipgloss.NewStyle().Foreground(lipgloss.Color("10")).Render("●")
-				} else {
-					inUse = lipgloss.NewStyle().Foreground(lipgloss.Color("8")).Render("○")
-				}
-			}
-
-			rows = append(rows, imageRow{
-				id:           id,
-				name:         name,
-				platforms:    formattedPlatforms,
-				createdHuman: created,
-				createdUnix:  img.Created,
-				size:         size,
-				inUse:        inUse,
-				store:        store,
-				machine:      machineName,
-			})
-		}
+		rows = append(rows, imageRows(machineImages.Images, machineName, store)...)
 	}
 
 	if len(rows) == 0 {
@@ -184,13 +148,55 @@ func list(ctx context.Context, uncli *cli.CLI, opts listOptions) error {
 	return nil
 }
 
+// imageRows keeps every stored name visible and retains digest-only and unnamed images.
+func imageRows(images []image.Summary, machineName, store string) []imageRow {
+	var rows []imageRow
+	for _, img := range images {
+		// RepoTags includes stored digest names on containerd. RepoDigests can include derived names.
+		imageNames := img.RepoTags
+		if len(imageNames) == 0 {
+			imageNames = []string{"<untagged>"}
+		}
+
+		imgPlatforms, _ := imagePlatforms(img)
+		created := ""
+		if img.Created > 0 {
+			created = units.HumanDuration(time.Since(time.Unix(img.Created, 0))) + " ago"
+		}
+		// Check if the image is in use by any containers. Only supported by Docker API >=1.51
+		inUse := "-"
+		if img.Containers >= 0 { // -1 means the info is not available.
+			inUse = lipgloss.NewStyle().Foreground(lipgloss.Color("8")).Render("○")
+			if img.Containers > 0 {
+				inUse = lipgloss.NewStyle().Foreground(lipgloss.Color("10")).Render("●")
+			}
+		}
+
+		for _, name := range imageNames {
+			rows = append(rows, imageRow{
+				id:           stringid.TruncateID(img.ID),
+				name:         name,
+				platforms:    formatPlatforms(imgPlatforms),
+				createdHuman: created,
+				createdUnix:  img.Created,
+				size:         units.HumanSizeWithPrecision(float64(img.Size), 3),
+				inUse:        inUse,
+				store:        store,
+				machine:      machineName,
+			})
+		}
+	}
+
+	return rows
+}
+
 // imagePlatforms returns a list of platforms supported by the image and a boolean indicating if it's multi-platform.
 func imagePlatforms(img image.Summary) ([]string, bool) {
 	var formattedPlatforms []string
 	multiPlatform := false
 
 	for _, m := range img.Manifests {
-		if m.Kind != image.ManifestKindImage || !m.Available {
+		if m.Kind != image.ManifestKindImage || !m.Available || m.ImageData == nil {
 			continue
 		}
 

cmd/uc/image/rm.go

@@ -0,0 +1,137 @@
+package image
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+
+	"charm.land/lipgloss/v2"
+	"github.com/docker/compose/v2/pkg/progress"
+	"github.com/psviderski/uncloud/internal/cli"
+	"github.com/psviderski/uncloud/internal/cli/completion"
+	"github.com/psviderski/uncloud/internal/cli/tui"
+	"github.com/spf13/cobra"
+)
+
+type removeOptions struct {
+	machines []string
+	yes      bool
+}
+
+func NewRemoveCommand() *cobra.Command {
+	opts := removeOptions{}
+	cmd := &cobra.Command{
+		Use:     "rm IMAGE [IMAGE...]",
+		Aliases: []string{"remove", "delete"},
+		Short:   "Remove images from machines in the cluster.",
+		Long: `Remove images from all or selected machines in the cluster.
+
+An image name without a tag selects all its tags. Specify a tag, such as myapp:latest, to remove
+only that tag.
+
+Wildcard patterns are supported for image names and tags and should be quoted to prevent your
+shell from expanding them. Removing by image ID attempts to remove each name for that image
+independently.
+
+Images used by running or stopped containers cannot be removed. Unused tags can be removed even
+when the same image is used under another tag. Failed removals do not prevent other removals.`,
+		Example: `  # Remove a tag from all machines after confirming the plan.
+  uc image rm myapp:old
+
+  # Remove all tags for an image name from all machines.
+  uc image rm myapp
+
+  # Remove matching tags from two machines without confirmation.
+  uc image rm 'myapp:1.*' 'otherapp:*' -m machine1,machine2 --yes
+
+  # Remove all names for an image by ID from all machines.
+  uc image rm ee8fed0e9618`,
+		Args: cobra.MinimumNArgs(1),
+		PreRun: func(cmd *cobra.Command, args []string) {
+			cli.BindEnvToFlag(cmd, "yes", "UNCLOUD_AUTO_CONFIRM")
+		},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			uncli := cmd.Context().Value("cli").(*cli.CLI)
+			return remove(cmd.Context(), uncli, args, opts)
+		},
+	}
+
+	cmd.Flags().StringSliceVarP(&opts.machines, "machine", "m", nil,
+		"Machine names or IDs to remove images from. Can be specified multiple times or as a comma-separated list.\n"+
+			"If not specified, the matching images will be removed from all machines.")
+	cmd.Flags().BoolVarP(&opts.yes, "yes", "y", false,
+		"Auto-confirm the removal plan. Should be explicitly set when running non-interactively,\n"+
+			"e.g., in CI/CD pipelines. [$UNCLOUD_AUTO_CONFIRM]")
+
+	completion.MachinesFlag(cmd)
+
+	return cmd
+}
+
+func remove(ctx context.Context, uncli *cli.CLI, images []string, opts removeOptions) error {
+	clusterClient, err := uncli.ConnectCluster(ctx)
+	if err != nil {
+		return fmt.Errorf("connect to cluster: %w", err)
+	}
+	defer clusterClient.Close()
+
+	plan, err := planImageRemoval(ctx, clusterClient, images, cli.ExpandCommaSeparatedValues(opts.machines))
+	if err != nil {
+		return fmt.Errorf("plan image removal: %w", err)
+	}
+	directConn := uncli.DirectConnection()
+	contextName := uncli.ContextOverrideOrCurrent()
+	cluster := ""
+	if directConn != "" {
+		cluster = directConn
+		lipgloss.Println(tui.Faint.Render("connection: ") + tui.NameStyle.Render(directConn))
+		lipgloss.Println()
+	} else if contextName != "" && len(uncli.Config.Contexts) > 1 {
+		// Only show context if there's more than one to avoid unnecessary clutter.
+		cluster = contextName
+		lipgloss.Println(tui.Faint.Render("context: ") + tui.NameStyle.Render(contextName))
+		lipgloss.Println()
+	}
+
+	lipgloss.Println(plan.Format())
+
+	if !opts.yes {
+		if !tui.IsTerminalAvailable() {
+			return errors.New("cannot ask to confirm image removal in non-interactive mode, " +
+				"use --yes flag or set UNCLOUD_AUTO_CONFIRM=true to auto-confirm")
+		}
+
+		title := "Proceed with image removal?"
+		if cluster != "" {
+			isDark := lipgloss.HasDarkBackground(os.Stdin, os.Stdout)
+			confirmStyle := tui.ThemeConfirm().Theme(isDark).Focused.Title
+			title = "Proceed with image removal on " + tui.NameStyle.Render(cluster) + confirmStyle.Render("?")
+		}
+
+		confirmed, err := tui.Confirm(title)
+		if err != nil {
+			return fmt.Errorf("confirm image removal: %w", err)
+		}
+		if !confirmed {
+			return cli.Cancelled("Image removal cancelled. No images were removed.")
+		}
+	}
+
+	untagged := make(map[string]bool)
+	var errs []error
+	for i, group := range plan.GroupPlans {
+		if i > 0 {
+			fmt.Println()
+		}
+
+		err := progress.RunWithTitle(ctx, func(ctx context.Context) error {
+			return group.Execute(ctx, clusterClient, untagged)
+		}, uncli.ProgressOut(), "Removing image "+group.Image)
+		if err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	return errors.Join(errs...)
+}

cmd/uc/image/rm_plan.go

@@ -0,0 +1,426 @@
+package image
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"path"
+	"regexp"
+	"slices"
+	"strings"
+
+	"charm.land/lipgloss/v2"
+	"github.com/distribution/reference"
+	"github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/pkg/stringid"
+	"github.com/psviderski/uncloud/internal/cli/tui"
+	"github.com/psviderski/uncloud/pkg/api"
+)
+
+var imageIDRegex = regexp.MustCompile(`^(sha256:)?[a-f0-9]{4,64}$`)
+
+// imageRemovalPlan contains all image removal operations grouped by the user-supplied image name, ID, or pattern.
+type imageRemovalPlan struct {
+	GroupPlans []*removeImageGroupPlan
+}
+
+func (p *imageRemovalPlan) IsEmpty() bool { return len(p.GroupPlans) == 0 }
+
+func (p *imageRemovalPlan) Format() string {
+	var out strings.Builder
+	machines := make(map[string]struct{})
+	removeCount := 0
+	for _, group := range p.GroupPlans {
+		out.WriteString(group.Format())
+		for _, op := range group.Operations {
+			machines[op.MachineName] = struct{}{}
+			removeCount++
+		}
+	}
+
+	summary := fmt.Sprintf("%s remove %s across %s %s",
+		tui.BoldRed.Render(fmt.Sprint(removeCount)),
+		tui.Faint.Render("·"),
+		tui.Bold.Render(fmt.Sprint(len(machines))),
+		pluralMachines(len(machines)),
+	)
+	out.WriteString("\n" + tui.Faint.Render(strings.Repeat("─", lipgloss.Width(summary))) + "\n" + summary + "\n")
+
+	return out.String()
+}
+
+func pluralMachines(count int) string {
+	if count == 1 {
+		return "machine"
+	}
+	return "machines"
+}
+
+// Execute applies the frozen plan, collecting failures without discovering new targets.
+func (p *imageRemovalPlan) Execute(ctx context.Context, cli api.ImageClient) error {
+	untagged := make(map[string]bool)
+	var errs []error
+	for _, group := range p.GroupPlans {
+		if err := group.Execute(ctx, cli, untagged); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	return errors.Join(errs...)
+}
+
+// removeImageGroupPlan groups removals for one image name, ID, or pattern supplied by the user.
+type removeImageGroupPlan struct {
+	// Image is the image name, ID, or pattern supplied by the user.
+	Image      string
+	Operations []*removeImageOperation
+}
+
+func (o *removeImageGroupPlan) Execute(ctx context.Context, cli api.ImageClient, untagged map[string]bool) error {
+	var errs []error
+	for _, op := range o.Operations {
+		if err := ctx.Err(); err != nil {
+			return errors.Join(append(errs, err)...)
+		}
+		if err := op.Execute(ctx, cli, untagged); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	return errors.Join(errs...)
+}
+
+func (o *removeImageGroupPlan) Format() string {
+	var out strings.Builder
+	out.WriteString(tui.BoldRed.Render("-") + " remove image " + tui.NameStyle.Render(o.Image) + "\n")
+	for i, op := range o.Operations {
+		branch := "  ├── "
+		if i == len(o.Operations)-1 {
+			branch = "  ╰── "
+		}
+		out.WriteString(tui.Faint.Render(branch) + op.Format() + "\n")
+	}
+	return out.String()
+}
+
+func (o *removeImageGroupPlan) String() string {
+	return fmt.Sprintf("removeImageGroupPlan[image=%s]", o.Image)
+}
+
+// removeImageOperation removes an image name or an unnamed image by ID on a machine.
+type removeImageOperation struct {
+	MachineName string
+	ImageID     string
+	// Image is the exact image name or ID sent to Docker.
+	Image string
+}
+
+func (o *removeImageOperation) Execute(ctx context.Context, cli api.ImageClient, untagged map[string]bool) error {
+	if untagged[o.MachineName+"\x00"+o.Image] {
+		return nil
+	}
+	results, err := cli.RemoveImage(ctx, o.Image, api.RemoveImageOptions{Machines: []string{o.MachineName}})
+	// A removal may also untag other planned names. Track actual results across all groups, per machine.
+	for _, result := range results {
+		for _, removal := range result.Results {
+			if removal.Untagged != "" {
+				untagged[result.Metadata.MachineName+"\x00"+removal.Untagged] = true
+			}
+		}
+	}
+	if errors.Is(err, api.ErrNotFound) {
+		return nil
+	}
+	if err != nil {
+		return fmt.Errorf("remove image '%s': %w", o.Image, err)
+	}
+	return nil
+}
+
+func (o *removeImageOperation) Format() string {
+	return tui.BoldRed.Render("-") + " " + tui.FormatImage(o.Image, tui.NoStyle) +
+		tui.Faint.Render(" ("+stringid.TruncateID(o.ImageID)+") on ") + o.MachineName
+}
+
+func (o *removeImageOperation) String() string {
+	return fmt.Sprintf("removeImageOperation[machine_name=%s image=%s]", o.MachineName, o.Image)
+}
+
+type machineImageInventory struct {
+	machineName string
+	images      []image.Summary
+}
+
+// planImageRemoval builds a removal plan grouped by input argument from images on the selected machines.
+// An empty machines list selects all machines.
+//
+// Arguments expand as follows:
+//   - Name: without a tag or digest, select all stored names in that exact repository across image IDs.
+//     An explicit tag selects only that tag. Familiar names are normalised.
+//   - ID: select all RepoTags for the matching image, or its full ID if unnamed. A prefix must identify
+//     one unique full ID across the selected machines.
+//   - Pattern: match RepoTags only. A matching digest also selects that image's names in the same repository.
+//   - Digest: resolve through RepoTags, RepoDigests, or the image ID, then select that image's names in
+//     the same repository. If none exist but RepoDigests contains the reference, select the digest itself.
+//
+// Selecting all tags for a repository/image on a machine also adds its stored digest references after
+// the tags, even if those digests did not match an argument. Stored names are kept as is, and overlapping
+// selections produce only one operation per machine and name.
+//
+// Failed image listings produce warnings and exclude those machines from the plan. If no machine can
+// be queried, planning fails. Every argument must match on a successfully queried machine. Unmatched
+// or invalid arguments and ambiguous ID prefixes reject the whole plan before any removal.
+//
+// Planning does not check container usage. The backend checks each removal during execution, and failures
+// do not stop other operations. Tag removal may implicitly untag a used digest. Execution skips names
+// already untagged by earlier operations and tolerates names that disappeared after planning.
+func planImageRemoval(ctx context.Context, cli api.ImageClient, images, machines []string) (*imageRemovalPlan, error) {
+	if len(images) == 0 {
+		return nil, errors.New("at least one image is required")
+	}
+
+	var clusterImages []api.MachineImages
+	err := tui.RunSpinner(ctx, "Finding images to remove...", func(ctx context.Context) error {
+		var err error
+		clusterImages, err = cli.ListImages(ctx, api.ImageFilter{Machines: machines})
+		return err
+	})
+	if err != nil {
+		return nil, fmt.Errorf("list images: %w", err)
+	}
+
+	var inventory []*machineImageInventory
+	for _, machineImages := range clusterImages {
+		if err := machineImages.Metadata.Err(); err != nil {
+			tui.PrintWarning(fmt.Sprintf("failed to list images on machine '%s': %s",
+				machineImages.Metadata.MachineName, err))
+			continue
+		}
+		machine := &machineImageInventory{
+			machineName: machineImages.Metadata.MachineName,
+			images:      machineImages.Images,
+		}
+		inventory = append(inventory, machine)
+	}
+	if len(inventory) == 0 {
+		return nil, errors.New("failed to list images on any machine")
+	}
+
+	return planImageRemovalFromInventory(images, inventory)
+}
+
+func planImageRemovalFromInventory(images []string, inventory []*machineImageInventory) (*imageRemovalPlan, error) {
+	plan := &imageRemovalPlan{}
+	seen := make(map[string]bool)
+	var errs []error
+	for _, imageArg := range images {
+		group := &removeImageGroupPlan{Image: imageArg}
+		isID := imageIDRegex.MatchString(imageArg)
+		isPattern := strings.ContainsAny(imageArg, "*?[")
+		var namedRef reference.Named
+		if isPattern {
+			if _, err := path.Match(imageArg, ""); err != nil {
+				return nil, fmt.Errorf("invalid image pattern '%s': %w", imageArg, err)
+			}
+		} else if !isID {
+			var err error
+			namedRef, err = reference.ParseNormalizedNamed(imageArg)
+			if err != nil {
+				return nil, fmt.Errorf("invalid image '%s': %w", imageArg, err)
+			}
+		}
+		if isID {
+			matches := make(map[string]bool)
+			for _, machine := range inventory {
+				for _, img := range machine.images {
+					if imageIDMatches(img.ID, imageArg) {
+						matches[img.ID] = true
+					}
+				}
+			}
+			if len(matches) > 1 {
+				var candidates []string
+				for id := range matches {
+					candidates = append(candidates, id)
+				}
+				slices.Sort(candidates)
+				errs = append(errs,
+					fmt.Errorf("image ID '%s' is ambiguous: %s", imageArg, strings.Join(candidates, ", ")))
+				continue
+			}
+		}
+
+		matched := false
+		for _, machine := range inventory {
+			for _, img := range machine.images {
+				var imagesToRemove []string
+				switch {
+				case isID:
+					if !imageIDMatches(img.ID, imageArg) {
+						continue
+					}
+					matched = true
+					// Expand only stored names, matching uc image ls. RepoDigests remains available for digest lookup.
+					imagesToRemove = img.RepoTags
+					if len(imagesToRemove) == 0 {
+						imagesToRemove = []string{img.ID}
+					}
+				case isPattern:
+					for _, ref := range img.RepoTags {
+						if ok, _ := path.Match(imageArg, ref); ok {
+							named, _ := reference.ParseDockerRef(ref)
+							if _, digest := named.(reference.Canonical); digest {
+								imagesToRemove = append(imagesToRemove,
+									imageRepositoryReferences(img.RepoTags, named.Name())...)
+							} else {
+								imagesToRemove = append(imagesToRemove, ref)
+							}
+						}
+					}
+				case reference.IsNameOnly(namedRef):
+					imagesToRemove = imageRepositoryReferences(img.RepoTags, namedRef.Name())
+				default:
+					if canonical, digest := namedRef.(reference.Canonical); digest {
+						ref := reference.FamiliarString(namedRef)
+						if canonical.Digest().String() != img.ID && !slices.Contains(img.RepoTags, ref) &&
+							!slices.Contains(img.RepoDigests, ref) {
+							continue
+						}
+						imagesToRemove = imageRepositoryReferences(img.RepoTags, namedRef.Name())
+						if len(imagesToRemove) == 0 && slices.Contains(img.RepoDigests, ref) {
+							// An explicitly requested digest can resolve even when no stored name is listed.
+							imagesToRemove = []string{ref}
+						}
+					} else if slices.Contains(img.RepoTags, reference.FamiliarString(namedRef)) {
+						imagesToRemove = []string{reference.FamiliarString(namedRef)}
+					}
+				}
+				for _, ref := range imagesToRemove {
+					matched = true
+					key := machine.machineName + "\x00" + ref
+					if !seen[key] {
+						seen[key] = true
+						group.Operations = append(group.Operations, &removeImageOperation{
+							MachineName: machine.machineName, ImageID: img.ID, Image: ref,
+						})
+					}
+				}
+			}
+		}
+		if !matched {
+			errs = append(errs, fmt.Errorf("image '%s' not found on any machine", imageArg))
+		}
+		slices.SortFunc(group.Operations, compareImageRemovalOperations)
+		if len(group.Operations) > 0 {
+			plan.GroupPlans = append(plan.GroupPlans, group)
+		}
+	}
+
+	planDigestRemovals(plan, inventory)
+	if err := errors.Join(errs...); err != nil {
+		return nil, err
+	}
+	return plan, nil
+}
+
+func imageRepositoryReferences(refs []string, repository string) []string {
+	var matches []string
+	for _, ref := range refs {
+		if named, err := reference.ParseDockerRef(ref); err == nil && named.Name() == repository {
+			matches = append(matches, ref)
+		}
+	}
+	return matches
+}
+
+// planDigestRemovals includes stored digests with the group removing their last repository tag.
+// RepoDigests also contains synthesised references, so only digest names stored in RepoTags get operations here.
+func planDigestRemovals(plan *imageRemovalPlan, inventory []*machineImageInventory) {
+	type repository struct {
+		remainingTags int
+		digests       []string
+	}
+	repositories := make(map[string]*repository)
+	for _, machine := range inventory {
+		for _, img := range machine.images {
+			names := slices.Clone(img.RepoTags)
+			slices.Sort(names)
+			for _, ref := range slices.Compact(names) {
+				named, err := reference.ParseDockerRef(ref)
+				if err != nil {
+					continue
+				}
+				key := machine.machineName + "\x00" + img.ID + "\x00" + named.Name()
+				repo := repositories[key]
+				if repo == nil {
+					repo = &repository{}
+					repositories[key] = repo
+				}
+				if _, tagged := named.(reference.Tagged); tagged {
+					repo.remainingTags++
+				} else if _, digest := named.(reference.Canonical); digest {
+					repo.digests = append(repo.digests, ref)
+				}
+			}
+		}
+	}
+	emitted := make(map[string]bool)
+	var groups []*removeImageGroupPlan
+	for _, group := range plan.GroupPlans {
+		var operations []*removeImageOperation
+		for _, op := range group.Operations {
+			key := op.MachineName + "\x00" + op.Image
+			if emitted[key] {
+				continue
+			}
+			emitted[key] = true
+			operations = append(operations, op)
+			named, err := reference.ParseDockerRef(op.Image)
+			if err != nil {
+				continue
+			}
+			if _, tagged := named.(reference.Tagged); !tagged {
+				continue
+			}
+			repo := repositories[op.MachineName+"\x00"+op.ImageID+"\x00"+named.Name()]
+			if repo == nil {
+				continue
+			}
+			repo.remainingTags--
+			if repo.remainingTags != 0 {
+				continue
+			}
+			for _, digest := range repo.digests {
+				key := op.MachineName + "\x00" + digest
+				if !emitted[key] {
+					emitted[key] = true
+					operations = append(operations, &removeImageOperation{
+						MachineName: op.MachineName, ImageID: op.ImageID, Image: digest,
+					})
+				}
+			}
+		}
+		group.Operations = operations
+		slices.SortFunc(group.Operations, compareImageRemovalOperations)
+		if len(group.Operations) > 0 {
+			groups = append(groups, group)
+		}
+	}
+	plan.GroupPlans = groups
+}
+
+func compareImageRemovalOperations(a, b *removeImageOperation) int {
+	aDigest, bDigest := strings.Contains(a.Image, "@"), strings.Contains(b.Image, "@")
+	if aDigest != bDigest {
+		if aDigest {
+			return 1
+		}
+		return -1
+	}
+	if c := strings.Compare(a.Image, b.Image); c != 0 {
+		return c
+	}
+	return strings.Compare(a.MachineName, b.MachineName)
+}
+
+func imageIDMatches(id, prefix string) bool {
+	return strings.HasPrefix(strings.TrimPrefix(id, "sha256:"), strings.TrimPrefix(prefix, "sha256:"))
+}

cmd/uc/image/rm_plan_test.go

@@ -0,0 +1,405 @@
+package image
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/docker/docker/api/types/image"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestPlanImageRemovalFromInventory_Selectors(t *testing.T) {
+	idA, idB := testImageID("a"), testImageID("b")
+	digestRef := "myapp@" + testImageID("c")
+	tests := []struct {
+		name      string
+		selector  string
+		inventory []*machineImageInventory
+		want      []removeImageOperation
+	}{
+		{
+			name: "repository selects all stored names across images and machines", selector: "myapp",
+			inventory: []*machineImageInventory{
+				testMachineInventory("dev1", []image.Summary{
+					testImage(idA, "myapp:old", "other:keep"),
+					testImage(idB, "myapp:latest"),
+					testImage(testImageID("c"), digestRef),
+					testImage(testImageID("d"), "myapp-extra:latest", "team/myapp:latest", "myapp/worker:latest"),
+				}),
+				testMachineInventory("machine2", []image.Summary{testImage(idB, "myapp:test")}),
+			},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idB, Image: "myapp:latest"},
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "machine2", ImageID: idB, Image: "myapp:test"},
+				{MachineName: "dev1", ImageID: testImageID("c"), Image: digestRef},
+			},
+		},
+		{
+			name: "repository without latest includes its tags and stored digest", selector: "myapp",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "myapp:old", digestRef, "other:keep"),
+			})},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "dev1", ImageID: idA, Image: digestRef},
+			},
+		},
+		{
+			name: "explicit latest selects only that tag", selector: "myapp:latest",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "myapp:old", "myapp:latest", digestRef),
+			})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: "myapp:latest"}},
+		},
+		{
+			name: "qualified repository selects familiar names", selector: "docker.io/library/myapp",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "myapp:old", "myapp:latest", "other:keep"),
+			})},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:latest"},
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+			},
+		},
+		{
+			name: "registry port does not count as an explicit tag", selector: "registry.example.com:5000/team/myapp",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "registry.example.com:5000/team/myapp:old", "registry.example.com:5000/team/myapp:new",
+					"registry.example.com:5001/team/myapp:keep", "registry.example.com:5000/team/myapp/worker:keep"),
+			})},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "registry.example.com:5000/team/myapp:new"},
+				{MachineName: "dev1", ImageID: idA, Image: "registry.example.com:5000/team/myapp:old"},
+			},
+		},
+		{
+			name: "explicit tag with registry port stays exact", selector: "registry.example.com:5000/team/myapp:old",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "registry.example.com:5000/team/myapp:old", "registry.example.com:5000/team/myapp:new"),
+			})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: "registry.example.com:5000/team/myapp:old"}},
+		},
+		{
+			name: "tag uses each machines local image and allows missing copies", selector: "myapp:old",
+			inventory: []*machineImageInventory{
+				testMachineInventory("machine2", []image.Summary{testImage(idB, "myapp:old")}),
+				testMachineInventory("empty", nil),
+				testMachineInventory("dev1", []image.Summary{testImage(idA, "myapp:old")}),
+			},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "machine2", ImageID: idB, Image: "myapp:old"},
+			},
+		},
+		{
+			name: "qualified names use familiar references", selector: "docker.io/library/myapp:old",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "myapp:old"),
+			})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: "myapp:old"}},
+		},
+		{
+			name: "full ID expands all repositories and deduplicates references per machine", selector: idA,
+			inventory: []*machineImageInventory{
+				testMachineInventory("dev1", []image.Summary{
+					{
+						ID:       idA,
+						RepoTags: []string{"other:keep", "myapp:old", "myapp:old", digestRef, "other@" + testImageID("c")},
+						RepoDigests: []string{
+							digestRef, "other@" + testImageID("c"), "other@" + testImageID("c"), testImageID("c"),
+						},
+					},
+					testImage(idB, "unrelated:keep"),
+				}),
+				testMachineInventory("machine2", []image.Summary{{
+					ID: idA, RepoTags: []string{"myapp:old", digestRef}, RepoDigests: []string{digestRef},
+				}}),
+			},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "machine2", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "dev1", ImageID: idA, Image: "other:keep"},
+				{MachineName: "dev1", ImageID: idA, Image: digestRef},
+				{MachineName: "machine2", ImageID: idA, Image: digestRef},
+				{MachineName: "dev1", ImageID: idA, Image: "other@" + testImageID("c")},
+			},
+		},
+		{
+			name: "same full ID on multiple machines is unambiguous", selector: "aaaaaaaa",
+			inventory: []*machineImageInventory{
+				testMachineInventory("dev1", []image.Summary{testImage(idA, "myapp:old")}),
+				testMachineInventory("dev1", []image.Summary{testImage(idB, "myapp:latest")}),
+				testMachineInventory("machine2", []image.Summary{testImage(idA, "other:test")}),
+			},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "machine2", ImageID: idA, Image: "other:test"},
+			},
+		},
+		{
+			name: "short ID with algorithm prefix", selector: "sha256:aaaaaaaa",
+			inventory: []*machineImageInventory{testMachineInventory("dev1",
+				[]image.Summary{testImage(idA, "myapp:old")})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: "myapp:old"}},
+		},
+		{
+			name: "unnamed image is removed by its full ID", selector: idA,
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{{ID: idA}})},
+			want:      []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: idA}},
+		},
+		{
+			name: "ID expands only stored names", selector: idA,
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{{
+				ID: idA, RepoTags: []string{"myapp:latest"},
+				RepoDigests: []string{"myapp@" + idA, "other@" + idA},
+			}})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: "myapp:latest"}},
+		},
+		{
+			name: "ID removes an untagged image by ID even if RepoDigests is populated", selector: idA,
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{{
+				ID: idA, RepoDigests: []string{digestRef},
+			}})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: idA}},
+		},
+		{
+			name: "synthesized digest selects repository tags without a digest row", selector: digestRef,
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{{
+				ID: idA, RepoTags: []string{"myapp:old", "other:keep", "myapp:latest"},
+				RepoDigests: []string{digestRef, "other@" + testImageID("c")},
+			}})},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:latest"},
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+			},
+		},
+		{
+			name: "explicit digest lookup works without stored names", selector: digestRef,
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{{
+				ID: idA, RepoDigests: []string{digestRef},
+			}})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: digestRef}},
+		},
+		{
+			name: "synthesized digest resolves by target and repository even if not listed", selector: "myapp@" + idA,
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{{
+				ID: idA, RepoTags: []string{"myapp:old", "other:keep"}, RepoDigests: []string{"other@" + idA},
+			}})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: "myapp:old"}},
+		},
+		{
+			name: "stored digest follows its repository tags", selector: digestRef,
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "myapp:old", "myapp:latest", digestRef, "other:keep"),
+				testImage(idB, "myapp@"+idB),
+			})},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:latest"},
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "dev1", ImageID: idA, Image: digestRef},
+			},
+		},
+		{
+			name: "digest pattern also expands matching repository tags", selector: "myapp@sha256:c*",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "myapp:old", "myapp:latest", digestRef, "other:keep"),
+				testImage(idB, "myapp@"+idB),
+			})},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:latest"},
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "dev1", ImageID: idA, Image: digestRef},
+			},
+		},
+		{
+			name: "digest pattern matches stored names and ignores derived names", selector: "myapp@sha256:*",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "myapp:old", digestRef),
+				{ID: idB, RepoTags: []string{"myapp:latest"}, RepoDigests: []string{"myapp@" + idB}},
+			})},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "dev1", ImageID: idA, Image: digestRef},
+			},
+		},
+		{
+			name: "last repository tag includes its stored digest", selector: "myapp:old",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "myapp:old", digestRef, "other:keep"),
+			})},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:old"},
+				{MachineName: "dev1", ImageID: idA, Image: digestRef},
+			},
+		},
+		{
+			name: "last tag does not add a synthesized digest row", selector: "myapp:old",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{{
+				ID: idA, RepoTags: []string{"myapp:old", "other:keep"}, RepoDigests: []string{digestRef},
+			}})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: "myapp:old"}},
+		},
+		{
+			name: "remaining repository tag preserves its stored digest", selector: "myapp:old",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, "myapp:old", "myapp:latest", digestRef),
+			})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: "myapp:old"}},
+		},
+		{
+			name: "digest without repository tags remains executable", selector: digestRef,
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+				testImage(idA, digestRef, "other:keep"),
+			})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: digestRef}},
+		},
+		{
+			name: "digest-only image keeps its named reference", selector: idA,
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{{
+				ID: idA, RepoTags: []string{digestRef}, RepoDigests: []string{digestRef, testImageID("c")},
+			}})},
+			want: []removeImageOperation{{MachineName: "dev1", ImageID: idA, Image: digestRef}},
+		},
+		{
+			name: "tag pattern selects only matching tags", selector: "myapp:1.[12]",
+			inventory: []*machineImageInventory{testMachineInventory("dev1", []image.Summary{{
+				ID: idA, RepoTags: []string{"myapp:1.3", "myapp:1.2", "myapp:1.1"}, RepoDigests: []string{digestRef},
+			}})},
+			want: []removeImageOperation{
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:1.1"},
+				{MachineName: "dev1", ImageID: idA, Image: "myapp:1.2"},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			plan, err := planImageRemovalFromInventory([]string{tt.selector}, tt.inventory)
+			require.NoError(t, err)
+
+			require.Len(t, plan.GroupPlans, 1)
+			assert.Equal(t, tt.selector, plan.GroupPlans[0].Image)
+
+			var got []removeImageOperation
+			for _, op := range plan.GroupPlans[0].Operations {
+				got = append(got, *op)
+			}
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestPlanImageRemovalFromInventory_OverlappingSelectors(t *testing.T) {
+	inventory := []*machineImageInventory{
+		testMachineInventory("dev1", []image.Summary{testImage(testImageID("a"), "myapp:old", "myapp:latest")}),
+		testMachineInventory("machine2", []image.Summary{testImage(testImageID("b"), "myapp:test", "myapp:old")}),
+	}
+
+	plan, err := planImageRemovalFromInventory([]string{"myapp:old", "myapp", "myapp:*", testImageID("a"), "myapp:old"},
+		inventory)
+	require.NoError(t, err)
+
+	assert.Equal(t, &imageRemovalPlan{GroupPlans: []*removeImageGroupPlan{
+		{Image: "myapp:old", Operations: []*removeImageOperation{
+			{MachineName: "dev1", ImageID: testImageID("a"), Image: "myapp:old"},
+			{MachineName: "machine2", ImageID: testImageID("b"), Image: "myapp:old"},
+		}},
+		{Image: "myapp", Operations: []*removeImageOperation{
+			{MachineName: "dev1", ImageID: testImageID("a"), Image: "myapp:latest"},
+			{MachineName: "machine2", ImageID: testImageID("b"), Image: "myapp:test"},
+		}},
+	}}, plan, "the first selector owns each removal and empty groups are omitted")
+}
+
+func TestPlanImageRemovalFromInventory_DigestFollowsLastTagAcrossSelectors(t *testing.T) {
+	imageID := testImageID("a")
+	digestRef := "myapp@" + imageID
+	inventory := []*machineImageInventory{testMachineInventory("dev1", []image.Summary{
+		testImage(imageID, "myapp:old", "myapp:latest", "myapp:old", digestRef, digestRef, "other:keep"),
+	})}
+
+	plan, err := planImageRemovalFromInventory([]string{"myapp:old", "myapp:latest", digestRef}, inventory)
+	require.NoError(t, err)
+
+	assert.Equal(t, &imageRemovalPlan{GroupPlans: []*removeImageGroupPlan{
+		{Image: "myapp:old", Operations: []*removeImageOperation{
+			{MachineName: "dev1", ImageID: imageID, Image: "myapp:old"},
+		}},
+		{Image: "myapp:latest", Operations: []*removeImageOperation{
+			{MachineName: "dev1", ImageID: imageID, Image: "myapp:latest"},
+			{MachineName: "dev1", ImageID: imageID, Image: digestRef},
+		}},
+	}}, plan, "digest cleanup belongs to the last tag removal, so the later digest selector has no extra operation")
+}
+
+func TestPlanImageRemovalFromInventory_RejectsInvalidOrMissingSelectors(t *testing.T) {
+	idA := "sha256:abcdef" + strings.Repeat("a", 58)
+	idB := "sha256:abcdef" + strings.Repeat("b", 58)
+	inventory := []*machineImageInventory{
+		testMachineInventory("dev1", []image.Summary{{
+			ID: idA, RepoTags: []string{"myapp:old"}, RepoDigests: []string{"myapp@" + idA, "derived@" + idA},
+		}}),
+		testMachineInventory("machine2", []image.Summary{{ID: idB, RepoTags: []string{"myapp:old"}}}),
+	}
+
+	tests := []struct {
+		name   string
+		images []string
+		err    string
+	}{
+		{"missing repository", []string{"missing"}, "not found"},
+		{"repository only has a derived digest", []string{"derived"}, "not found"},
+		{"missing tag", []string{"myapp:missing"}, "not found"},
+		{"missing pattern", []string{"other:*"}, "not found"},
+		{"pattern only matches a derived digest", []string{"myapp@sha256:*"}, "not found"},
+		{"missing ID", []string{testImageID("c")}, "not found"},
+		{"ambiguous ID prefix", []string{"abcdef"}, "ambiguous"},
+		{"invalid name", []string{"MyApp:old"}, "invalid image"},
+		{"invalid pattern", []string{"myapp:["}, "invalid image pattern"},
+		{"one missing selector rejects the whole plan", []string{"myapp:old", "myapp:missing"}, "not found"},
+		{"one invalid selector rejects the whole plan", []string{"myapp:old", "myapp:["}, "invalid image pattern"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			plan, err := planImageRemovalFromInventory(tt.images, inventory)
+			require.ErrorContains(t, err, tt.err)
+			assert.Nil(t, plan, "a failed selector must not return a partial plan")
+		})
+	}
+
+	t.Run("ID prefix resolves within the supplied machines", func(t *testing.T) {
+		plan, err := planImageRemovalFromInventory([]string{"abcdef"}, inventory[:1])
+		require.NoError(t, err)
+		require.Len(t, plan.GroupPlans, 1)
+		require.Len(t, plan.GroupPlans[0].Operations, 1)
+		assert.Equal(t, idA, plan.GroupPlans[0].Operations[0].ImageID)
+	})
+}
+
+func TestPlanImageRemovalFromInventory_InUseImagesAreStillPlanned(t *testing.T) {
+	img := testImage(testImageID("a"), "myapp:old", "myapp:current")
+	img.Containers = 1
+
+	for _, selector := range []string{"myapp", "myapp:current", img.ID, "myapp:*"} {
+		t.Run(selector, func(t *testing.T) {
+			plan, err := planImageRemovalFromInventory([]string{selector}, []*machineImageInventory{
+				testMachineInventory("dev1", []image.Summary{img}),
+			})
+			require.NoError(t, err)
+			assert.False(t, plan.IsEmpty(), "usage protection belongs to the backend at execution time")
+		})
+	}
+}
+
+func testImageID(char string) string { return "sha256:" + strings.Repeat(char, 64) }
+
+func testImage(imageID string, tags ...string) image.Summary {
+	return image.Summary{ID: imageID, RepoTags: tags}
+}
+
+func testMachineInventory(name string, images []image.Summary) *machineImageInventory {
+	return &machineImageInventory{machineName: name, images: images}
+}

cmd/uc/image/root.go

@@ -13,6 +13,7 @@ func NewRootCommand() *cobra.Command {
 	cmd.AddCommand(
 		NewListCommand(),
 		NewPushCommand(),
+		NewRemoveCommand(),
 	)
 
 	return cmd

cmd/uc/machine/rtt.go

@@ -54,8 +54,8 @@ func rtt(ctx context.Context, uncli *cli.CLI) error {
 			tui.PrintWarning("metadata is missing in response from unknown server")
 			continue
 		}
-		if m.Metadata.Error != "" {
-			tui.PrintWarning(fmt.Sprintf("failed to inspect machine '%s': %s", m.Metadata.MachineName, m.Metadata.Error))
+		if err := m.Metadata.Err(); err != nil {
+			tui.PrintWarning(fmt.Sprintf("failed to inspect machine '%s': %s", m.Metadata.MachineName, err))
 			continue
 		}
 		if m.Machine == nil {

cmd/uc/ps.go

@@ -207,9 +207,9 @@ func collectContainers(ctx context.Context, cli *client.Client) ([]containerInfo
 
 		machineName := msc.Metadata.MachineName
 
-		if msc.Metadata.Error != "" {
+		if err := msc.Metadata.Err(); err != nil {
 			tui.PrintWarning(fmt.Sprintf("failed to list service containers on machine %s: %s",
-				machineName, msc.Metadata.Error))
+				machineName, err))
 			continue
 		}
 

internal/cli/progress/event.go

@@ -9,7 +9,7 @@ import (
 
 type eventIDKey struct{}
 
-// WithEventID returns a context that overrides the default event ID used by client methods.
+// WithEventID returns a context that overrides the event ID already set in the context.
 func WithEventID(ctx context.Context, eventID string) context.Context {
 	return context.WithValue(ctx, eventIDKey{}, eventID)
 }
@@ -48,7 +48,7 @@ func OldPreDeployHookEventID(serviceName, containerID, machineName string) strin
 		tui.Faint.Render(" on ") + machineName
 }
 
-// ImageEventID returns a progress event ID for image pull operations.
+// ImageEventID returns a progress event ID for image operations on a machine.
 func ImageEventID(image, machineName string) string {
 	return tui.Faint.Render("Image ") + image +
 		tui.Faint.Render(" on ") + machineName

internal/machine/caddyconfig/mocks_test.go

@@ -16,10 +16,19 @@ func NewMockCaddyfileValidator(t interface {
 	mock.TestingT
 	Cleanup(func())
 }) *MockCaddyfileValidator {
+	if helper, ok := t.(interface{ Helper() }); ok {
+		helper.Helper()
+	}
+
 	mock := &MockCaddyfileValidator{}
 	mock.Mock.Test(t)
 
-	t.Cleanup(func() { mock.AssertExpectations(t) })
+	t.Cleanup(func() {
+		if helper, ok := t.(interface{ Helper() }); ok {
+			helper.Helper()
+		}
+		mock.AssertExpectations(t)
+	})
 
 	return mock
 }

internal/machine/docker/client.go

@@ -167,7 +167,7 @@ func (c *Client) ListContainers(ctx context.Context, opts container.ListOptions)
 	machineContainers := make([]MachineContainers, len(resp.Messages))
 	for i, msg := range resp.Messages {
 		machineContainers[i].Metadata = msg.Metadata
-		if msg.Metadata != nil && msg.Metadata.Error != "" {
+		if msg.Metadata.Err() != nil {
 			continue
 		}
 
@@ -258,7 +258,7 @@ func (c *Client) InspectImage(ctx context.Context, id string) ([]api.MachineImag
 
 	notFoundCount := 0
 	for _, msg := range resp.Messages {
-		if msg.Metadata != nil && msg.Metadata.Status != nil && codes.Code(msg.Metadata.Status.Code) == codes.NotFound {
+		if status.Code(msg.Metadata.Err()) == codes.NotFound {
 			notFoundCount++
 		}
 	}
@@ -269,7 +269,7 @@ func (c *Client) InspectImage(ctx context.Context, id string) ([]api.MachineImag
 	images := make([]api.MachineImage, len(resp.Messages))
 	for i, msg := range resp.Messages {
 		images[i].Metadata = msg.Metadata
-		if msg.Metadata != nil && msg.Metadata.Error != "" {
+		if msg.Metadata.Err() != nil {
 			continue
 		}
 
@@ -312,7 +312,7 @@ func parseRemoteImageMessage(msg *pb.RemoteImage) (api.MachineRemoteImage, error
 	mri := api.MachineRemoteImage{
 		Metadata: msg.Metadata,
 	}
-	if msg.Metadata != nil && msg.Metadata.Error != "" {
+	if msg.Metadata.Err() != nil {
 		return mri, nil
 	}
 
@@ -393,7 +393,7 @@ func (c *Client) ListVolumes(ctx context.Context, opts volume.ListOptions) ([]Ma
 	machineVolumes := make([]MachineVolumes, len(resp.Messages))
 	for i, msg := range resp.Messages {
 		machineVolumes[i].Metadata = msg.Metadata
-		if msg.Metadata != nil && msg.Metadata.Error != "" {
+		if msg.Metadata.Err() != nil {
 			continue
 		}
 
@@ -472,7 +472,7 @@ func (c *Client) ListServiceContainers(
 	machineContainers := make([]MachineServiceContainers, len(resp.Messages))
 	for i, msg := range resp.Messages {
 		machineContainers[i].Metadata = msg.Metadata
-		if msg.Metadata != nil && msg.Metadata.Error != "" {
+		if msg.Metadata.Err() != nil {
 			continue
 		}
 

internal/machine/docker/controller.go

@@ -27,7 +27,7 @@ const (
 type Controller struct {
 	// machineID is the ID of the machine where the managed Docker daemon is running.
 	machineID string
-	client    *client.Client
+	client    client.APIClient
 	service   *Service
 	store     *store.Store
 }

internal/machine/docker/image.go

@@ -0,0 +1,79 @@
+package docker
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/containerd/errdefs"
+	"github.com/distribution/reference"
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/pkg/stringid"
+	"github.com/psviderski/uncloud/pkg/api"
+)
+
+// RemoveImage removes an image while protecting names used by containers, even when force is requested.
+func (s *Service) RemoveImage(ctx context.Context, id string, opts image.RemoveOptions) ([]image.DeleteResponse, error) {
+	if err := s.checkImageRemovalConflicts(ctx, id); err != nil {
+		return nil, err
+	}
+	// Docker enforces its own conflicts, including protection of a used image's final reference.
+	return s.Client.ImageRemove(ctx, id, opts)
+}
+
+// checkImageRemovalConflicts rejects an image ID used by a running or stopped container, or a name used by a
+// container while it still resolves to that container's image. A digest request also checks the repository tags
+// Docker would remove with it. Unused aliases are allowed.
+func (s *Service) checkImageRemovalConflicts(ctx context.Context, id string) error {
+	img, err := s.Client.ImageInspect(ctx, id)
+	if err != nil {
+		return err
+	}
+	// Match Docker's resolved ID before parsing names, since a short ID also parses as a repository name.
+	isID := strings.HasPrefix(strings.TrimPrefix(img.ID, "sha256:"), strings.TrimPrefix(id, "sha256:"))
+	var named reference.Named
+	if !isID {
+		named, err = reference.ParseDockerRef(id)
+		if err != nil {
+			return errdefs.ErrInvalidArgument.WithMessage(err.Error())
+		}
+	}
+	_, isDigest := named.(reference.Canonical)
+
+	containers, err := s.Client.ContainerList(ctx, container.ListOptions{
+		All: true, Filters: filters.NewArgs(filters.Arg("ancestor", img.ID)),
+	})
+	if err != nil {
+		return fmt.Errorf("list containers using image: %w", err)
+	}
+
+	for _, ctr := range containers {
+		// The ancestor filter can include descendants. A retagged name must also be checked against its current ID.
+		if ctr.ImageID != img.ID {
+			continue
+		}
+
+		usedRef, err := reference.ParseDockerRef(ctr.Image)
+		// Familiar names make "alpine:latest" and "docker.io/library/alpine:latest" identify the same tag.
+		removesUsedName := err == nil && named != nil && reference.FamiliarString(usedRef) == reference.FamiliarString(named)
+		if isDigest && err == nil && usedRef.Name() == named.Name() {
+			// Removing a digest also removes this repository's tags pointing at the same image.
+			removesUsedName = true
+		}
+		if isID || removesUsedName {
+			ctrID, state := stringid.TruncateID(ctr.ID), "stopped"
+			if serviceName := ctr.Labels[api.LabelServiceName]; serviceName != "" {
+				ctrID = serviceName + "/" + ctrID
+			}
+			if ctr.State == container.StateRunning || ctr.State == container.StatePaused {
+				state = container.StateRunning
+			}
+			return errdefs.ErrConflict.WithMessage(
+				fmt.Sprintf("image '%s' is used by container '%s' (%s)", id, ctrID, state))
+		}
+	}
+
+	return nil
+}

internal/machine/docker/image_test.go

@@ -0,0 +1,175 @@
+package docker
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/containerd/errdefs"
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/image"
+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+	"github.com/psviderski/uncloud/pkg/api"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCheckImageRemovalConflicts(t *testing.T) {
+	imageID := "sha256:" + strings.Repeat("a", 64)
+	otherID := "sha256:" + strings.Repeat("b", 64)
+	digestRef := "myapp@" + imageID
+
+	tests := []struct {
+		name             string
+		requested        string
+		configured       string
+		containerImageID string
+		serviceName      string
+		blocked          bool
+	}{
+		{name: "used tag", requested: "myapp:current", configured: "myapp:current", serviceName: "web", blocked: true},
+		{name: "qualified request", requested: "docker.io/library/myapp:current", configured: "myapp:current", blocked: true},
+		{name: "qualified container reference", requested: "myapp:current", configured: "docker.io/library/myapp:current", blocked: true},
+		{name: "implicit latest", requested: "myapp", configured: "myapp:latest", blocked: true},
+		{name: "unused alias", requested: "myapp:old", configured: "myapp:current"},
+		{name: "unused alias of ID-used image", requested: "myapp:old", configured: imageID},
+		{name: "tag may clean up a used digest", requested: "myapp:old", configured: digestRef},
+		{name: "used digest", requested: digestRef, configured: digestRef, blocked: true},
+		{name: "digest also removes used tag", requested: digestRef, configured: "myapp:current", blocked: true},
+		{name: "unused repository digest", requested: digestRef, configured: "other:keep"},
+		{name: "image ID", requested: imageID, configured: "myapp:current", blocked: true},
+		{name: "short image ID", requested: "aaaaaaaa", configured: "myapp:current", blocked: true},
+		{name: "short image ID with algorithm", requested: "sha256:aaaaaaaa", configured: "myapp:current", blocked: true},
+		{name: "retagged name", requested: "myapp:current", configured: "myapp:current", containerImageID: otherID},
+	}
+
+	for _, tt := range tests {
+		for _, state := range []string{container.StateExited, container.StateRunning} {
+			t.Run(fmt.Sprintf("%s/%s", tt.name, state), func(t *testing.T) {
+				containerImageID := tt.containerImageID
+				if containerImageID == "" {
+					containerImageID = imageID
+				}
+
+				cli := NewMockAPIClient(t)
+				cli.EXPECT().ImageInspect(mock.Anything, tt.requested).
+					Return(image.InspectResponse{ID: imageID}, nil).Once()
+				cli.EXPECT().ContainerList(mock.Anything, mock.MatchedBy(func(opts container.ListOptions) bool {
+					return opts.All // Stopped containers must be checked too.
+				})).Return([]container.Summary{{
+					ID:      strings.Repeat("c", 64),
+					Labels:  map[string]string{api.LabelServiceName: tt.serviceName},
+					Names:   []string{"/web"},
+					ImageID: containerImageID,
+					Image:   tt.configured,
+					State:   state,
+				}}, nil).Once()
+
+				service := NewService(cli, nil)
+				err := service.checkImageRemovalConflicts(context.Background(), tt.requested)
+
+				if tt.blocked {
+					require.True(t, errdefs.IsConflict(err), "%v", err)
+					assert.ErrorContains(t, err, tt.requested)
+					if tt.serviceName != "" {
+						assert.ErrorContains(t, err, "container 'web/cccccccccccc'")
+					} else {
+						assert.ErrorContains(t, err, "container 'cccccccccccc'")
+					}
+					wantState := "stopped"
+					if state == container.StateRunning {
+						wantState = state
+					}
+					assert.ErrorContains(t, err, wantState)
+				} else {
+					require.NoError(t, err)
+				}
+			})
+		}
+	}
+}
+
+func TestCheckImageRemovalConflicts_PropagatesLookupErrors(t *testing.T) {
+	imageID := "sha256:" + strings.Repeat("a", 64)
+	t.Run("image lookup fails", func(t *testing.T) {
+		cli := NewMockAPIClient(t)
+		lookupErr := errdefs.ErrNotFound.WithMessage("no such image")
+		cli.EXPECT().ImageInspect(mock.Anything, "myapp:old").Return(image.InspectResponse{}, lookupErr).Once()
+
+		service := NewService(cli, nil)
+		require.ErrorIs(t, service.checkImageRemovalConflicts(context.Background(), "myapp:old"), lookupErr)
+	})
+
+	t.Run("container lookup fails", func(t *testing.T) {
+		cli := NewMockAPIClient(t)
+		lookupErr := errors.New("Docker unavailable")
+		cli.EXPECT().ImageInspect(mock.Anything, "myapp:old").Return(image.InspectResponse{ID: imageID}, nil).Once()
+		cli.EXPECT().ContainerList(mock.Anything, mock.Anything).Return(nil, lookupErr).Once()
+
+		service := NewService(cli, nil)
+		err := service.checkImageRemovalConflicts(context.Background(), "myapp:old")
+
+		require.ErrorIs(t, err, lookupErr)
+		assert.ErrorContains(t, err, "list containers using image")
+	})
+}
+
+func TestServiceRemoveImage_RejectsUsedNameBeforeDeletion(t *testing.T) {
+	imageID := "sha256:" + strings.Repeat("a", 64)
+	cli := NewMockAPIClient(t)
+	cli.EXPECT().ImageInspect(mock.Anything, "myapp:current").Return(image.InspectResponse{ID: imageID}, nil).Once()
+	cli.EXPECT().ContainerList(mock.Anything, mock.Anything).Return([]container.Summary{{
+		ID: "container-id", ImageID: imageID, Image: "myapp:current", State: container.StateRunning,
+	}}, nil).Once()
+
+	service := NewService(cli, nil)
+	// ImageRemove has no expectation: any deletion call would fail this test.
+	results, err := service.RemoveImage(context.Background(), "myapp:current", image.RemoveOptions{Force: true})
+
+	require.True(t, errdefs.IsConflict(err), "%v", err)
+	assert.Nil(t, results)
+}
+
+func TestServiceRemoveImage_DelegatesToDocker(t *testing.T) {
+	imageID := "sha256:" + strings.Repeat("a", 64)
+	tests := []struct {
+		name    string
+		opts    image.RemoveOptions
+		results []image.DeleteResponse
+		err     error
+	}{
+		{
+			name:    "options and results pass through",
+			opts:    image.RemoveOptions{Force: true, PruneChildren: true, Platforms: []ocispec.Platform{{OS: "linux", Architecture: "amd64"}}},
+			results: []image.DeleteResponse{{Deleted: imageID}},
+		},
+		{
+			name: "Docker rejects final reference removal",
+			opts: image.RemoveOptions{PruneChildren: true},
+			err:  errdefs.ErrConflict.WithMessage("container is using its referenced image"),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cli := NewMockAPIClient(t)
+			cli.EXPECT().ImageInspect(mock.Anything, "myapp:old").Return(image.InspectResponse{ID: imageID}, nil).Once()
+			cli.EXPECT().ContainerList(mock.Anything, mock.Anything).Return([]container.Summary{{
+				ID: "container-id", ImageID: imageID, Image: "myapp@" + imageID, State: container.StateRunning,
+			}}, nil).Once()
+			cli.EXPECT().ImageRemove(mock.Anything, "myapp:old", tt.opts).Return(tt.results, tt.err).Once()
+
+			service := NewService(cli, nil)
+			results, err := service.RemoveImage(context.Background(), "myapp:old", tt.opts)
+			if tt.err != nil {
+				require.ErrorIs(t, err, tt.err)
+			} else {
+				require.NoError(t, err)
+			}
+			assert.Equal(t, tt.results, results)
+		})
+	}
+}

internal/machine/docker/server.go

@@ -56,7 +56,7 @@ var fullDockerIDRegex = regexp.MustCompile(`^[a-f0-9]{64}$`)
 // Server implements the gRPC Docker service that proxies requests to the Docker daemon.
 type Server struct {
 	pb.UnimplementedDockerServer
-	client  *client.Client
+	client  client.APIClient
 	service *Service
 	db      *sqlx.DB
 	// internalDNSIP is a function that returns the IP address of the internal DNS server. It may return an empty
@@ -349,6 +349,41 @@ func (s *Server) InspectImage(ctx context.Context, req *pb.InspectImageRequest)
 	}, nil
 }
 
+// RemoveImage removes an image while protecting names used by containers, even when force is requested.
+func (s *Server) RemoveImage(ctx context.Context, req *pb.RemoveImageRequest) (*pb.RemoveImageResponse, error) {
+	opts := image.RemoveOptions{Force: req.Force, PruneChildren: req.PruneChildren}
+	for _, platform := range req.Platforms {
+		opts.Platforms = append(opts.Platforms, ocispec.Platform{
+			Architecture: platform.Architecture,
+			OS:           platform.Os,
+			OSVersion:    platform.OsVersion,
+			OSFeatures:   platform.OsFeatures,
+			Variant:      platform.Variant,
+		})
+	}
+
+	removals, err := s.service.RemoveImage(ctx, req.Id, opts)
+	if err != nil {
+		switch {
+		case errdefs.IsNotFound(err):
+			return nil, status.Error(codes.NotFound, err.Error())
+		case errdefs.IsConflict(err):
+			return nil, status.Error(codes.FailedPrecondition, err.Error())
+		case errdefs.IsInvalidArgument(err):
+			return nil, status.Error(codes.InvalidArgument, err.Error())
+		default:
+			return nil, status.Error(codes.Internal, err.Error())
+		}
+	}
+
+	result := &pb.MachineImageRemoval{}
+	for _, removal := range removals {
+		result.Results = append(result.Results, &pb.ImageRemoval{Deleted: removal.Deleted, Untagged: removal.Untagged})
+	}
+
+	return &pb.RemoveImageResponse{Messages: []*pb.MachineImageRemoval{result}}, nil
+}
+
 // InspectRemoteImage returns the image metadata for an image in a remote registry using the machine's Docker auth
 // credentials if necessary.
 func (s *Server) InspectRemoteImage(

internal/machine/docker/service.go

@@ -31,13 +31,13 @@ import (
 // from the machine database.
 type Service struct {
 	// Client is a Docker client for managing Docker resources.
-	Client *client.Client
+	Client client.APIClient
 	// db is a connection to the machine database.
 	db *sqlx.DB
 }
 
 // NewService creates a new Docker service instance.
-func NewService(client *client.Client, db *sqlx.DB) *Service {
+func NewService(client client.APIClient, db *sqlx.DB) *Service {
 	return &Service{
 		Client: client,
 		db:     db,

mise.lock

@@ -1,40 +1,58 @@
 # @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html
 
+lockfile_version = 3
+
 [[tools."aqua:vektra/mockery"]]
-version = "3.5.3"
+version = "3.8.1"
 backend = "aqua:vektra/mockery"
+specifiers = ["3.8.1"]
 
 [tools."aqua:vektra/mockery"."platforms.linux-arm64"]
-checksum = "sha256:ec02ca72b7ad1ff5a1de5503a27d3b1b3f230d722eb35c5b92e43e295a8e1290"
-url = "https://github.com/vektra/mockery/releases/download/v3.5.3/mockery_3.5.3_Linux_arm64.tar.gz"
+checksum = "sha256:d1f481f3a6e9868dd3ad65da265238ee109ab3a5dd7508958d5811953696f452"
+checksum_source = "mise-versions"
+url = "https://github.com/vektra/mockery/releases/download/v3.8.1/mockery_3.8.1_Linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/vektra/mockery/releases/assets/632915757"
 
 [tools."aqua:vektra/mockery"."platforms.linux-arm64-musl"]
-checksum = "sha256:ec02ca72b7ad1ff5a1de5503a27d3b1b3f230d722eb35c5b92e43e295a8e1290"
-url = "https://github.com/vektra/mockery/releases/download/v3.5.3/mockery_3.5.3_Linux_arm64.tar.gz"
+checksum = "sha256:d1f481f3a6e9868dd3ad65da265238ee109ab3a5dd7508958d5811953696f452"
+checksum_source = "mise-versions"
+url = "https://github.com/vektra/mockery/releases/download/v3.8.1/mockery_3.8.1_Linux_arm64.tar.gz"
+url_api = "https://api.github.com/repos/vektra/mockery/releases/assets/632915757"
 
 [tools."aqua:vektra/mockery"."platforms.linux-x64"]
-checksum = "sha256:ebce416b0175338525246c376885a1579ca6cd4d4015140ba0c70e6b5339a39c"
-url = "https://github.com/vektra/mockery/releases/download/v3.5.3/mockery_3.5.3_Linux_x86_64.tar.gz"
+checksum = "sha256:953c7d38b58dd6398b1c595f27caf8bbf27e9b733b49c404d2e124e86d2ae72a"
+checksum_source = "mise-versions"
+url = "https://github.com/vektra/mockery/releases/download/v3.8.1/mockery_3.8.1_Linux_x86_64.tar.gz"
+url_api = "https://api.github.com/repos/vektra/mockery/releases/assets/632915756"
 
 [tools."aqua:vektra/mockery"."platforms.linux-x64-musl"]
-checksum = "sha256:ebce416b0175338525246c376885a1579ca6cd4d4015140ba0c70e6b5339a39c"
-url = "https://github.com/vektra/mockery/releases/download/v3.5.3/mockery_3.5.3_Linux_x86_64.tar.gz"
+checksum = "sha256:953c7d38b58dd6398b1c595f27caf8bbf27e9b733b49c404d2e124e86d2ae72a"
+checksum_source = "mise-versions"
+url = "https://github.com/vektra/mockery/releases/download/v3.8.1/mockery_3.8.1_Linux_x86_64.tar.gz"
+url_api = "https://api.github.com/repos/vektra/mockery/releases/assets/632915756"
 
 [tools."aqua:vektra/mockery"."platforms.macos-arm64"]
-checksum = "sha256:a3a94b14c7414e148f2252199ffc4a0108d311358f3d336cbe05bb73cb203704"
-url = "https://github.com/vektra/mockery/releases/download/v3.5.3/mockery_3.5.3_Darwin_arm64.tar.gz"
+checksum = "sha256:303a794484243906b37da0c37056f974bf94278c2e10d7b1372e6bd53a2d5034"
+checksum_source = "mise-versions"
+url = "https://github.com/vektra/mockery/releases/download/v3.8.1/mockery_3.8.1_Darwin_arm64.tar.gz"
+url_api = "https://api.github.com/repos/vektra/mockery/releases/assets/632915806"
 
 [tools."aqua:vektra/mockery"."platforms.macos-x64"]
-checksum = "sha256:8bd2b3e4722e476400395920fb5bbd68be4ea22ec12cddf1e424c40610fda863"
-url = "https://github.com/vektra/mockery/releases/download/v3.5.3/mockery_3.5.3_Darwin_x86_64.tar.gz"
+checksum = "sha256:6882331344e946268b304dce042b01371a0213a896536413be8abe49d532ca6f"
+checksum_source = "mise-versions"
+url = "https://github.com/vektra/mockery/releases/download/v3.8.1/mockery_3.8.1_Darwin_x86_64.tar.gz"
+url_api = "https://api.github.com/repos/vektra/mockery/releases/assets/632915746"
 
 [tools."aqua:vektra/mockery"."platforms.windows-x64"]
-checksum = "sha256:3b4264066db615a56a8b59abda992f6db82b8cd7666937ed9dd8f4a4bfc424a0"
-url = "https://github.com/vektra/mockery/releases/download/v3.5.3/mockery_3.5.3_Windows_x86_64.tar.gz"
+checksum = "sha256:7a7458756e9d7bce5f9936b7a63394000f3affa751b9740e65350c4bdcb627dc"
+checksum_source = "mise-versions"
+url = "https://github.com/vektra/mockery/releases/download/v3.8.1/mockery_3.8.1_Windows_x86_64.tar.gz"
+url_api = "https://api.github.com/repos/vektra/mockery/releases/assets/632915759"
 
 [[tools.go]]
 version = "1.26.1"
 backend = "core:go"
+specifiers = ["1.26.1"]
 
 [tools.go."platforms.linux-arm64"]
 checksum = "sha256:a290581cfe4fe28ddd737dde3095f3dbeb7f2e4065cab4eae44dfc53b760c2f7"
@@ -67,95 +85,118 @@ url = "https://dl.google.com/go/go1.26.1.windows-amd64.zip"
 [[tools.golangci-lint]]
 version = "2.11.2"
 backend = "aqua:golangci/golangci-lint"
+specifiers = ["2.11.2"]
 
 [tools.golangci-lint."platforms.linux-arm64"]
 checksum = "sha256:c3c83c7ed003e881991af21361c487151abd37969927ed9062cd0b48f3cd1d8d"
 url = "https://github.com/golangci/golangci-lint/releases/download/v2.11.2/golangci-lint-2.11.2-linux-arm64.tar.gz"
+url_api = "https://api.github.com/repos/golangci/golangci-lint/releases/assets/369099658"
+provenance = "github-attestations"
 
 [tools.golangci-lint."platforms.linux-arm64-musl"]
 checksum = "sha256:c3c83c7ed003e881991af21361c487151abd37969927ed9062cd0b48f3cd1d8d"
 url = "https://github.com/golangci/golangci-lint/releases/download/v2.11.2/golangci-lint-2.11.2-linux-arm64.tar.gz"
+url_api = "https://api.github.com/repos/golangci/golangci-lint/releases/assets/369099658"
+provenance = "github-attestations"
 
 [tools.golangci-lint."platforms.linux-x64"]
 checksum = "sha256:852741ea769f4543ab4b6cf86b313cb7173f2e8d2d39f00eb0cd5ef5d4d5eda9"
 url = "https://github.com/golangci/golangci-lint/releases/download/v2.11.2/golangci-lint-2.11.2-linux-amd64.tar.gz"
+url_api = "https://api.github.com/repos/golangci/golangci-lint/releases/assets/369099674"
 provenance = "github-attestations"
 
 [tools.golangci-lint."platforms.linux-x64-musl"]
 checksum = "sha256:852741ea769f4543ab4b6cf86b313cb7173f2e8d2d39f00eb0cd5ef5d4d5eda9"
 url = "https://github.com/golangci/golangci-lint/releases/download/v2.11.2/golangci-lint-2.11.2-linux-amd64.tar.gz"
+url_api = "https://api.github.com/repos/golangci/golangci-lint/releases/assets/369099674"
+provenance = "github-attestations"
 
 [tools.golangci-lint."platforms.macos-arm64"]
 checksum = "sha256:11e9549b955bae4bfb71aa3b5c2762e446e2d3f975fe963d6d767b8f745d9344"
 url = "https://github.com/golangci/golangci-lint/releases/download/v2.11.2/golangci-lint-2.11.2-darwin-arm64.tar.gz"
+url_api = "https://api.github.com/repos/golangci/golangci-lint/releases/assets/369099671"
 provenance = "github-attestations"
 
 [tools.golangci-lint."platforms.macos-x64"]
 checksum = "sha256:1dbbbe745eadba9cf012d49bd0b8c9290cbcb50dbf2cf9611f75a715b46ae3af"
 url = "https://github.com/golangci/golangci-lint/releases/download/v2.11.2/golangci-lint-2.11.2-darwin-amd64.tar.gz"
+url_api = "https://api.github.com/repos/golangci/golangci-lint/releases/assets/369099653"
+provenance = "github-attestations"
 
 [tools.golangci-lint."platforms.windows-x64"]
 checksum = "sha256:60e50178253d276d1c808ef00845eddcabca63b7d69d86a6dbaa41e88bc843f3"
 url = "https://github.com/golangci/golangci-lint/releases/download/v2.11.2/golangci-lint-2.11.2-windows-amd64.zip"
+url_api = "https://api.github.com/repos/golangci/golangci-lint/releases/assets/369099651"
+provenance = "github-attestations"
 
 [[tools.goreleaser]]
 version = "2.15.2"
 backend = "aqua:goreleaser/goreleaser"
+specifiers = ["2.15.2"]
 
 [tools.goreleaser."platforms.linux-arm64"]
 checksum = "sha256:5db66761a98f6693161e49e1a95d28d2673a892ba60cb4a5e16736cafd41c4c9"
 url = "https://github.com/goreleaser/goreleaser/releases/download/v2.15.2/goreleaser_Linux_arm64.tar.gz"
-provenance = "cosign"
+url_api = "https://api.github.com/repos/goreleaser/goreleaser/releases/assets/385702105"
+provenance = "github-attestations"
 
 [tools.goreleaser."platforms.linux-arm64-musl"]
 checksum = "sha256:5db66761a98f6693161e49e1a95d28d2673a892ba60cb4a5e16736cafd41c4c9"
 url = "https://github.com/goreleaser/goreleaser/releases/download/v2.15.2/goreleaser_Linux_arm64.tar.gz"
-provenance = "cosign"
+url_api = "https://api.github.com/repos/goreleaser/goreleaser/releases/assets/385702105"
+provenance = "github-attestations"
 
 [tools.goreleaser."platforms.linux-x64"]
 checksum = "sha256:0ebdbf0353aba566b969dde746cc4e4806f96c27aa2f3971b229a9df7611fedc"
 url = "https://github.com/goreleaser/goreleaser/releases/download/v2.15.2/goreleaser_Linux_x86_64.tar.gz"
+url_api = "https://api.github.com/repos/goreleaser/goreleaser/releases/assets/385702106"
 provenance = "github-attestations"
 
 [tools.goreleaser."platforms.linux-x64-musl"]
 checksum = "sha256:0ebdbf0353aba566b969dde746cc4e4806f96c27aa2f3971b229a9df7611fedc"
 url = "https://github.com/goreleaser/goreleaser/releases/download/v2.15.2/goreleaser_Linux_x86_64.tar.gz"
-provenance = "cosign"
+url_api = "https://api.github.com/repos/goreleaser/goreleaser/releases/assets/385702106"
+provenance = "github-attestations"
 
 [tools.goreleaser."platforms.macos-arm64"]
 checksum = "sha256:0e6bd67688ac949780bf1166813a91f89856898ef4c40d7d46c2c74ebaa4b9ee"
 url = "https://github.com/goreleaser/goreleaser/releases/download/v2.15.2/goreleaser_Darwin_all.tar.gz"
+url_api = "https://api.github.com/repos/goreleaser/goreleaser/releases/assets/385702148"
 provenance = "github-attestations"
 
 [tools.goreleaser."platforms.macos-x64"]
 checksum = "sha256:0e6bd67688ac949780bf1166813a91f89856898ef4c40d7d46c2c74ebaa4b9ee"
 url = "https://github.com/goreleaser/goreleaser/releases/download/v2.15.2/goreleaser_Darwin_all.tar.gz"
-provenance = "cosign"
+url_api = "https://api.github.com/repos/goreleaser/goreleaser/releases/assets/385702148"
+provenance = "github-attestations"
 
 [tools.goreleaser."platforms.windows-x64"]
 checksum = "sha256:7459832946dbe122c144f8d7f87484d8572ca005b779310aa6bb03346e8de17a"
 url = "https://github.com/goreleaser/goreleaser/releases/download/v2.15.2/goreleaser_Windows_x86_64.zip"
-provenance = "cosign"
+url_api = "https://api.github.com/repos/goreleaser/goreleaser/releases/assets/385702135"
+provenance = "github-attestations"
 
 [[tools.node]]
 version = "22.20.0"
 backend = "core:node"
+specifiers = ["22.20.0"]
 
 [tools.node."platforms.linux-arm64"]
 checksum = "sha256:4181609e03dcb9880e7e5bf956061ecc0503c77a480c6631d868cb1f65a2c7dd"
 url = "https://nodejs.org/dist/v22.20.0/node-v22.20.0-linux-arm64.tar.gz"
 
 [tools.node."platforms.linux-arm64-musl"]
-checksum = "sha256:4181609e03dcb9880e7e5bf956061ecc0503c77a480c6631d868cb1f65a2c7dd"
-url = "https://nodejs.org/dist/v22.20.0/node-v22.20.0-linux-arm64.tar.gz"
+checksum = "sha256:79a087c1e23fc97d173ad6676df5b1a4e1a02daf1acca05ee25662747c5d492c"
+url = "https://nodejs.org/dist/v22.20.0/node-v22.20.0.tar.gz"
+install = "source"
 
 [tools.node."platforms.linux-x64"]
 checksum = "sha256:eeaccb0378b79406f2208e8b37a62479c70595e20be6b659125eb77dd1ab2a29"
 url = "https://nodejs.org/dist/v22.20.0/node-v22.20.0-linux-x64.tar.gz"
 
 [tools.node."platforms.linux-x64-musl"]
-checksum = "sha256:eeaccb0378b79406f2208e8b37a62479c70595e20be6b659125eb77dd1ab2a29"
-url = "https://nodejs.org/dist/v22.20.0/node-v22.20.0-linux-x64.tar.gz"
+checksum = "sha256:461aafed5eb607357479c6de5df978515d74daf7e0169e972e61c8390c035f1a"
+url = "https://unofficial-builds.nodejs.org/download/release/v22.20.0/node-v22.20.0-linux-x64-musl.tar.gz"
 
 [tools.node."platforms.macos-arm64"]
 checksum = "sha256:cc04a76a09f79290194c0646f48fec40354d88969bec467789a5d55dd097f949"
@@ -172,41 +213,119 @@ url = "https://nodejs.org/dist/v22.20.0/node-v22.20.0-win-x64.zip"
 [[tools.protoc]]
 version = "27.3"
 backend = "aqua:protocolbuffers/protobuf/protoc"
+specifiers = ["27.3"]
+
+[tools.protoc."platforms.linux-arm64"]
+checksum = "sha256:bdad36f3ad7472281d90568c4956ea2e203c216e0de005c6bd486f1920f2751c"
+url = "https://github.com/protocolbuffers/protobuf/releases/download/v27.3/protoc-27.3-linux-aarch_64.zip"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf/releases/assets/183006374"
+
+[tools.protoc."platforms.linux-arm64-musl"]
+checksum = "sha256:bdad36f3ad7472281d90568c4956ea2e203c216e0de005c6bd486f1920f2751c"
+url = "https://github.com/protocolbuffers/protobuf/releases/download/v27.3/protoc-27.3-linux-aarch_64.zip"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf/releases/assets/183006374"
 
 [tools.protoc."platforms.linux-x64"]
-checksum = "blake3:8c2938accf7061164ea3968529a47ced1db4824ca553857f6903c68ae4347739"
+checksum = "sha256:6dab2adab83f915126cab53540d48957c40e9e9023969c3e84d44bfb936c7741"
 url = "https://github.com/protocolbuffers/protobuf/releases/download/v27.3/protoc-27.3-linux-x86_64.zip"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf/releases/assets/183006380"
+
+[tools.protoc."platforms.linux-x64-musl"]
+checksum = "sha256:6dab2adab83f915126cab53540d48957c40e9e9023969c3e84d44bfb936c7741"
+url = "https://github.com/protocolbuffers/protobuf/releases/download/v27.3/protoc-27.3-linux-x86_64.zip"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf/releases/assets/183006380"
+
+[tools.protoc."platforms.macos-arm64"]
+checksum = "sha256:b22116bd97cdbd7ea25346abe635a9df268515fe5ef5afa93cd9a68fc2513f84"
+url = "https://github.com/protocolbuffers/protobuf/releases/download/v27.3/protoc-27.3-osx-aarch_64.zip"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf/releases/assets/183006383"
+
+[tools.protoc."platforms.macos-x64"]
+checksum = "sha256:ce282648fed0e7fbd6237d606dc9ec168dd2c1863889b04efa0b19c47da65d1b"
+url = "https://github.com/protocolbuffers/protobuf/releases/download/v27.3/protoc-27.3-osx-x86_64.zip"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf/releases/assets/183006381"
+
+[tools.protoc."platforms.windows-x64"]
+checksum = "sha256:bdccd341a0c25ff4f65d8530f170c78ce5681e42920aa5d892f27ac06cc3bba0"
+url = "https://github.com/protocolbuffers/protobuf/releases/download/v27.3/protoc-27.3-win64.zip"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf/releases/assets/183006385"
 
 [[tools.protoc-gen-go]]
 version = "1.34.2"
 backend = "aqua:protocolbuffers/protobuf-go/protoc-gen-go"
+specifiers = ["1.34.2"]
 
 [tools.protoc-gen-go."platforms.linux-arm64"]
+checksum = "sha256:63d400167e75ab9f6690688f6fdc6a9455aa20bc1faa71e32149dbd322f7f198"
 url = "https://github.com/protocolbuffers/protobuf-go/releases/download/v1.34.2/protoc-gen-go.v1.34.2.linux.arm64.tar.gz"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf-go/releases/assets/173109690"
 
 [tools.protoc-gen-go."platforms.linux-arm64-musl"]
+checksum = "sha256:63d400167e75ab9f6690688f6fdc6a9455aa20bc1faa71e32149dbd322f7f198"
 url = "https://github.com/protocolbuffers/protobuf-go/releases/download/v1.34.2/protoc-gen-go.v1.34.2.linux.arm64.tar.gz"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf-go/releases/assets/173109690"
 
 [tools.protoc-gen-go."platforms.linux-x64"]
-checksum = "blake3:f765e393e0f0b25070c13848d88f5e6303e66090132afa1b753e981507a4174e"
+checksum = "sha256:b87bc134dee55576a842141bf0ed27761c635d746780fce5dee038c6dd16554f"
 url = "https://github.com/protocolbuffers/protobuf-go/releases/download/v1.34.2/protoc-gen-go.v1.34.2.linux.amd64.tar.gz"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf-go/releases/assets/173109692"
 
 [tools.protoc-gen-go."platforms.linux-x64-musl"]
+checksum = "sha256:b87bc134dee55576a842141bf0ed27761c635d746780fce5dee038c6dd16554f"
 url = "https://github.com/protocolbuffers/protobuf-go/releases/download/v1.34.2/protoc-gen-go.v1.34.2.linux.amd64.tar.gz"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf-go/releases/assets/173109692"
 
 [tools.protoc-gen-go."platforms.macos-arm64"]
+checksum = "sha256:17aca7f948dbb624049030cf841e35895cf34183ba006e721247fdeb95ff2780"
 url = "https://github.com/protocolbuffers/protobuf-go/releases/download/v1.34.2/protoc-gen-go.v1.34.2.darwin.arm64.tar.gz"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf-go/releases/assets/173109697"
 
 [tools.protoc-gen-go."platforms.macos-x64"]
+checksum = "sha256:9b48d8f90add02e8e94e14962fed74e7ce2b2d6bda4dd42f1f4fbccf0f766f1a"
 url = "https://github.com/protocolbuffers/protobuf-go/releases/download/v1.34.2/protoc-gen-go.v1.34.2.darwin.amd64.tar.gz"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf-go/releases/assets/173109698"
 
 [tools.protoc-gen-go."platforms.windows-x64"]
+checksum = "sha256:abafd39612177dd4e9a65207cadd5374a9352d8611e8e040f8462fcfa3010daf"
 url = "https://github.com/protocolbuffers/protobuf-go/releases/download/v1.34.2/protoc-gen-go.v1.34.2.windows.amd64.zip"
+url_api = "https://api.github.com/repos/protocolbuffers/protobuf-go/releases/assets/173109685"
 
 [[tools.protoc-gen-go-grpc]]
 version = "1.5.1"
 backend = "aqua:grpc/grpc-go/protoc-gen-go-grpc"
+specifiers = ["1.5.1"]
+
+[tools.protoc-gen-go-grpc."platforms.linux-arm64"]
+checksum = "sha256:370a7cfa5786e61e6fdc5aa8f689e35c2d27d036a49caac7aa25f962c89a01e8"
+url = "https://github.com/grpc/grpc-go/releases/download/cmd/protoc-gen-go-grpc/v1.5.1/protoc-gen-go-grpc.v1.5.1.linux.arm64.tar.gz"
+url_api = "https://api.github.com/repos/grpc/grpc-go/releases/assets/182572238"
+
+[tools.protoc-gen-go-grpc."platforms.linux-arm64-musl"]
+checksum = "sha256:370a7cfa5786e61e6fdc5aa8f689e35c2d27d036a49caac7aa25f962c89a01e8"
+url = "https://github.com/grpc/grpc-go/releases/download/cmd/protoc-gen-go-grpc/v1.5.1/protoc-gen-go-grpc.v1.5.1.linux.arm64.tar.gz"
+url_api = "https://api.github.com/repos/grpc/grpc-go/releases/assets/182572238"
 
 [tools.protoc-gen-go-grpc."platforms.linux-x64"]
-checksum = "blake3:197739132f0408f017d0c83773ac1ace85c0572473fdd658ec6e4ccbf20e0552"
+checksum = "sha256:a6cac4ea731e54aea304ad44d704a69d1cdc82997084b33637e21a89dc9229d6"
 url = "https://github.com/grpc/grpc-go/releases/download/cmd/protoc-gen-go-grpc/v1.5.1/protoc-gen-go-grpc.v1.5.1.linux.amd64.tar.gz"
+url_api = "https://api.github.com/repos/grpc/grpc-go/releases/assets/182572229"
+
+[tools.protoc-gen-go-grpc."platforms.linux-x64-musl"]
+checksum = "sha256:a6cac4ea731e54aea304ad44d704a69d1cdc82997084b33637e21a89dc9229d6"
+url = "https://github.com/grpc/grpc-go/releases/download/cmd/protoc-gen-go-grpc/v1.5.1/protoc-gen-go-grpc.v1.5.1.linux.amd64.tar.gz"
+url_api = "https://api.github.com/repos/grpc/grpc-go/releases/assets/182572229"
+
+[tools.protoc-gen-go-grpc."platforms.macos-arm64"]
+checksum = "sha256:d6083feb51dcfe59f26793e99ef01ef5eac68b64294ec2546711f614ac5878f3"
+url = "https://github.com/grpc/grpc-go/releases/download/cmd/protoc-gen-go-grpc/v1.5.1/protoc-gen-go-grpc.v1.5.1.darwin.arm64.tar.gz"
+url_api = "https://api.github.com/repos/grpc/grpc-go/releases/assets/182572243"
+
+[tools.protoc-gen-go-grpc."platforms.macos-x64"]
+checksum = "sha256:c12c259d59c8b451f24b6abdad6d055fd0884c5268b7247fd7e5ec9d2432d1f1"
+url = "https://github.com/grpc/grpc-go/releases/download/cmd/protoc-gen-go-grpc/v1.5.1/protoc-gen-go-grpc.v1.5.1.darwin.amd64.tar.gz"
+url_api = "https://api.github.com/repos/grpc/grpc-go/releases/assets/182572208"
+
+[tools.protoc-gen-go-grpc."platforms.windows-x64"]
+checksum = "sha256:c2ad1460c9e34b5b37759826da61220be6ee0a8a11431723d205512a69319991"
+url = "https://github.com/grpc/grpc-go/releases/download/cmd/protoc-gen-go-grpc/v1.5.1/protoc-gen-go-grpc.v1.5.1.windows.amd64.tar.gz"
+url_api = "https://api.github.com/repos/grpc/grpc-go/releases/assets/182572216"

mise.toml

@@ -1,8 +1,9 @@
 [settings]
 experimental = true
+lockfile = true
 
 [tools]
-"aqua:vektra/mockery" = "3.5.3"
+"aqua:vektra/mockery" = "3.8.1"
 go = "1.26.1"
 golangci-lint = "2.11.2"
 goreleaser = "2.15.2"
@@ -36,9 +37,18 @@ GOOS=linux GOARCH=arm64 go build -ldflags "-X github.com/psviderski/uncloud/inte
 """
 outputs = ["uncloudd-linux-arm64"]
 
-[tasks."mise:lock"]
-description = "Update mise.lock with hashes for all platforms"
-run = "mise lock --platform linux-x64,macos-arm64"
+[tasks."docs:cli"]
+description = "Regenerate the CLI reference docs"
+run = "go run ./cmd/uc docs"
+
+[tasks."docs:dev"]
+description = "Run the documentation website locally"
+dir = "website"
+run = "npm start --"
+
+[tasks.mocks]
+description = "Regenerate Go test mocks"
+run = "mockery"
 
 [tasks.proto]
 description = "Regenerate gRPC API code from .proto files"
@@ -49,10 +59,12 @@ protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=p
 
 [tasks.uc]
 description = "Run the Uncloud CLI"
+raw_args = true
 run = "go run ./cmd/uc"
 
 [tasks.ucind]
 description = "Run ucind CLI for managing local Docker-based clusters"
+raw_args = true
 run = "go run ./cmd/ucind"
 
 [tasks."ucind:image"]

pkg/api/client.go

@@ -42,6 +42,8 @@ type DNSClient interface {
 type ImageClient interface {
 	InspectImage(ctx context.Context, id string) ([]MachineImage, error)
 	InspectRemoteImage(ctx context.Context, id string) ([]MachineRemoteImage, error)
+	ListImages(ctx context.Context, filter ImageFilter) ([]MachineImages, error)
+	RemoveImage(ctx context.Context, image string, opts RemoveImageOptions) ([]MachineImageRemoval, error)
 }
 
 type LogsClient interface {

pkg/api/image.go

@@ -1,8 +1,6 @@
 package api
 
 import (
-	"errors"
-
 	"github.com/distribution/reference"
 	"github.com/docker/docker/api/types/image"
 	v1 "github.com/opencontainers/image-spec/specs-go/v1"
@@ -24,14 +22,6 @@ type MachineImages struct {
 	ContainerdStore bool
 }
 
-// Error returns a non-nil error if listing images on this machine failed.
-func (mi MachineImages) Error() error {
-	if mi.Metadata != nil && mi.Metadata.Error != "" {
-		return errors.New(mi.Metadata.Error)
-	}
-	return nil
-}
-
 // ImageFilter defines criteria to filter images in ListImages.
 type ImageFilter struct {
 	// Machines filters images to those present on the specified machines (names or IDs).
@@ -42,6 +32,18 @@ type ImageFilter struct {
 	Name string
 }
 
+// RemoveImageOptions defines options for removing an image from cluster machines.
+type RemoveImageOptions struct {
+	// Machines selects machines to remove the image from (names or IDs). If empty, all cluster machines are selected.
+	Machines []string
+}
+
+// MachineImageRemoval contains the outcome of removing an image on one machine.
+type MachineImageRemoval struct {
+	Metadata *pb.Metadata
+	Results  []image.DeleteResponse
+}
+
 // MachineRemoteImage represents an image in a remote registry fetched by a particular machine.
 type MachineRemoteImage struct {
 	Metadata *pb.Metadata

pkg/client/client.go

@@ -86,6 +86,7 @@ func (cli *Client) progressOut() *streams.Out {
 // ProxyMachinesContext returns a new context that proxies gRPC requests to the specified machines.
 // If namesOrIDs is nil or empty, all machines are included.
 // This triggers One2Many proxying, which always injects metadata into the response.
+// TODO: validate namesOrIDs can't contain "*" as this is reserved as internal value and may break the caller logic.
 func ProxyMachinesContext(ctx context.Context, namesOrIDs []string) context.Context {
 	md := outgoingMetadataWithoutProxyTargets(ctx)
 	if len(namesOrIDs) == 0 {

pkg/client/compose/deploy.go

@@ -13,8 +13,8 @@ import (
 	"github.com/docker/docker/api/types/volume"
 	"github.com/psviderski/uncloud/pkg/api"
 	"github.com/psviderski/uncloud/pkg/client/deploy"
-	"github.com/psviderski/uncloud/pkg/client/deploy/operation"
 	"github.com/psviderski/uncloud/pkg/client/deploy/scheduler"
+	"github.com/psviderski/uncloud/pkg/client/operation"
 )
 
 type Client interface {

pkg/client/compose/plan.go

@@ -10,7 +10,7 @@ import (
 	"github.com/psviderski/uncloud/internal/cli/tui"
 	"github.com/psviderski/uncloud/pkg/api"
 	"github.com/psviderski/uncloud/pkg/client/deploy"
-	"github.com/psviderski/uncloud/pkg/client/deploy/operation"
+	"github.com/psviderski/uncloud/pkg/client/operation"
 )
 
 // Plan holds the compose-level deployment plan with volume and service operations.

pkg/client/deploy/deploy.go

@@ -12,8 +12,8 @@ import (
 	"github.com/distribution/reference"
 	"github.com/psviderski/uncloud/internal/cli/tui"
 	"github.com/psviderski/uncloud/pkg/api"
-	"github.com/psviderski/uncloud/pkg/client/deploy/operation"
 	"github.com/psviderski/uncloud/pkg/client/deploy/scheduler"
+	"github.com/psviderski/uncloud/pkg/client/operation"
 )
 
 type Client interface {

pkg/client/deploy/strategy.go

@@ -8,8 +8,8 @@ import (
 	"github.com/psviderski/uncloud/api/pb"
 	"github.com/psviderski/uncloud/internal/secret"
 	"github.com/psviderski/uncloud/pkg/api"
-	"github.com/psviderski/uncloud/pkg/client/deploy/operation"
 	"github.com/psviderski/uncloud/pkg/client/deploy/scheduler"
+	"github.com/psviderski/uncloud/pkg/client/operation"
 )
 
 // Strategy defines how a service should be deployed or updated. Different implementations can provide various

pkg/client/deploy/strategy_test.go

@@ -8,8 +8,8 @@ import (
 	"github.com/google/go-cmp/cmp/cmpopts"
 	"github.com/psviderski/uncloud/api/pb"
 	"github.com/psviderski/uncloud/pkg/api"
-	"github.com/psviderski/uncloud/pkg/client/deploy/operation"
 	"github.com/psviderski/uncloud/pkg/client/deploy/scheduler"
+	"github.com/psviderski/uncloud/pkg/client/operation"
 	"github.com/stretchr/testify/assert"
 )
 

pkg/client/image.go

@@ -23,9 +23,11 @@ import (
 	"github.com/docker/docker/api/types/image"
 	dockerclient "github.com/docker/docker/client"
 	"github.com/docker/docker/pkg/jsonmessage"
+	"github.com/docker/docker/pkg/stringid"
 	"github.com/docker/go-connections/nat"
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"github.com/psviderski/uncloud/api/pb"
+	cliprogress "github.com/psviderski/uncloud/internal/cli/progress"
 	"github.com/psviderski/uncloud/internal/cli/tui"
 	"github.com/psviderski/uncloud/internal/docker"
 	"github.com/psviderski/uncloud/internal/machine/constants"
@@ -34,6 +36,8 @@ import (
 	"github.com/psviderski/uncloud/internal/secret"
 	"github.com/psviderski/uncloud/pkg/api"
 	netproxy "golang.org/x/net/proxy"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
 )
 
 // This is the container image used to run socat proxy containers.
@@ -61,7 +65,7 @@ func (cli *Client) ListImages(ctx context.Context, filter api.ImageFilter) ([]ap
 	// Broadcast the image list request to the specified machines or all machines if none specified.
 	listCtx := ProxyMachinesContext(ctx, filter.Machines)
 
-	opts := image.ListOptions{Manifests: true}
+	opts := image.ListOptions{All: true, Manifests: true}
 	if filter.Name != "" {
 		opts.Filters = filters.NewArgs(
 			filters.Arg("reference", filter.Name),
@@ -92,7 +96,7 @@ func (cli *Client) ListImages(ctx context.Context, filter api.ImageFilter) ([]ap
 			ContainerdStore: msg.ContainerdStore,
 		}
 
-		if msg.Metadata.Error == "" && len(msg.Images) > 0 {
+		if msg.Metadata.Err() == nil && len(msg.Images) > 0 {
 			if err = json.Unmarshal(msg.Images, &mi.Images); err != nil {
 				return nil, fmt.Errorf("unmarshal images: %w", err)
 			}
@@ -104,6 +108,81 @@ func (cli *Client) ListImages(ctx context.Context, filter api.ImageFilter) ([]ap
 	return machineImages, nil
 }
 
+// RemoveImage removes one exact image name or ID on the selected machines with protection of used references.
+// Results include the outcome of removing an image on each machine.
+//
+// An absent image on some machines is normal if removal succeeds on at least one machine. If every selected machine
+// reports NotFound, the returned error is api.ErrNotFound. Other machine failures are combined, with successful
+// results still returned.
+func (cli *Client) RemoveImage(
+	ctx context.Context, imageNameOrID string, opts api.RemoveImageOptions,
+) ([]api.MachineImageRemoval, error) {
+	if strings.TrimSpace(imageNameOrID) == "" {
+		return nil, errors.New("image name or ID is required")
+	}
+
+	resp, err := cli.Docker.GRPCClient.RemoveImage(ProxyMachinesContext(ctx, opts.Machines),
+		&pb.RemoveImageRequest{Id: imageNameOrID, PruneChildren: true})
+	if err != nil {
+		return nil, err
+	}
+
+	pw := progress.ContextWriter(ctx)
+	var results []api.MachineImageRemoval
+	var errs []error
+	notFoundCount := 0
+	for _, msg := range resp.Messages {
+		result := api.MachineImageRemoval{Metadata: msg.Metadata}
+		for _, removal := range msg.Results {
+			result.Results = append(result.Results, image.DeleteResponse{
+				Deleted:  removal.Deleted,
+				Untagged: removal.Untagged,
+			})
+		}
+		results = append(results, result)
+
+		eventID := cliprogress.ImageEventID(imageNameOrID, msg.Metadata.MachineName)
+		if err = result.Metadata.Err(); err != nil {
+			event := progress.NewEvent(eventID, progress.Done, "Not found")
+			if status.Code(err) == codes.NotFound {
+				notFoundCount++
+			} else {
+				errs = append(errs, fmt.Errorf("machine '%s': %w", msg.Metadata.MachineName, err))
+				event.Status = progress.Error
+				event.StatusText = status.Convert(err).Message()
+			}
+			pw.Event(event)
+			continue
+		}
+
+		// An unnamed image can return Deleted without Untagged. Use the requested name or ID as its row fallback.
+		deleted := false
+		for _, removal := range result.Results {
+			if removal.Untagged != "" {
+				eventID = cliprogress.ImageEventID(removal.Untagged, msg.Metadata.MachineName)
+				pw.Event(progress.NewEvent(eventID, progress.Done, "Untagged"))
+			}
+			if removal.Deleted != "" && !deleted {
+				// Docker reports the deletion of the selected image before any pruned parents or released layers.
+				// Only that first deletion updates the last untagged row marking the image as Removed.
+				deleted = true
+				pw.Event(progress.NewEvent(eventID, progress.Done,
+					fmt.Sprintf("Removed (%s)", stringid.TruncateID(removal.Deleted))))
+			}
+		}
+	}
+
+	if err = errors.Join(errs...); err != nil {
+		return results, err
+	}
+	if notFoundCount == len(results) {
+		return results, api.ErrNotFound
+	}
+
+	return results, nil
+}
+
+// TODO: move PushImageOptions to api package and include PushImage in ImageClient interface.
 type PushImageOptions struct {
 	// AllMachines pushes the image to all machines in the cluster. Takes precedence over Machines field.
 	AllMachines bool
@@ -215,7 +294,7 @@ func (cli *Client) pushImageToMachine(
 		Name:     "%invalid-name-to-only-check-store-type%",
 	})
 	if err == nil {
-		err = images[0].Error()
+		err = images[0].Metadata.Err()
 	}
 	if err != nil {
 		return fmt.Errorf("check Docker image store type on machine '%s': %w", machine.Name, err)

pkg/client/operation/operation.go

@@ -6,8 +6,8 @@ import (
 	"github.com/psviderski/uncloud/pkg/api"
 )
 
-// Operation represents a single atomic operation in a deployment process.
-// Operations can be composed to form complex deployment strategies.
+// Operation represents a single operation in the cluster that can be executed.
+// Operations can be composed to form complex workflows (plans).
 type Operation interface {
 	// Execute performs the operation using the provided client.
 	Execute(ctx context.Context, cli Client) error
@@ -16,7 +16,7 @@ type Operation interface {
 	String() string
 }
 
-// Client defines the interface required to execute deployment operations.
+// Client defines the interface required to execute cluster operations.
 type Client interface {
 	api.ContainerClient
 	api.VolumeClient

pkg/client/service.go

@@ -125,10 +125,10 @@ func (cli *Client) InspectService(ctx context.Context, nameOrID string) (api.Ser
 			continue
 		}
 
-		if mc.Metadata.Error != "" {
+		if err := mc.Metadata.Err(); err != nil {
 			// TODO: return failed machines in the response.
 			tui.PrintWarning(fmt.Sprintf("failed to list containers on machine '%s': %s",
-				mc.Metadata.MachineName, mc.Metadata.Error))
+				mc.Metadata.MachineName, err))
 			continue
 		}
 
@@ -333,10 +333,10 @@ func (cli *Client) ListServices(ctx context.Context) ([]api.Service, error) {
 	// Group containers by service ID using the broadcast results.
 	servicesByID := make(map[string]api.Service)
 	for _, mc := range machineContainers {
-		if mc.Metadata.Error != "" {
+		if err := mc.Metadata.Err(); err != nil {
 			// TODO: return failed machines in the response.
 			tui.PrintWarning(fmt.Sprintf("failed to list containers on machine '%s': %s",
-				mc.Metadata.MachineName, mc.Metadata.Error))
+				mc.Metadata.MachineName, err))
 			continue
 		}
 

pkg/client/volume.go

@@ -70,10 +70,10 @@ func (cli *Client) ListVolumes(ctx context.Context, filter *api.VolumeFilter) ([
 			continue
 		}
 
-		if mv.Metadata.Error != "" {
+		if err := mv.Metadata.Err(); err != nil {
 			// TODO: return failed machines in the response.
 			tui.PrintWarning(fmt.Sprintf("failed to list volumes on machine '%s': %s", mv.Metadata.MachineName,
-				mv.Metadata.Error))
+				err))
 			continue
 		}
 

test/e2e/service_test.go

@@ -14,6 +14,7 @@ import (
 	"time"
 
 	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/image"
 	"github.com/docker/docker/api/types/mount"
 	"github.com/docker/docker/api/types/volume"
 	"github.com/docker/go-units"
@@ -1265,10 +1266,10 @@ myapp.example.com {
 			"Containers should be on machines where the volume exists")
 	})
 
-	t.Run("list images for replicated service", func(t *testing.T) {
+	t.Run("image lifecycle for replicated service", func(t *testing.T) {
 		t.Parallel()
 
-		serviceName := "test-list-images-replicated"
+		serviceName := "test-image-lifecycle-replicated"
 		uniqueImage := "portainer/pause:3.9" // Unique image not used by other tests.
 		t.Cleanup(func() {
 			err := cli.RemoveService(ctx, serviceName)
@@ -1301,39 +1302,59 @@ myapp.example.com {
 		machinesWithContainers := serviceMachines(svc)
 		assert.Len(t, machinesWithContainers.ToSlice(), 2, "Containers should be on 2 different machines")
 
-		var machineWithoutContainer string
-		for _, m := range c.Machines {
-			if !machinesWithContainers.Contains(m.ID) {
-				machineWithoutContainer = m.ID
-				break
-			}
-		}
-		assert.NotEmpty(t, machineWithoutContainer, "Should have found a machine without container")
-
-		machineImages, err := cli.ListImages(ctx, api.ImageFilter{})
+		machineImages, err := cli.ListImages(ctx, api.ImageFilter{Name: uniqueImage})
 		require.NoError(t, err)
-		assert.Len(t, machineImages, 3, "Should get images from all 3 machines")
+		require.Len(t, machineImages, len(c.Machines))
 
 		for _, mi := range machineImages {
-			// Checking only DockerImages because the machines in ucind cluster don't use the containerd image store.
+			require.NoError(t, mi.Metadata.Err())
 			if !machinesWithContainers.Contains(mi.Metadata.MachineId) {
-				// This is the machine without service containers, it should not have the unique image.
-				for _, img := range mi.Images {
-					assert.NotContains(t, img.RepoTags, uniqueImage)
-				}
+				assert.Empty(t, mi.Images)
 				continue
 			}
 
-			// Check if the unique image is present on the machine where a service container is running.
-			hasImage := false
-			for _, img := range mi.Images {
-				if slices.Contains(img.RepoTags, uniqueImage) {
-					hasImage = true
-					break
-				}
+			require.Len(t, mi.Images, 1)
+			assert.Contains(t, mi.Images[0].RepoTags, uniqueImage)
+		}
+
+		// The used tag must remain on both machines while their service containers exist.
+		results, err := cli.RemoveImage(ctx, uniqueImage, api.RemoveImageOptions{Machines: spec.Placement.Machines})
+		require.Error(t, err)
+		assert.ErrorContains(t, err, "used by container")
+		require.Len(t, results, 2)
+		for _, result := range results {
+			assert.Equal(t, codes.FailedPrecondition, status.Code(result.Metadata.Err()))
+		}
+
+		require.NoError(t, cli.RemoveService(ctx, serviceName))
+
+		// Broadcast removal after deleting the containers. Absence on the third machine is not an overall error.
+		results, err = cli.RemoveImage(ctx, uniqueImage, api.RemoveImageOptions{})
+		require.NoError(t, err)
+		require.Len(t, results, len(c.Machines))
+		for _, result := range results {
+			if !machinesWithContainers.Contains(result.Metadata.MachineId) {
+				assert.Equal(t, codes.NotFound, status.Code(result.Metadata.Err()))
+				continue
 			}
-			assert.True(t, hasImage, "Machine %s with container should have image %s",
-				mi.Metadata.MachineId, uniqueImage)
+			require.NoError(t, result.Metadata.Err())
+			assert.Contains(t, result.Results, image.DeleteResponse{Untagged: uniqueImage})
+		}
+
+		results, err = cli.RemoveImage(ctx, uniqueImage, api.RemoveImageOptions{})
+		require.ErrorIs(t, err, api.ErrNotFound)
+		require.Len(t, results, len(c.Machines))
+		for _, result := range results {
+			assert.Equal(t, codes.NotFound, status.Code(result.Metadata.Err()))
+			assert.Empty(t, result.Results)
+		}
+
+		machineImages, err = cli.ListImages(ctx, api.ImageFilter{Name: uniqueImage})
+		require.NoError(t, err)
+		require.Len(t, machineImages, len(c.Machines))
+		for _, mi := range machineImages {
+			require.NoError(t, mi.Metadata.Err())
+			assert.Empty(t, mi.Images)
 		}
 	})
 

website/README.md

@@ -18,14 +18,22 @@ npm run dev
 
 `/docs` and `/blog` are built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-### Local Development
+### Local development
 
-```
-npm start
+To preview the documentation website, install its dependencies first:
+
+```shell
+npm ci
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without
-having to restart the server.
+Then start the local development server:
+
+```shell
+mise run docs:dev
+```
+
+It opens up a browser window at http://localhost:3000/. Most changes are reflected live without having to restart the
+server.
 
 ## Deployment
 

website/docs/9-cli-reference/uc_caddy_config.md

@@ -15,7 +15,6 @@ uc caddy config [flags]
 ```
   -h, --help             help for config
   -m, --machine string   Name or ID of the machine to get the configuration from. (default is connected machine)
-      --no-color         Disable syntax highlighting for the output.
 ```
 
 ## Options inherited from parent commands

website/docs/9-cli-reference/uc_image.md

@@ -22,4 +22,5 @@ Manage images on machines in the cluster.
 * [uc](uc.md)	 - A CLI tool for managing Uncloud resources such as machines, services, and volumes.
 * [uc image ls](uc_image_ls.md)	 - List images on machines in the cluster.
 * [uc image push](uc_image_push.md)	 - Upload a local Docker image to the cluster.
+* [uc image rm](uc_image_rm.md)	 - Remove images from machines in the cluster.
 

website/docs/9-cli-reference/uc_image_rm.md

@@ -0,0 +1,61 @@
+# uc image rm
+
+Remove images from machines in the cluster.
+
+## Synopsis
+
+Remove images from all or selected machines in the cluster.
+
+An image name without a tag selects all its tags. Specify a tag, such as myapp:latest, to remove
+only that tag.
+
+Wildcard patterns are supported for image names and tags and should be quoted to prevent your
+shell from expanding them. Removing by image ID attempts to remove each name for that image
+independently.
+
+Images used by running or stopped containers cannot be removed. Unused tags can be removed even
+when the same image is used under another tag. Failed removals do not prevent other removals.
+
+```
+uc image rm IMAGE [IMAGE...] [flags]
+```
+
+## Examples
+
+```
+  # Remove a tag from all machines after confirming the plan.
+  uc image rm myapp:old
+
+  # Remove all tags for an image name from all machines.
+  uc image rm myapp
+
+  # Remove matching tags from two machines without confirmation.
+  uc image rm 'myapp:1.*' 'otherapp:*' -m machine1,machine2 --yes
+
+  # Remove all names for an image by ID from all machines.
+  uc image rm ee8fed0e9618
+```
+
+## Options
+
+```
+  -h, --help              help for rm
+  -m, --machine strings   Machine names or IDs to remove images from. Can be specified multiple times or as a comma-separated list.
+                          If not specified, the matching images will be removed from all machines.
+  -y, --yes               Auto-confirm the removal plan. Should be explicitly set when running non-interactively,
+                          e.g., in CI/CD pipelines. [$UNCLOUD_AUTO_CONFIRM]
+```
+
+## Options inherited from parent commands
+
+```
+      --connect string          Connect to a remote cluster machine without using the Uncloud configuration file. [$UNCLOUD_CONNECT]
+                                Format: [ssh://]user@host[:port], ssh+go://user@host[:port], tcp://host:port, or unix:///path/to/uncloud.sock
+  -c, --context string          Name of the cluster context to use (default is the current context). [$UNCLOUD_CONTEXT]
+      --uncloud-config string   Path to the Uncloud configuration file. [$UNCLOUD_CONFIG] (default "~/.config/uncloud/config.yaml")
+```
+
+## See also
+
+* [uc image](uc_image.md)	 - Manage images on machines in the cluster.
+