describe major modes of lima operation #3831

olamilekan000 · 2025-08-14T00:35:12Z

change explains how the Lima operation mode works.

fixes issue

jandubois · 2025-08-14T06:04:12Z

No time for a review right now, but I dislike the term "machine mode". I know it comes from the issue that this PR addresses, but most people will not make the connection to "docker-machine" and "podman-machine", and even then might not recognize the implications.

I would suggest that we talk about "integrated mode" (default) vs. "plain mode".

"Integrated" is kind of a long word, so I was looking for alternatives, like "blended mode", "fusion mode", "hybrid mode", "seamless mode", but in the end I think "integrated mode" is the most descriptive one.

What do you think @afbjorklund?

afbjorklund · 2025-08-14T07:47:02Z

The machine reference was mostly internal, we can call it something else in the user documentation...

The individual machines created are usually just referred to as "the instances", in Lima. Perhaps even "THE instance", since having more than one is an advanced topic (like the plain mode)

olamilekan000 · 2025-08-14T07:50:12Z

The machine reference was mostly internal, we can call it something else in the user documentation...

The individual machines created are usually just referred to as "the instances", in Lima. Perhaps even "THE instance", since having more than one is an advanced topic (like the plain mode)

does integrated or instance mode work?

jandubois · 2025-08-14T15:59:41Z

does integrated or instance mode work?

Doesn't work for me because "instance" is just a synonym for "machine", you can have "integrated" or "plain" instances.

Lima already means "Linux Machine", so "Lima machine" doesn't make much sense (like "ATM machine").

We use the terms "template" for just the spec of a machine, and "instance" for an actual implementation that can be run.

So I still think "integrated" (default) and "plain" are the best choices so far.

And no, we are not going to make "plain" the default. As "The Highlander" says: "There can be only one!", and "integrated" was here first. 😛

afbjorklund · 2025-08-14T17:52:55Z

We could just call it "default mode", if it is hard to come up with a name.

jandubois · 2025-08-14T18:54:52Z

We could just call it "default mode", if it is hard to come up with a name.

"default mode" is not descriptive (how is it different from "plain mode").

I think we should just go with "integrated mode" even though it is a mouthful.

Signed-off-by: olalekan odukoya <[email protected]>

afbjorklund

I think it looks very good, and I like that tries into explain differences and why/when

https://deploy-preview-3831--lima-vm.netlify.app/docs/usage/operation-modes/

afbjorklund · 2025-08-16T06:52:08Z

website/content/en/docs/usage/operation-modes.md

+- Reduced background processes in the guest
+
+#### 5. Minimal Host Integration
+- User information may still be mirrored for SSH access


This is true for now, in the future we might want to add a feature to only use a local user (like "ubuntu", or "lima")

It is a separate feature though, and if it is implemented later on we can just modify this sentence accordingly...

afbjorklund · 2025-08-16T06:55:20Z

website/content/en/docs/usage/operation-modes.md

+| **Port Forwarding** | ✅ Automatic | ❌ None |
+| **Container Engine** | ✅ containerd by default | ❌ None |
+| **Guest Agent** | ✅ Running | ❌ Disabled |
+| **User Mirroring** | ✅ Full mirroring | ✅ Basic (for SSH) |


This does look a bit "odd" in the column, we don't actually need the user account in plain mode do we?

Plain mode without mirroring user account #3844

AkihiroSuda · 2025-08-18T03:19:02Z

website/content/en/docs/usage/operation-modes.md

+- **Configuration Management**: Version control your Lima YAML configurations
+- **Testing**: Test your setup in both development and production-like scenarios
+
+## Troubleshooting Common Issues


FAQs should be consolidated into https://lima-vm.io/docs/faq/ ?

AkihiroSuda · 2025-08-18T03:19:52Z

website/content/en/docs/usage/operation-modes.md

+- **Integrated Mode (Default)**: Best for development workflows with seamless host-guest integration
+- **Plain Mode**: Best for traditional VM usage with explicit control and better isolation
+
+Choose the mode that best fits your security requirements, workflow preferences, and integration needs. You can always switch between modes by modifying your Lima configuration file.


You can always switch between modes by modifying your Lima configuration file.

I don't think you can switch an integrated mode into a plain mode in this way

Did ChatGPT or something write this section?

My money is on Claude Sonnet. 😄 (I recognize the style because I just used it last week to write a larger set of reference docs, and both the formatting and document structure closely resembles what it generated for me).

AkihiroSuda · 2025-08-18T03:23:17Z

website/content/en/docs/usage/operation-modes.md

