guestagent,hostagent,limactl: add memory ballooning and auto-pause

Add adaptive memory ballooning and auto-pause for macOS VZ driver VMs.
The balloon controller dynamically adjusts guest memory between a
configured minimum and the VM's maximum based on guest PSI pressure
metrics, host memory pressure (Mach vm_stat), and workload signals.

Key components:

Guest agent memory metrics: Collect /proc/meminfo, /proc/pressure/
memory, /proc/vmstat, and Docker container stats via gRPC streaming.
Export PSI some/full avg10 and avg60, AnonPages, swap usage, page fault
rates, and container count.

Balloon controller state machine: Four states (Bootstrap → Learning
Descend → Steady → OOM Recovery) with PSI-driven grow/shrink decisions.
Configurable thresholds, cooldowns, settle windows, and step sizes.
Learned floor tracking with OOM circuit breaker (3 OOMs in 10min locks
at max).

Host pressure monitor (macOS): Poll Mach vm_stat for free/inactive/
speculative pages. Classify Normal/Warning/Critical with hysteresis.
Critical triggers immediate grow; Warning halves shrink steps.

Auto-pause manager: Pause the VM after configurable idle timeout using
multi-signal idle detection (SSH connections, CPU, disk I/O, socket
proxy activity). Resume on incoming connections with socket proxy that
queues traffic during pause. Manual pause/resume via limactl commands.

VZ driver integration: Implement Ballooner and Pausable interfaces.
SetMemorySize via Virtualization.framework, pause/resume via VZ API.

CLI additions:
- limactl pause/resume: manual VM suspend and resume
- limactl ls: show physical memory footprint column

Template: Alpine Docker VZ template with memory optimization (swap,
zswap, cgroup tuning, PSI boot script, compaction cron).

Signed-off-by: Jason W. Ehrlich <jwehrlich@outlook.com>

Author: jwehrlich

cmd/lima-guestagent/daemon_linux.go

@@ -17,6 +17,7 @@ import (
 
 	"github.com/lima-vm/lima/v2/pkg/guestagent"
 	"github.com/lima-vm/lima/v2/pkg/guestagent/api/server"
+	"github.com/lima-vm/lima/v2/pkg/guestagent/metrics"
 	"github.com/lima-vm/lima/v2/pkg/guestagent/serialport"
 	"github.com/lima-vm/lima/v2/pkg/guestagent/ticker"
 	"github.com/lima-vm/lima/v2/pkg/portfwdserver"
@@ -145,5 +146,8 @@ func daemonAction(cmd *cobra.Command, _ []string) error {
 		logrus.Infof("serving the guest agent on %q", socket)
 	}
 	defer logrus.Debug("exiting lima-guestagent daemon")
-	return server.StartServer(ctx, l, &server.GuestServer{Agent: agent, TunnelS: portfwdserver.NewTunnelServer()})
+	dockerSocket := "/var/run/docker.sock"
+	collector := metrics.NewCollector(&dockerSocket)
+	defer collector.Close()
+	return server.StartServer(ctx, l, &server.GuestServer{Agent: agent, TunnelS: portfwdserver.NewTunnelServer(), Collector: collector})
 }

cmd/limactl/disk.go

@@ -345,7 +345,7 @@ func diskUnlockAction(cmd *cobra.Command, args []string) error {
 					diskName, disk.Instance, inst.Errors)
 				continue
 			}
