Configuration guide on Lima

Intel-on-ARM and ARM-on-Intel

Mon, 01 Jan 0001 00:00:00 +0000

Lima supports several modes for running Intel-on-ARM and ARM-on-Intel:

Slow mode: Intel VM on ARM Host / ARM VM on Intel Host

⚡ Requirement	QEMU, lima-additional-guestagents

Lima can run a VM with a foreign architecture, using QEMU.

For port forwarding, the lima-additional-guestagents package has to be installed on the host.

An example configuration:

limactl start --vm-type=qemu --arch=x86_64 --plain

See the YAML tab for the explanation of the corresponding CLI flags.

Port Forwarding

Mon, 01 Jan 0001 00:00:00 +0000

Lima supports automatic port-forwarding of localhost ports from guest to host.

See also: In plain mode, dynamic port forwarding is disabled and only rules with static: true are forwarded.

Port forwarding types

Lima supports two port forwarders: SSH and GRPC.

The default port forwarder is shown in the following table.

Version	Default
v0.1.0	SSH
v1.0.0	GRPC
v1.0.1	SSH
v1.1.0	GRPC

The default was once changed to GRPC in Lima v1.0, but it was reverted to SSH in v1.0.1 due to stability reasons. The default was further reverted to GRPC in Lima v1.1, as the stability issues were resolved.

Sudo

Mon, 01 Jan 0001 00:00:00 +0000

⚡ Requirement	Lima >= 2.2

By default, the guest user has passwordless sudo (NOPASSWD:ALL).

Warning user.passwordlessSudo: false is experimental. The default user.passwordlessSudo: true is not experimental.

The password is only generated once, on first boot. If you manually change the password and remove ~/password, it will not be regenerated on subsequent boots, the file is purely informational for the initial login.

user:
 passwordlessSudo: false

Caveats

