# lima-vm/lima architecture

> Architecture diagram of the GitHub repository lima-vm/lima, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lima-vm/lima
- Repository: https://github.com/lima-vm/lima

## Overview

##### Main Components

a) Host-side Components:
- limactl (Control CLI)
- Host Agent Service
- Network Management System
- File System Sharing
- Port Forwarding System

b) Guest-side Components:
- Guest Agent Service
- Container Runtime Support
- Mount Management
- Network Stack

##### Key Architectural Elements

**Top Layer: User Interface**
- CLI Tools (limactl, lima)
- Third-party Integration Points (Docker, Kubernetes, etc.)

**Middle Layer: Host Services**
- Host Agent
- Network Management
- Port Forwarding
- File System Management

**Bottom Layer: Virtual Machine Layer**
- Guest OS
- Guest Agent
- Container Runtimes
- System Services

##### Important Relationships

a) Control Flow:
- User commands → limactl → Host Agent → Guest Agent
- Network traffic flow between host and guest
- File system mount points and sharing mechanisms

b) Integration Points:
- Container runtime connections (Docker, containerd, etc.)
- Kubernetes integration
- Port forwarding mappings

##### Technical Details

- VM Types Support (QEMU, Virtualization.Framework, WSL2)
- Network Modes (user, bridged)
- Storage Systems (9P, virtiofs)
- Container Runtime Sockets

##### Specific Implementation Notes

- The separation between host and guest environments
- The communication channels between components
- The plugin architecture for different VM backends
- The template system for VM configurations

##### Key Flows to Highlight

a) VM Lifecycle:
**limactl start → Host Agent → VM Creation → Guest Agent → Service Setup**

b) Container Operations:
**Container Command → Lima CLI → Host Agent → Guest Agent → Container Runtime**

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph User_Interface
        CLI["Control CLI (limactl)"]:::cli
        ThirdParty["Third-party Tools<br/>(Docker, Kubernetes)"]:::external
    end

    subgraph Host_Services
        HostAgent["Host Agent Service"]:::core
        NetworkMgmt["Network Management"]:::network
        PortFwd["Port Forwarding"]:::network
        FSMgmt["File System Management"]:::storage
        VMConfig["VM Configuration"]:::core
        TmplSys["Template System"]:::core
        VMDrivers["VM Drivers"]:::core
    end

    subgraph Virtual_Machine_Layer
        GuestAgent["Guest Agent Service"]:::core
        ContRuntime["Container Runtime Support"]:::container
        MountMgmt["Mount Management"]:::storage
        NetStack["Network Stack"]:::network
        GuestOS["Guest OS"]:::core
    end

    %% Relationships
    CLI --> HostAgent
    CLI --> VMConfig
    HostAgent --> GuestAgent
    HostAgent --> NetworkMgmt
    HostAgent --> PortFwd
    HostAgent --> FSMgmt
    HostAgent --> VMDrivers
    NetworkMgmt --> NetStack
    FSMgmt --> MountMgmt
    VMConfig --> TmplSys
    GuestAgent --> ContRuntime
    ThirdParty --> ContRuntime

    %% Click Events
    click CLI "https://github.com/lima-vm/lima/tree/master/cmd/limactl/"
    click HostAgent "https://github.com/lima-vm/lima/tree/master/pkg/hostagent/"
    click GuestAgent "https://github.com/lima-vm/lima/tree/master/pkg/guestagent/"
    click NetworkMgmt "https://github.com/lima-vm/lima/tree/master/pkg/networks/"
    click PortFwd "https://github.com/lima-vm/lima/tree/master/pkg/portfwd/"
    click FSMgmt "https://github.com/lima-vm/lima/tree/master/pkg/fsutil/"
    click ContRuntime "https://github.com/lima-vm/lima/blob/master/templates/docker.yaml"
    click VMConfig "https://github.com/lima-vm/lima/tree/master/pkg/cidata/"
    click NetStack "https://github.com/lima-vm/lima/tree/master/pkg/networks/usernet/"
    click TmplSys "https://github.com/lima-vm/lima/tree/master/pkg/limatmpl/"
    click VMDrivers "https://github.com/lima-vm/lima/tree/master/pkg/driver/"
    click MountMgmt "https://github.com/lima-vm/lima/blob/master/pkg/hostagent/mount.go"

    %% Styles
    classDef core fill:#2374f7,stroke:#333,stroke-width:2px
    classDef network fill:#4CAF50,stroke:#333,stroke-width:2px
    classDef storage fill:#FF9800,stroke:#333,stroke-width:2px
    classDef container fill:#9C27B0,stroke:#333,stroke-width:2px
    classDef external fill:#757575,stroke:#333,stroke-width:2px
    classDef cli fill:#03A9F4,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Network Components"]:::network
        L3["Storage Components"]:::storage
        L4["Container Components"]:::container
        L5["External Systems"]:::external
        L6["CLI Tools"]:::cli
    end
```