+- **Resource Monitoring**: Monitor CPU, memory, and disk usage
+- **Regular Maintenance**: Keep the guest OS and packages updated
+- **Configuration Management**: Version control your Lima YAML configurations
+- **Testing**: Test your setup in both development and production-like scenarios


Too verbose and sounds like out of the topic of the "operation modes".

AkihiroSuda · 2025-08-18T03:23:38Z

website/content/en/docs/usage/operation-modes.md

+- **Review Mounted Directories**: Be aware of what host directories are accessible
+- **Use Read-Only Mounts**: Keep the home directory read-only unless you need to write
+- **Monitor Port Forwarding**: Be aware of which ports are being forwarded
+- **Regular Updates**: Keep the guest agent and container engines updated


The guest agent and nerdctl are automatically kept updated

As far as I know, this goes for Docker and Podman as well

AkihiroSuda · 2025-08-18T03:24:01Z

website/content/en/docs/usage/operation-modes.md

+
+### For Plain Mode
+- **Explicit Configuration**: Document all manual configurations you make
+- **Security Review**: Regularly audit what access the VM has to host resources


This rather sounds like a practice for integrated mode

AkihiroSuda · 2025-08-18T03:27:05Z

website/content/en/docs/usage/operation-modes.md

+
+### Key Features of Integrated Mode
+
+#### 1. User Mirroring


This is not specific to integrated mode

AkihiroSuda · 2025-08-18T03:27:57Z

website/content/en/docs/usage/operation-modes.md

+- Network services running in the guest become accessible from the host
+
+#### 4. Container Engine Integration
+Lima can automatically install and configure container engines:


Link https://lima-vm.io/docs/examples/

AkihiroSuda · 2025-08-18T03:28:03Z

website/content/en/docs/usage/operation-modes.md

+#### 4. Container Engine Integration
+Lima can automatically install and configure container engines:
+
+- **containerd**: Installed by default in user mode (rootless)


"user mode" sounds like the antonym of the "kernel mode"

AkihiroSuda · 2025-08-18T03:28:20Z

website/content/en/docs/usage/operation-modes.md

+A guest agent runs inside the VM to:
+- Manage port forwarding
+- Handle file system mounts
+- Coordinate host-guest integration


What integration?

AkihiroSuda · 2025-08-18T03:28:26Z

website/content/en/docs/usage/operation-modes.md

+- Manage port forwarding
+- Handle file system mounts
+- Coordinate host-guest integration
+- Provide status information


What status?

AkihiroSuda · 2025-08-18T03:29:08Z

website/content/en/docs/usage/operation-modes.md

+- **Container Development**: When you need Docker/Podman/containerd with host integration
+- **Development Workflows**: When you want to edit files on the host but run them in Linux
+- **Cross-platform Development**: When developing Linux applications on macOS/Windows
+- **CI/CD Testing**: When you need a Linux environment that integrates with host tools


I'd rather use the plain mode for CI to run "normal" Ubuntu that is usually seen on non-Lima environments.

See also https://lima-vm.io/docs/examples/gha/#plain-mode

AkihiroSuda · 2025-08-18T03:29:20Z

website/content/en/docs/usage/operation-modes.md

+Integrated mode is ideal for:
+- **Container Development**: When you need Docker/Podman/containerd with host integration
+- **Development Workflows**: When you want to edit files on the host but run them in Linux
+- **Cross-platform Development**: When developing Linux applications on macOS/Windows


Not specific to integrated mode

AkihiroSuda · 2025-08-18T03:29:51Z

website/content/en/docs/usage/operation-modes.md

+| **Port Forwarding** | ✅ Automatic | ❌ None |
+| **Container Engine** | ✅ containerd by default | ❌ None |
+| **Guest Agent** | ✅ Running | ❌ Disabled |
+| **User Mirroring** | ✅ Full mirroring | ✅ Basic (for SSH) |


What is "Full mirroring" ?

AkihiroSuda · 2025-08-18T03:30:01Z

website/content/en/docs/usage/operation-modes.md

+| **Container Engine** | ✅ containerd by default | ❌ None |
+| **Guest Agent** | ✅ Running | ❌ Disabled |
+| **User Mirroring** | ✅ Full mirroring | ✅ Basic (for SSH) |
+| **Host Integration** | ✅ Seamless | ❌ Minimal |


What is "Host Integration"?

AkihiroSuda · 2025-08-18T03:31:21Z

website/content/en/docs/usage/operation-modes.md

+Lima's default behavior of mounting the home directory is designed to provide seamless integration similar to Docker Machine or Podman Machine. This design choice:
+
+1. **Enables Seamless Development**: You can edit files on your host with your preferred tools and run them in the Linux environment
+2. **Maintains File Ownership**: The UID mirroring ensures files have correct permissions


The UID mirroring is kinda broken at least on Apple virtiofs

virtiofs: file ownerships dynamically changes depending on the caller's UID #1513

AkihiroSuda · 2025-08-18T03:31:59Z

website/content/en/docs/usage/operation-modes.md

+
+1. **Enables Seamless Development**: You can edit files on your host with your preferred tools and run them in the Linux environment
+2. **Maintains File Ownership**: The UID mirroring ensures files have correct permissions
+3. **Reduces Context Switching**: No need to copy files back and forth between host and guest


"Context Switching" may sound like talking about kernel/user context switches

AkihiroSuda · 2025-08-18T03:32:19Z

website/content/en/docs/usage/operation-modes.md

+1. **Enables Seamless Development**: You can edit files on your host with your preferred tools and run them in the Linux environment
+2. **Maintains File Ownership**: The UID mirroring ensures files have correct permissions
+3. **Reduces Context Switching**: No need to copy files back and forth between host and guest
+4. **Supports Container Workflows**: Container images can access host files for development


I don't get it

Possibly related to mounting, but could need some clarification

AkihiroSuda · 2025-08-18T03:33:32Z

website/content/en/docs/usage/operation-modes.md

+### "Ports aren't being forwarded"
+In plain mode, port forwarding is disabled. You need to:
+- Add explicit `portForwards` configuration
+- Or use plain networking and access the VM's IP directly


What is "plain networking"?

AkihiroSuda · 2025-08-18T03:37:53Z

website/content/en/docs/usage/operation-modes.md

Probably this should be rather under https://lima-vm.io/docs/config/ ?

AkihiroSuda

Sorry, this PR is too verbose, contains many misinformation and unclear sentences.

I suggest beginning with a smaller size of PR.

You can use LLM for "brainstorming" and reviewing your draft, but I suggest writing the final submission by your own hands

AkihiroSuda · 2025-08-18T04:29:16Z

website/content/en/docs/usage/operation-modes.md

+
+#### 2. No Port Forwarding
+- Ports are not automatically forwarded from guest to host
+- You must manually configure any port forwarding rules


This is not merged yet

Plain mode: support port forwarding #3699

AkihiroSuda · 2025-08-18T04:29:28Z

website/content/en/docs/usage/operation-modes.md

+#### 2. No Port Forwarding
+- Ports are not automatically forwarded from guest to host
+- You must manually configure any port forwarding rules
+- Network access requires explicit configuration


What network access ?

olamilekan000 force-pushed the describe-major-modes-of-lima-operation branch 3 times, most recently from 9a07017 to 6c8bbd3 Compare August 14, 2025 00:51

olamilekan000 force-pushed the describe-major-modes-of-lima-operation branch from 6c8bbd3 to ba49971 Compare August 14, 2025 17:22

describe major modes of lima operation

39c889a

Signed-off-by: olalekan odukoya <[email protected]>

olamilekan000 force-pushed the describe-major-modes-of-lima-operation branch from ba49971 to 39c889a Compare August 16, 2025 04:55

jandubois added this to the v2.0.0 milestone Aug 16, 2025

afbjorklund approved these changes Aug 16, 2025

View reviewed changes

afbjorklund reviewed Aug 16, 2025

View reviewed changes

AkihiroSuda reviewed Aug 18, 2025

View reviewed changes

AkihiroSuda removed this from the v2.0.0 milestone Aug 18, 2025

AkihiroSuda reviewed Aug 18, 2025

View reviewed changes

website/content/en/docs/usage/operation-modes.md

Copy link

Member

AkihiroSuda Aug 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably this should be rather under https://lima-vm.io/docs/config/ ?

AkihiroSuda requested changes Aug 18, 2025

View reviewed changes

AkihiroSuda added the documentation Improvements or additions to documentation label Aug 18, 2025

AkihiroSuda reviewed Aug 18, 2025

View reviewed changes

describe major modes of lima operation #3831

Are you sure you want to change the base?

describe major modes of lima operation #3831

Uh oh!

Conversation

olamilekan000 commented Aug 14, 2025

Uh oh!

jandubois commented Aug 14, 2025

Uh oh!

afbjorklund commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

olamilekan000 commented Aug 14, 2025

Uh oh!

jandubois commented Aug 14, 2025

Uh oh!

afbjorklund commented Aug 14, 2025

Uh oh!

jandubois commented Aug 14, 2025

Uh oh!

afbjorklund left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda left a comment

afbjorklund commented Aug 14, 2025 •

edited

Loading

AkihiroSuda Aug 18, 2025 •

edited

Loading

AkihiroSuda Aug 18, 2025 •

edited

Loading

AkihiroSuda Aug 18, 2025 •

edited

Loading