Host Agent System

Relevant source files

• pkg/hostagent/hostagent.go
• pkg/limayaml/default.yaml
• pkg/limayaml/defaults.go
• pkg/limayaml/defaults_test.go
• pkg/limayaml/load.go
• pkg/limayaml/validate.go
• pkg/limayaml/validate_test.go

The Host Agent is a host-side daemon process that manages the lifecycle of a Lima instance. It orchestrates VM drivers, establishes communication with the guest agent, handles port forwarding, manages filesystem mounts, and monitors instance status. The host agent runs for the entire lifetime of a VM instance and serves as the primary control plane for host-to-guest interactions.

For information about guest-side operations, see Guest Agent System. For VM driver details, see VM Driver System. For configuration management, see Configuration System.

Host Agent Role and Responsibilities

The host agent serves as the central coordinator between:

• The Lima CLI commands that start/stop instances
• The VM driver (QEMU, VZ, or WSL2) that runs the guest
• The guest agent running inside the VM
• Host system resources (network, filesystem, SSH)

Key responsibilities:

• Instance Initialization: Generates cloud-init configuration and starts the VM
• Connection Management: Establishes and maintains SSH and gRPC connections to the guest
• Mount Management: Sets up filesystem sharing (reverse-sshfs, virtiofs, 9p, or WSL mounts)
• Port Forwarding: Configures both static and dynamic port forwarding rules
• Event Monitoring: Receives and processes events from the guest agent
• Status Reporting: Emits JSON event messages to stdout for CLI consumption
• Lifecycle Control: Handles graceful shutdown and cleanup

Sources: pkg/hostagent/hostagent.go1-86

HostAgent Structure

The HostAgent struct contains:

Field Category	Key Fields	Purpose
Configuration	instConfig, instDir, instName	Instance configuration and paths
Network	sshLocalPort, udpDNSLocalPort, tcpDNSLocalPort	Port allocations for communication
Port Forwarding	portForwarder, grpcPortForwarder	Dual-mode port forwarding (SSH and gRPC)
Guest Communication	client, vSockPort, virtioPort	Guest agent connection details
Driver	driver	VM driver abstraction (QEMU/VZ/WSL2)
Lifecycle	signalCh, onClose	Shutdown coordination
Event Reporting	eventEnc, currentStatus	Status emission to CLI

Sources: pkg/hostagent/hostagent.go51-85

Host Agent Initialization Flow

The New() function performs the following initialization steps:

1. Load Instance Configuration: Retrieves instance metadata from the store
2. Determine SSH Port: Either uses configured port or allocates a free port
3. Allocate DNS Ports: If host resolver is enabled, allocates UDP and TCP ports
4. Create VM Driver: Initializes the appropriate driver (QEMU/VZ/WSL2)
5. Generate Cloud-Init: Creates cloud-init configuration and ISO image
6. Configure SSH: Sets up SSH configuration and writes ssh.config file
7. Build Port Forward Rules: Constructs port forwarding rule list with appropriate precedence
8. Initialize Port Forwarders: Creates both legacy SSH and gRPC port forwarders

The SSH port determination logic:

• If explicitly configured (non-zero): use that port
• If instance is "default" and Lima version < 2.0.0: use 60022 for backward compatibility
• Otherwise: allocate a free port using freeport.TCP()

Sources: pkg/hostagent/hostagent.go119-258 pkg/hostagent/hostagent.go293-309

Host Agent Execution Lifecycle

The main execution flow in Run():

1. Adjust Resources: Sets file descriptor limits
2. Start DNS Server: If host resolver is enabled, starts DNS server on localhost
3. Start VM Driver: Calls driver.Start(ctx) which returns an error channel
4. Update SSH Address: For WSL2, retrieves dynamic SSH address
5. Setup VNC (optional): If VNC display is configured, sets up VNC connection
6. Launch Goroutine: Starts startHostAgentRoutines() in a goroutine
7. Wait for Termination: Blocks on either driver error channel or signal channel
8. Cleanup: Calls close() to execute registered cleanup functions in LIFO order
9. Stop Driver: Calls driver.Stop(ctx) to gracefully stop the VM

The routine startup process (startHostAgentRoutines):

• Registers SSH master cleanup
• Waits for essential requirements (SSH connectivity, guest reachability)
• Sets up SSH agent forwarding if enabled
• Mounts filesystems (if not plain mode)
• Separates and applies static port forwards
• Starts guest agent event watcher
• Waits for optional requirements (guest agent alive)
• Waits for final requirements (provision completion)
• Copies files to host as configured

Sources: pkg/hostagent/hostagent.go343-477 pkg/hostagent/hostagent.go492-616

Guest Agent Communication Architecture

The host agent establishes guest agent connections using a priority order:

1. VSOCK/VirtIO (preferred): Uses driver.GuestAgentConn(ctx) if the driver supports it
2. SSH-forwarded Unix Socket (fallback): Connects to ~/.lima/INSTANCE/ga.sock which is forwarded to /run/lima-guestagent.sock in the guest

Connection establishment:

• getOrCreateClient() pkg/hostagent/hostagent.go773-782 creates or reuses the guest agent client
• createConnection() pkg/hostagent/hostagent.go784-792 provides the connection callback
• Client is created with guestagentclient.NewGuestAgentClient()

Event processing flow:

• watchGuestAgentEvents() runs continuously in a goroutine
• Retries every 10 seconds if connection fails
• Forwards Unix socket for guest agent if needed
• Calls processGuestAgentEvents() when connected
• processGuestAgentEvents() retrieves guest info and streams events
• Each event is passed to onEvent() callback which dispatches to port forwarders

The host agent chooses between SSH-based and gRPC-based port forwarding via the LIMA_SSH_PORT_FORWARDER environment variable (defaults to false for gRPC-based).

Sources: pkg/hostagent/hostagent.go640-722 pkg/hostagent/hostagent.go773-840

Integration with VM Drivers

The host agent interacts with VM drivers through the driver.Driver interface. Key driver operations used:

Operation	Usage in Host Agent	Description
Start(ctx)	Called in Run() to start the VM	Returns error channel for async failures
Stop(ctx)	Called during shutdown	Gracefully stops the VM
Info()	Called during initialization	Returns driver capabilities (VSOCK, VirtIO, features)
GuestAgentConn(ctx)	Called when creating guest connection	Provides native connection if available
SSHAddress(ctx)	Called after start (WSL2)	Retrieves dynamic SSH address
ForwardGuestAgent()	Used in event watching	Determines if SSH forwarding is needed

Driver-specific features extracted from Info():

• VsockPort: Port number for VSOCK communication
• VirtioPort: Port identifier for VirtIO communication
• NoCloudInit: Whether driver bypasses cloud-init
• RosettaEnabled, RosettaBinFmt: Rosetta support (VZ on macOS)
• DynamicSSHAddress: Whether SSH address is determined post-start (WSL2)
• CanRunGUI: Whether driver supports GUI mode
• SkipSocketForwarding: Whether to skip SSH socket forwarding setup

The driver is created during initialization via driverutil.CreateConfiguredDriver() which:

1. Selects the appropriate driver based on vmType configuration
2. Configures driver-specific options
3. Returns the initialized driver instance and potentially updated SSH local port

Sources: pkg/hostagent/hostagent.go157-162 pkg/hostagent/hostagent.go378-390 pkg/hostagent/hostagent.go436-445 pkg/hostagent/hostagent.go784-792

Event Emission and Status Reporting

The host agent emits JSON-encoded status events to stdout, which are consumed by the Lima CLI:

Key event emission points:

When	Status Fields	Purpose
VM starting	SSHLocalPort set, others false	Indicate boot in progress
Host agent routines started	Running=true, errors if any degraded	Main operation started
During cloud-init	CloudInitProgress updated	Show provisioning progress
Error occurs	Degraded=true, Errors populated	Report non-fatal issues
Shutdown initiated	Exiting=true	Signal termination

The emitEvent() function pkg/hostagent/hostagent.go311-325:

• Updates currentStatus with the new status
• Sets event timestamp if not already set
• JSON-encodes the event to stdout
• Protected by eventEncMu mutex for thread safety

Cloud-init progress monitoring pkg/hostagent/hostagent.go940-1051:

• Optionally enabled via WithCloudInitProgress() option
• Polls cloud-init status every 5 seconds
• Emits progress events with log lines
• Runs with 10-minute timeout
• Marks complete when cloud-init finishes

Sources: pkg/hostagent/hostagent.go311-336 pkg/hostagent/hostagent.go940-1051

Cleanup and Shutdown

The host agent implements a LIFO (Last-In-First-Out) cleanup mechanism:

Cleanup functions are registered via cleanUp() pkg/hostagent/hostagent.go618-624:

• Appends cleanup function to onClose slice
• Protected by onCloseMu mutex
• Functions are called in reverse order during shutdown

Common cleanup operations registered:

1. Port Forwarder Cleanup: grpcPortForwarder.Close() pkg/hostagent/hostagent.go695
2. Socket Forward Cancellation: Cancel SSH socket forwards pkg/hostagent/hostagent.go658-677
3. Mount Cleanup: Unmount all reverse-sshfs mounts pkg/hostagent/hostagent.go532-540
4. Disk Unlock: Unlock additional disks pkg/hostagent/hostagent.go543-557
5. File Deletion: Delete copyToHost files if deleteOnStop=true pkg/hostagent/hostagent.go603-614
6. SSH Master Shutdown: Exit SSH master connection pkg/hostagent/hostagent.go503-509

The cleanup process:

• Executes before context cancellation
• Runs in reverse order to ensure proper dependency unwinding
• Collects all errors via errors.Join()
• Does not abort on individual cleanup failures
• Followed by driver shutdown and final event emission

Sources: pkg/hostagent/hostagent.go465-477 pkg/hostagent/hostagent.go618-638

Relationship to Child Pages

This overview covers the host agent's role and structure. For detailed information:

• Host Agent Architecture and Initialization (#7.1): Deep dive into New() function, driver configuration, cloud-init generation, and SSH setup
• Guest-Host Communication Channels (#7.2): Detailed explanation of SSH master connections, gRPC over VSOCK/VirtIO, HTTP API, and event streaming
• Port Forwarding Implementation (#7.3): Static vs dynamic forwarding, SSH-based vs gRPC-based mechanisms, and automatic port discovery

Sources: pkg/hostagent/hostagent.go1-1461 pkg/limayaml/defaults.go1-1005