Garden Linux

Appearance

First Boot on Lima ​

Garden Linux is a minimal, security-hardened Linux distribution designed for cloud and container environments. Lima (Linux Machines) is a virtual machine lifecycle management tool that makes it straightforward to run virtual machines on your local workstation. Lima takes care of configuration details such as creating a user, setting up SSH access, and mounting directories into the VM.

This tutorial guides you through deploying your first Garden Linux instance using Lima, from launching the VM to verifying the installation.

Difficulty: Beginner | Time: ~5 minutes

Learning Objective: By the end of this tutorial, you'll have a running Garden Linux virtual machine under Lima and understand the basic deployment workflow.

Prerequisites ​

Before starting, you'll need:

  • A macOS or Linux host with virtualization support
  • Lima installed
  • Podman installed (for generating the Lima YAML manifest)

TIP

Install Lima and Podman on Debian/Ubuntu-based systems:

bash
# Install Lima
sudo apt install lima

# Install Podman
sudo apt install podman

On macOS, use Homebrew:

bash
brew install lima podman

What You'll Build ​

You'll launch a Garden Linux virtual machine using Lima with a single command, open a shell into the VM, and verify the installation. Lima handles all QEMU configuration, SSH setup, and user provisioning automatically — no manual configuration scripts are needed.

Steps ​

Step 1: Create and Start the VM ​

Garden Linux provides pre-built images suitable for use with Lima. A containerized YAML generator (ghcr.io/gardenlinux/gardenlinux/lima:latest) produces the correct Lima manifest automatically, so you don't need to construct image URLs manually.

The pre-built images are intentionally minimal and do not include much of the additional software available in Garden Linux. You can use apt to search and install additional packages that are available for Garden Linux.

bash
# For the latest nightly build:
podman run --rm ghcr.io/gardenlinux/gardenlinux/lima:latest | limactl start --name gardenlinux -

# For a specific nightly build:
podman run --rm ghcr.io/gardenlinux/gardenlinux/lima:latest --version 2066.0.0 --allow-nightly | limactl start --name gardenlinux -

# For a release version:
podman run --rm ghcr.io/gardenlinux/gardenlinux/lima:latest --version <version> | limactl start --name gardenlinux -

Replace <version> with a specific Garden Linux release number (e.g., 2066.0.0).

TIP

The container generates a Lima YAML manifest with the correct image URL and all required configuration. You can redirect the output to a file for review or modification:

bash
podman run --rm ghcr.io/gardenlinux/gardenlinux/lima:latest > gardenlinux-manifest.yaml
cat gardenlinux-manifest.yaml | limactl start --name gardenlinux -

TIP

For a complete list of maintained releases and their support lifecycle, see the releases reference.

Build Your Own Images ​

To create custom Garden Linux images with additional features or configurations, see the Building Flavors guide.

Step 2: Connect to Your Instance ​

Once the VM has started, open a shell:

bash
limactl shell gardenlinux

Lima automatically provisions a user with sudo access and configures SSH for you. No manual SSH key setup or firmware configuration scripts are needed.

Step 3: Verify the Installation ​

Once connected, verify your Garden Linux installation with the following commands:

bash
# Check OS information
cat /etc/os-release

# Verify kernel version
uname -a

# Check system status
systemctl status

# View network configuration
ip addr show

Expected output from /etc/os-release should show:

NAME="Garden Linux"
VERSION="<version>"
ID=gardenlinux
...

Success Criteria ​

You have successfully completed this tutorial when:

  • Your Garden Linux virtual machine is running under Lima
  • You can open a shell via limactl shell gardenlinux
  • You can verify the Garden Linux version using cat /etc/os-release

Cleanup ​

When you're finished with the tutorial, stop and remove the VM:

bash
limactl stop gardenlinux
limactl delete gardenlinux

Next Steps ​

Now that you have a running Garden Linux instance on Lima, you can: