This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Examples

Running Linux commands

lima uname -a

Accessing host files

By default, the VM has read-only accesses to /Users/<USERNAME>.

To allow writing to /Users/<USERNAME>:

limactl edit --mount-writable

Running containers

nerdctl.lima run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine

limactl start template://docker
export DOCKER_HOST=$(limactl list docker --format 'unix://{{.Dir}}/sock/docker.sock')
docker run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine

limactl start template://podman
export DOCKER_HOST=$(limactl list podman --format 'unix://{{.Dir}}/sock/podman.sock')
docker run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine

limactl start template://k8s
export KUBECONFIG=$(limactl list k8s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
kubectl apply -f ...

Advanced configuration

limactl start \
  --name=default \
  --cpus=4 \
  --memory=8 \
  --vm-type=vz \
  --rosetta \
  --mount-writable \
  --network=vzNAT \
  template://fedora
  • --name=default: Set the instance name to “default”
  • --cpus=4: Set the number of the CPUs to 4
  • --memory=8: Set the amount of the memory to 8 GiB
  • --vm-type=vz: Use Apple’s Virtualization.framework (vz) to enable Rosetta, virtiofs, and vzNAT
  • --rosetta: Allow running Intel (AMD) binaries on ARM
  • --mount-writable: Make the home mount (/Users/<USERNAME>) writable
  • --network=vzNAT: Make the VM reachable from the host by its IP address
  • template://fedora: Use Fedora

1 - AI agents

Lima is useful for running AI agents inside a VM, so as to prevent agents from directly reading, writing, or executing the host files.

For running AI agents, it is highly recommended to only mount your project directory (current directory) into the VM:

limactl start --mount-only .:w

Drop :w for read-only mode.

limactl start --set ".mounts=[{\"location\":\"$(pwd)\", \"writable\":true}]"

Set writable to false for read-only mode.

lima sudo apt install -y pipx
lima pipx install aider-install
lima sh -c 'echo "export PATH=$PATH:$HOME/.local/bin" >>~/.bash_profile'
lima aider-install
lima aider

Follow the guide shown in the first session for authentication.

Alternatively, you can set environmental variables via:

lima vi "/home/${USER}.linux/.bash_profile"

See also https://github.com/Aider-AI/aider.

lima sudo snap install node --classic
lima sudo npm install -g @anthropic-ai/claude-code
lima codex

Follow the guide shown in the first session for authentication.

Alternatively, you can set export ANTHROPIC_API_KEY... via:

lima vi "/home/${USER}.linux/.bash_profile"

See also https://github.com/anthropics/claude-code.

lima sudo snap install node --classic
lima sudo npm install -g @openai/codex
lima codex

Follow the guide shown in the first session for authentication.

Alternatively, you can set export OPENAI_API_KEY... via:

lima vi "/home/${USER}.linux/.bash_profile"

See also https://github.com/openai/codex.

lima sudo snap install node --classic
lima sudo npm install -g @google/gemini-cli
lima gemini

Follow the guide shown in the first session for authentication.

Alternatively, you can set export GEMINI_API_KEY... via:

lima vi "/home/${USER}.linux/.bash_profile"

See also https://github.com/google-gemini/gemini-cli.

lima sudo snap install node --classic
lima sudo npm install -g @github/copilot
lima copilot

Type /login in the first session for authentication.

Alternatively, you can set export GH_TOKEN=... via:

lima vi "/home/${USER}.linux/.bash_profile"

See also https://github.com/github/copilot-cli.

See also

2 - GitHub Actions

Running Lima on GitHub Actions

On GitHub Actions, Lima is useful for:

  • Running commands on non-Ubuntu operating systems (e.g., Fedora for testing SELinux)
  • Emulating multiple hosts

While these tasks can be partially accomplished with containers like Docker, those containers still rely on the Ubuntu host’s kernel and cannot utilize features missing in Ubuntu, such as SELinux.

In contrast, Lima runs virtual machines that do not depend on the Ubuntu host’s kernel.

The following GitHub Actions workflow illustrates how to run multiple instances of Fedora using Lima. The instances are connected by the user-v2 network.

name: Fedora

on:
  workflow_dispatch:
  pull_request:

jobs:
  fedora:
    runs-on: ubuntu-24.04
    steps:
    - name: Check out code
      uses: actions/checkout@v4

    - name: "Set up Lima"
      uses: lima-vm/lima-actions/setup@v1
      id: lima-actions-setup

    - name: "Cache ~/.cache/lima"
      uses: actions/cache@v4
      with:
        path: ~/.cache/lima
        key: lima-${{ steps.lima-actions-setup.outputs.version }}

    - name: "Start an instance of Fedora"
      run: |
        set -eux
        limactl start --name=default --cpus=1 --memory=1 --network=lima:user-v2 template://fedora
        lima sudo dnf install -y httpd
        lima sudo systemctl enable --now httpd        

    - name: "Start another instance of Fedora"
      run: |
        set -eux
        limactl start --name=another --cpus=1 --memory=1 --network=lima:user-v2 template://fedora
        limactl shell another curl http://lima-default.internal

See also https://github.com/lima-vm/lima-actions.

Plain mode

The --plain mode is useful when you want the VM instance to be as close as possible to a physical host:

    - name: "Start Fedora"
      # --plain is set to disable file sharing, port forwarding, built-in containerd, etc.
      run: limactl start --plain --name=default --cpus=1 --memory=1 --network=lima:user-v2 template://fedora

    - name: "Set up SSH"
      uses: lima-vm/lima-actions/ssh@v1

    - name: "Initialize Fedora"
      # plain old rsync and ssh are used for the initialization of the guest,
      # so that people who are not familiar with Lima can understand the initialization steps.
      run: |
        set -eux -o pipefail
        # Sync the current directory to /tmp/repo in the guest
        rsync -a -e ssh . lima-default:/tmp/repo
        # Install packages
        ssh lima-default sudo dnf install -y httpd

Full examples