-			if inst.Status == limatype.StatusRunning {
+			if inst.Status == limatype.StatusRunning || inst.Status == limatype.StatusPaused {
 				logrus.Warnf("Cannot unlock disk %q used by running instance %q", diskName, disk.Instance)
 				continue
 			}
@@ -403,7 +403,7 @@ func diskResizeAction(cmd *cobra.Command, args []string) error {
 	if disk.Instance != "" {
 		inst, err := store.Inspect(ctx, disk.Instance)
 		if err == nil {
-			if inst.Status == limatype.StatusRunning {
+			if inst.Status == limatype.StatusRunning || inst.Status == limatype.StatusPaused {
 				return fmt.Errorf("cannot resize disk %q used by running instance %q. Please stop the VM instance", diskName, disk.Instance)
 			}
 		}

cmd/limactl/edit.go

@@ -64,7 +64,7 @@ func editAction(cmd *cobra.Command, args []string) error {
 			}
 			return err
 		}
-		if inst.Status == limatype.StatusRunning {
+		if inst.Status == limatype.StatusRunning || inst.Status == limatype.StatusPaused {
 			return errors.New("cannot edit a running instance")
 		}
 		filePath = filepath.Join(inst.Dir, filenames.LimaYAML)

cmd/limactl/guest-install.go

@@ -64,8 +64,8 @@ func guestInstallAction(cmd *cobra.Command, args []string) error {
 	if err != nil {
 		return err
 	}
-	if inst.Status == limatype.StatusStopped {
-		return fmt.Errorf("instance %q is stopped, run `limactl start %s` to start the instance", instName, instName)
+	if inst.Status == limatype.StatusStopped || inst.Status == limatype.StatusPaused {
+		return fmt.Errorf("instance %q is not running (status: %s), run `limactl start %s` to start the instance", instName, inst.Status, instName)
 	}
 
 	ctx := cmd.Context()

cmd/limactl/main.go

@@ -181,6 +181,8 @@ func newApp() *cobra.Command {
 		newCreateCommand(),
 		newStartCommand(),
 		newStopCommand(),
+		newPauseCommand(),
+		newResumeCommand(),
 		newShellCommand(),
 		newCopyCommand(),
 		newListCommand(),

cmd/limactl/pause.go

@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: Copyright The Lima Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	hostagentclient "github.com/lima-vm/lima/v2/pkg/hostagent/api/client"
+	"github.com/lima-vm/lima/v2/pkg/limatype"
+	"github.com/lima-vm/lima/v2/pkg/limatype/filenames"
+	"github.com/lima-vm/lima/v2/pkg/store"
+)
+
+func newPauseCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:               "pause INSTANCE",
+		Short:             "Pause a running instance",
+		Long:              "Pause a running instance immediately. Requires auto-pause to be enabled in the instance configuration. The instance can be resumed with 'limactl resume' or automatically when a client connects to a forwarded socket.",
+		Args:              WrapArgsError(cobra.MaximumNArgs(1)),
+		RunE:              pauseAction,
+		ValidArgsFunction: pauseBashComplete,
+		GroupID:           basicCommand,
+	}
+}
+
+func pauseAction(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+	instName := DefaultInstanceName
+	if len(args) > 0 {
+		instName = args[0]
+	}
+
+	inst, err := store.Inspect(ctx, instName)
+	if err != nil {
+		return err
+	}
+
+	if inst.Status == limatype.StatusPaused {
+		return fmt.Errorf("instance %q is already paused", instName)
+	}
+	if inst.Status != limatype.StatusRunning {
+		return fmt.Errorf("instance %q is not running (status: %s)", instName, inst.Status)
+	}
+
+	haSock := filepath.Join(inst.Dir, filenames.HostAgentSock)
+	haClient, err := hostagentclient.NewHostAgentClient(haSock)
+	if err != nil {
+		return fmt.Errorf("failed to connect to host agent: %w", err)
+	}
+
+	if err := haClient.Pause(ctx); err != nil {
+		return fmt.Errorf("failed to pause instance %q: %w", instName, err)
+	}
+
+	fmt.Fprintf(cmd.OutOrStdout(), "Paused instance %q\n", instName)
+	return nil
+}
+
+func pauseBashComplete(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return bashCompleteInstanceNames(cmd)
+}

cmd/limactl/resume.go

@@ -0,0 +1,71 @@
+// SPDX-FileCopyrightText: Copyright The Lima Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"fmt"
+	"path/filepath"
+
+	"github.com/spf13/cobra"
+
+	hostagentclient "github.com/lima-vm/lima/v2/pkg/hostagent/api/client"
+	"github.com/lima-vm/lima/v2/pkg/limatype"
+	"github.com/lima-vm/lima/v2/pkg/limatype/filenames"
+	"github.com/lima-vm/lima/v2/pkg/store"
+)
+
+func newResumeCommand() *cobra.Command {
+	return &cobra.Command{
+		Use:               "resume INSTANCE",
+		Short:             "Resume a paused instance",
+		Long:              "Resume a paused instance. If the instance is already running, this is a no-op.",
+		Args:              WrapArgsError(cobra.MaximumNArgs(1)),
+		RunE:              resumeAction,
+		ValidArgsFunction: resumeBashComplete,
+		GroupID:           basicCommand,
+	}
+}
+
+func resumeAction(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+	instName := DefaultInstanceName
+	if len(args) > 0 {
+		instName = args[0]
+	}
+
+	inst, err := store.Inspect(ctx, instName)
+	if err != nil {
+		return err
+	}
+
+	if inst.Status == limatype.StatusRunning {
+		fmt.Fprintf(cmd.OutOrStdout(), "Instance %q is already running\n", instName)
+		return nil
+	}
+	if inst.Status != limatype.StatusPaused {
+		return fmt.Errorf("instance %q is not paused (status: %s)", instName, inst.Status)
+	}
+
+	haSock := filepath.Join(inst.Dir, filenames.HostAgentSock)
+	haClient, err := hostagentclient.NewHostAgentClient(haSock)
+	if err != nil {
+		return fmt.Errorf("failed to connect to host agent: %w", err)
+	}
+
+	triggered, err := haClient.Resume(ctx)
+	if err != nil {
+		return fmt.Errorf("failed to resume instance %q: %w", instName, err)
+	}
+	if !triggered {
+		fmt.Fprintf(cmd.OutOrStdout(), "Instance %q is already running\n", instName)
+		return nil
+	}
+
+	fmt.Fprintf(cmd.OutOrStdout(), "Resumed instance %q\n", instName)
+	return nil
+}
+
+func resumeBashComplete(cmd *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) {
+	return bashCompleteInstanceNames(cmd)
+}

cmd/limactl/shell.go

@@ -135,7 +135,7 @@ func shellAction(cmd *cobra.Command, args []string) error {
 	if inst.Config == nil {
 		return fmt.Errorf("instance %q has no configuration", instName)
 	}
-	if inst.Status == limatype.StatusStopped {
+	if inst.Status == limatype.StatusStopped || inst.Status == limatype.StatusPaused {
 		startNow, err := flags.GetBool("start")
 		if err != nil {
 			return err
@@ -149,7 +149,7 @@ func shellAction(cmd *cobra.Command, args []string) error {
 		}
 
 		if !startNow {
-			return fmt.Errorf("instance %q is stopped, run `limactl start %s` to start the instance", instName, instName)
+			return fmt.Errorf("instance %q is not running (status: %s), run `limactl start %s` to start the instance", instName, inst.Status, instName)
 		}
 
 		// Network reconciliation will be performed by the process launched by the autostart manager

cmd/limactl/start.go

@@ -581,6 +581,9 @@ func startAction(cmd *cobra.Command, args []string) error {
 			inst.Name, instance.LimactlShellCmd(inst.Name))
 		// Not an error
 		return nil
+	case limatype.StatusPaused:
+		logrus.Infof("The instance %q is paused and will be resumed by the host agent on activity.", inst.Name)
+		return nil
 	case limatype.StatusStopped:
 		// NOP
 	default:

cmd/limactl/tunnel.go

@@ -73,8 +73,8 @@ func tunnelAction(cmd *cobra.Command, args []string) error {
 		}
 		return err
 	}
-	if inst.Status == limatype.StatusStopped {
-		return fmt.Errorf("instance %q is stopped, run `limactl start %s` to start the instance", instName, instName)
+	if inst.Status == limatype.StatusStopped || inst.Status == limatype.StatusPaused {
+		return fmt.Errorf("instance %q is not running (status: %s), run `limactl start %s` to start the instance", instName, inst.Status, instName)
 	}
 
 	if port == 0 {