# abiosoft/colima architecture

> Architecture diagram of the GitHub repository abiosoft/colima, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abiosoft/colima
- Repository: https://github.com/abiosoft/colima

## Overview

Colima provisions and manages per-profile Linux VMs on macOS/Linux, then configures container runtimes and optional Kubernetes or Incus. The main workflow is CLI start → configuration → app orchestration → Lima VM and runtime setup; daemon-managed networking and mount notifications support the running instance. README also documents model-runner commands and lifecycle, SSH, status, and maintenance operations. Edges cite only visible calls or README-documented capabilities; unsampled implementation links are omitted.

Main entry points: [`app/app.go`](https://github.com/abiosoft/colima/blob/main/app/app.go) (App lifecycle), [`cmd/start.go`](https://github.com/abiosoft/colima/blob/main/cmd/start.go) (CLI commands), [`model/runner.go`](https://github.com/abiosoft/colima/blob/main/model/runner.go) (Model runners), [`environment/vm/lima/lima.go`](https://github.com/abiosoft/colima/blob/main/environment/vm/lima/lima.go) (Lima VM adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and profiles"]
  node_commands["CLI commands<br/>[start.go]"]
  node_root["Command root<br/>[root.go]"]
  node_configuration["Profiles and config<br/>[configmanager.go]"]
  node_state[("Profile state<br/>[store.go]")]
end

subgraph group_orchestration["Instance orchestration"]
  node_app["App lifecycle<br/>[app.go]"]
  node_model["AI model commands<br/>[model.go]"]
  node_modelrunner["Model runners<br/>[runner.go]"]
  node_docker_model["Docker model backend<br/>[docker.go]"]
  node_ramalama["Ramalama backend<br/>[ramalama.go]"]
end

subgraph group_vm["VM and host integration"]
  node_lima["Lima VM adapter<br/>[lima.go]"]
  node_lima_config["VM configuration<br/>[yaml.go]"]
  node_host["Host integration<br/>[host.go]"]
  node_downloads["Image downloads<br/>[http.go]"]
end

subgraph group_runtime["Container runtimes"]
  node_docker["Docker runtime<br/>[docker.go]"]
  node_containerd["Containerd runtime<br/>[containerd.go]"]
  node_incus["Incus runtime<br/>[incus.go]"]
  node_kubernetes["Kubernetes<br/>[kubernetes.go]"]
end

subgraph group_background["Background services"]
  node_daemon["Daemon manager<br/>[daemon.go]"]
  node_processes["Host processes<br/>[process.go]"]
  node_inotify["Mount notifications<br/>[volumes.go]"]
  node_vmnet["VM networking<br/>[vmnet.go]"]
end

node_user(("Colima user"))
node_docker_cli(("Docker client"))
node_nerdctl_cli(("nerdctl client"))
node_kubectl(("kubectl client"))
node_incus_cli(("Incus client"))
node_model_registry(("Model registries"))

node_user -->|"invokes"| node_commands
node_commands -->|"registers with"| node_root
node_commands -->|"loads and validates"| node_configuration
node_commands -->|"starts instance"| node_app
node_app -->|"starts VM"| node_lima
node_app -->|"starts runtime"| node_docker
node_app -->|"selects runtime"| node_containerd
node_app -->|"selects runtime"| node_incus
node_app -->|"detects Kubernetes"| node_kubernetes
node_app -->|"reads and writes"| node_state
node_lima -->|"builds VM config"| node_lima_config
node_lima_config -->|"uses network state"| node_daemon
node_commands -->|"offers model commands"| node_model
node_model -->|"selects runner"| node_modelrunner
node_modelrunner -->|"dispatches Docker"| node_docker_model
node_modelrunner -->|"dispatches Ramalama"| node_ramalama
node_modelrunner -->|"runs guest commands"| node_lima
node_model_registry -.->|"supplies models"| node_modelrunner
node_docker_cli -.->|"uses runtime"| node_docker
node_nerdctl_cli -.->|"uses runtime"| node_containerd
node_kubectl -.->|"uses cluster"| node_kubernetes
node_incus_cli -.->|"uses runtime"| node_incus
node_commands -->|"manages services"| node_daemon
node_daemon -->|"selects processes"| node_processes
node_daemon -->|"registers watcher"| node_inotify
node_daemon -->|"registers networking"| node_vmnet
node_inotify -->|"tracks volumes"| node_docker
node_inotify -->|"tracks volumes"| node_containerd
node_lima -.->|"uses host actions"| node_host
node_lima -.->|"obtains images"| node_downloads

click node_commands "https://github.com/abiosoft/colima/blob/main/cmd/start.go"
click node_root "https://github.com/abiosoft/colima/blob/main/cmd/root/root.go"
click node_configuration "https://github.com/abiosoft/colima/blob/main/config/configmanager/configmanager.go"
click node_state "https://github.com/abiosoft/colima/blob/main/store/store.go"
click node_app "https://github.com/abiosoft/colima/blob/main/app/app.go"
click node_model "https://github.com/abiosoft/colima/blob/main/cmd/model.go"
click node_modelrunner "https://github.com/abiosoft/colima/blob/main/model/runner.go"
click node_docker_model "https://github.com/abiosoft/colima/blob/main/model/docker.go"
click node_ramalama "https://github.com/abiosoft/colima/blob/main/model/ramalama.go"
click node_lima "https://github.com/abiosoft/colima/blob/main/environment/vm/lima/lima.go"
click node_lima_config "https://github.com/abiosoft/colima/blob/main/environment/vm/lima/yaml.go"
click node_host "https://github.com/abiosoft/colima/blob/main/environment/host/host.go"
click node_downloads "https://github.com/abiosoft/colima/blob/main/util/downloader/http.go"
click node_docker "https://github.com/abiosoft/colima/blob/main/environment/container/docker/docker.go"
click node_containerd "https://github.com/abiosoft/colima/blob/main/environment/container/containerd/containerd.go"
click node_incus "https://github.com/abiosoft/colima/blob/main/environment/container/incus/incus.go"
click node_kubernetes "https://github.com/abiosoft/colima/blob/main/environment/container/kubernetes/kubernetes.go"
click node_daemon "https://github.com/abiosoft/colima/blob/main/daemon/daemon.go"
click node_processes "https://github.com/abiosoft/colima/blob/main/daemon/process/process.go"
click node_inotify "https://github.com/abiosoft/colima/blob/main/daemon/process/inotify/volumes.go"
click node_vmnet "https://github.com/abiosoft/colima/blob/main/daemon/process/vmnet/vmnet.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_commands,node_root,node_configuration,node_state,node_user,node_docker_cli,node_nerdctl_cli,node_kubectl,node_incus_cli toneBlue
class node_app,node_model,node_modelrunner,node_docker_model,node_ramalama toneAmber
class node_lima,node_lima_config,node_host,node_downloads toneMint
class node_docker,node_containerd,node_incus,node_kubernetes toneRose
class node_daemon,node_processes,node_inotify,node_vmnet,node_model_registry toneIndigo
```

## Components

### CLI and profiles

- [CLI commands](https://github.com/abiosoft/colima/blob/main/cmd/start.go): `cmd/start.go`
- [Command root](https://github.com/abiosoft/colima/blob/main/cmd/root/root.go): `cmd/root/root.go`
- [Profiles and config](https://github.com/abiosoft/colima/blob/main/config/configmanager/configmanager.go): `config/configmanager/configmanager.go`
- [Profile state](https://github.com/abiosoft/colima/blob/main/store/store.go): `store/store.go`

### Instance orchestration

- [App lifecycle](https://github.com/abiosoft/colima/blob/main/app/app.go): `app/app.go`
- [AI model commands](https://github.com/abiosoft/colima/blob/main/cmd/model.go): `cmd/model.go`
- [Model runners](https://github.com/abiosoft/colima/blob/main/model/runner.go): `model/runner.go`
- [Docker model backend](https://github.com/abiosoft/colima/blob/main/model/docker.go): `model/docker.go`
- [Ramalama backend](https://github.com/abiosoft/colima/blob/main/model/ramalama.go): `model/ramalama.go`

### VM and host integration

- [Lima VM adapter](https://github.com/abiosoft/colima/blob/main/environment/vm/lima/lima.go): `environment/vm/lima/lima.go`
- [VM configuration](https://github.com/abiosoft/colima/blob/main/environment/vm/lima/yaml.go): `environment/vm/lima/yaml.go`
- [Host integration](https://github.com/abiosoft/colima/blob/main/environment/host/host.go): `environment/host/host.go`
- [Image downloads](https://github.com/abiosoft/colima/blob/main/util/downloader/http.go): `util/downloader/http.go`

### Container runtimes

- [Docker runtime](https://github.com/abiosoft/colima/blob/main/environment/container/docker/docker.go): `environment/container/docker/docker.go`
- [Containerd runtime](https://github.com/abiosoft/colima/blob/main/environment/container/containerd/containerd.go): `environment/container/containerd/containerd.go`
- [Incus runtime](https://github.com/abiosoft/colima/blob/main/environment/container/incus/incus.go): `environment/container/incus/incus.go`
- [Kubernetes](https://github.com/abiosoft/colima/blob/main/environment/container/kubernetes/kubernetes.go): `environment/container/kubernetes/kubernetes.go`

### Background services

- [Daemon manager](https://github.com/abiosoft/colima/blob/main/daemon/daemon.go): `daemon/daemon.go`
- [Host processes](https://github.com/abiosoft/colima/blob/main/daemon/process/process.go): `daemon/process/process.go`
- [Mount notifications](https://github.com/abiosoft/colima/blob/main/daemon/process/inotify/volumes.go): `daemon/process/inotify/volumes.go`
- [VM networking](https://github.com/abiosoft/colima/blob/main/daemon/process/vmnet/vmnet.go): `daemon/process/vmnet/vmnet.go`

### Other components

- **Colima user**
- **Docker client**
- **nerdctl client**
- **kubectl client**
- **Incus client**
- **Model registries**

## Connections

- Colima user → CLI commands: invokes
- CLI commands → Command root: registers with
- CLI commands → Profiles and config: loads and validates (evidence: `cmd/start.go`)
- CLI commands → App lifecycle: starts instance (evidence: `cmd/start.go`)
- App lifecycle → Lima VM adapter: starts VM (evidence: `app/app.go`)
- App lifecycle → Docker runtime: starts runtime (evidence: `app/app.go`)
- App lifecycle → Containerd runtime: selects runtime (evidence: `app/app.go`)
- App lifecycle → Incus runtime: selects runtime (evidence: `app/app.go`)
- App lifecycle → Kubernetes: detects Kubernetes (evidence: `app/app.go`)
- App lifecycle → Profile state: reads and writes (evidence: `app/app.go`)
- Lima VM adapter → VM configuration: builds VM config (evidence: `environment/vm/lima/yaml.go`)
- VM configuration → Daemon manager: uses network state (evidence: `environment/vm/lima/yaml.go`)
- CLI commands → AI model commands: offers model commands
- AI model commands → Model runners: selects runner (evidence: `cmd/model.go`)
- Model runners → Docker model backend: dispatches Docker (evidence: `model/runner.go`)
- Model runners → Ramalama backend: dispatches Ramalama (evidence: `model/runner.go`)
- Model runners → Lima VM adapter: runs guest commands (evidence: `model/runner.go`)
- Model registries → Model runners: supplies models
- Docker client → Docker runtime: uses runtime
- nerdctl client → Containerd runtime: uses runtime
- kubectl client → Kubernetes: uses cluster
- Incus client → Incus runtime: uses runtime
- CLI commands → Daemon manager: manages services (evidence: `cmd/start.go`)
- Daemon manager → Host processes: selects processes (evidence: `daemon/daemon.go`)
- Daemon manager → Mount notifications: registers watcher (evidence: `daemon/daemon.go`)
- Daemon manager → VM networking: registers networking (evidence: `daemon/daemon.go`)
- Mount notifications → Docker runtime: tracks volumes (evidence: `daemon/process/inotify/volumes.go`)
- Mount notifications → Containerd runtime: tracks volumes (evidence: `daemon/process/inotify/volumes.go`)
- Lima VM adapter → Host integration: uses host actions
- Lima VM adapter → Image downloads: obtains images