Requires plain: true on non-macOS guests (GHSA-2j9v-p4xj-cjw2): the guest agent’s Unix socket tunneling is disabled until it can safely refuse privileged socket tunneling with passwordless sudo off.
Only applies to cloud-init provisioned guests (QEMU/vz). Setting user.passwordlessSudo: false on WSL2 (Windows) guests returns a validation error, as WSL2 does not support this configuration as of now.
The guest user is already a member of the adm and systemd-journal groups, which grants passive read access to /var/log/* and the full system journal independent of sudo.
param still relies on sudo internally (param.env is read via sudo cat inside the guest), so it may not work as expected when user.passwordlessSudo: false is set. A warning is printed in this case.
macOS: not configurable. Password-required sudo is always on (except /sbin/shutdown -h now), matching the built-in macOS guest behavior. Setting user.passwordlessSudo: true on a macOS guest returns a validation error.

Filesystem mounts

Mon, 01 Jan 0001 00:00:00 +0000

Lima supports several methods for mounting the host filesystem into the guest.

See also: In plain mode, all filesystem mounts are disabled.

The default mount type is shown in the following table:

Lima Version	Default
< 0.10	reverse-sshfs + Builtin SFTP server
>= 0.10	reverse-sshfs + OpenSSH SFTP server
>= 0.17	reverse-sshfs + OpenSSH SFTP server for QEMU, virtiofs for VZ
>= 1.0	9p for QEMU (on non-Windows), virtiofs for VZ

Mount types

reverse-sshfs

The “reverse-sshfs” mount type exposes the host filesystem by running an SFTP server on the host. While the host works as an SFTP server, the host does not open any TCP port, as the host initiates an SSH connection into the guest and let the guest connect to the SFTP server via the stdin.

Plain mode

Mon, 01 Jan 0001 00:00:00 +0000

Plain mode makes the VM instance as close as possible to a physical host by disabling Lima’s convenience features such as filesystem mounts, dynamic port forwarding, and the built-in containerd.

It is useful when you want to provision the guest with plain old ssh and rsync, without relying on Lima-specific integrations. See the GitHub Actions example for a typical use case.

Enabling plain mode

plain: true

limactl start --plain

Plain mode is disabled (false) by default.

Environment Variables

Mon, 01 Jan 0001 00:00:00 +0000

Environment Variables

This page documents the environment variables used in Lima.

`LIMA_HOME`

Description: Specifies the Lima home directory.
Default: ~/.lima
Usage:
```
export LIMA_HOME=~/.lima-custom
lima
```

`LIMA_INSTANCE`

Description: Specifies the name of the Lima instance to use.
Default: default

Usage:

export LIMA_INSTANCE=my-instance
lima uname -a

`LIMA_SHELL`

Description: Specifies the shell interpreter to use inside the Lima instance.
Default: User’s shell configured inside the instance
Usage:
```
export LIMA_SHELL=/bin/bash
lima
```

`LIMA_TEMPLATES_PATH`

Description: Specifies the directories used to resolve template: URLs.
Default: $LIMA_HOME/_templates:/usr/local/share/lima/templates

Usage:

export LIMA_TEMPLATES_PATH="$HOME/.config/lima/templates:/usr/local/share/lima/templates"
limactl create --name my-vm template:my-distro

`LIMA_WORKDIR`

Description: Specifies the initial working directory inside the Lima instance.
Default: Current directory from the host

Usage:

export LIMA_WORKDIR=/home/user/project
lima

`LIMA_SHELLENV_ALLOW`

Description: Specifies a comma-separated list of environment variable patterns to exempt from the block list when propagating environment variables to the Lima instance with --preserve-env. Variables matching the allow list pass through even if they also match the block list. Variables that match neither list pass through as well. This feature only applies to Lima v2.0.0 or later.
Default: unset (when using --preserve-env, all variables are propagated except those matching the block list patterns)

Usage:

# Pass FPATH and XAUTHORITY even though they are on the default block list
export LIMA_SHELLENV_ALLOW="FPATH,XAUTHORITY,CUSTOM_*"
limactl shell --preserve-env default

# To propagate ONLY specific variables, block everything else first
export LIMA_SHELLENV_BLOCK="*"
export LIMA_SHELLENV_ALLOW="GITHUB_TOKEN,MY_*"
limactl shell --preserve-env default

Behavior:
- Without --preserve-env: No environment variables are propagated (regardless of this setting)
- With --preserve-env and LIMA_SHELLENV_ALLOW unset: All variables are propagated except those in the block list
- With --preserve-env and LIMA_SHELLENV_ALLOW set: Variables matching the allow list are propagated even if they also match the block list. Variables matching neither list are still propagated. Only variables that match the block list without a corresponding allow list match are blocked.
Note: Patterns support * wildcards anywhere in the pattern (e.g., CUSTOM_* matches CUSTOM_VAR; *TOKEN* matches GITHUB_TOKEN).

`LIMA_SHELLENV_BLOCK`

Description: Specifies a comma-separated list of environment variable patterns to block when propagating environment variables to the Lima instance with --preserve-env. Can either replace the default block list or extend it by prefixing with +. This feature only applies to Lima v2.0.0 or later.

GPU acceleration

Mon, 01 Jan 0001 00:00:00 +0000

Lima VM supports GPU acceleration for the following VM types:

krunkit.

Note

“Lima” in this web site refers to the Lima VM project.

The Lima VM project is unrelated to the Lima driver project (driver for ARM Mali GPUs), which appears as “Lima” in the documentations of Mesa 3D, etc.

Disks

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to manage Lima disks: standalone raw/qcow2 block devices that persist independently of any instance.

Additional Disks (limactl disk)

Lima disks can be shared across instances and survive instance deletion.

Listing disks

limactl disk list
# or the short alias:
limactl disk ls

Creating a disk

limactl disk create NAME --size SIZE [--format qcow2|raw]

The supported formats are qcow2 (default) and raw.

Example – create a 20 GiB disk named data: