Getting Started

Getting Started

Prerequisites

By default, builds run inside a Lima VM, which works on both macOS and Linux. On Linux, builds can alternatively run natively in a Nix shell.

Lima (default)

Install Lima by following the instructions at https://lima-vm.io/docs/installation/.

No further setup is needed. The first make build invocation creates a Lima VM named tee-builder-<hash> for this repo, installs the build dependencies inside it, and runs mkosi there. Builds from macOS and Linux hosts produce the same image bit-for-bit.

The default Lima VM is provisioned with 6 CPUs, 12 GiB of memory, and a 100 GiB maximum disk size. To override these before the VM is created, you can set the allocated resources with environment variables like so:

LIMA_CPUS=4 LIMA_MEMORY=8GiB LIMA_DISK=50GiB make build IMAGE=example

These variables only apply at VM creation time. To resize an existing VM, run make clean first to delete it, then rebuild.

The ID of the Lima VM is based on the repository path, so multiple copies of this repo can simultaneously coexist on one machine.

Nix (Linux only)

Alternatively, to build natively on Linux:

1. Install Nix (not NixOS) from https://nixos.org/download/.
2. Enable the flakes and nix-command experimental features.
3. Create an empty .bypass-lima file in the repo root.

Subsequent make commands will use the Nix dev shell directly.

Building the example image

Easy-TEE includes a sample image called example to use as a starting point.

1. Set up the example image

Use the provided template to create a top-level configuration file:

cp images/example.conf.template images/example.conf

Then, open images/example.conf and set a Debian repository snapshot timestamp. This timestamp freezes all image dependencies to the latest versions available on the Debian package repository at that time.

For example, at the time of writing this page, the latest Debian snapshot is:

[Distribution]
Snapshot=20260513T202732Z

To find the latest snapshot, visit https://snapshot.debian.org/archive/debian/ and click the link at the bottom of the page corresponding with the current month of the current year. Then, scroll down to bottom of the page and right click the last timestamp link, clicking "Copy Link". Now, a URL that looks something like https://snapshot.debian.org/archive/debian/20260513T202732Z/ will be copied to your clipboard. The last section of this URL (leading up to, but not including the final slash) is the latest Debian archive timestamp.

In the future, if you would like to update your image beyond the software available in this timestamp, you'll need to update this value.

2. Build the example image

make build IMAGE=example

The first build downloads the necessary packages from the pinned Debian snapshot, compiles the Linux kernel from source, and assembles the image. It typically takes 15–30 minutes depending on hardware and network speed. Later builds reuse cached artifacts and complete much faster.

3. Build outputs

All build output goes to the build/ directory.

Outputs from the latest build are symlinked to build/latest.*. The most relevant files are:

• latest.efi for the raw VM image file (used for self-hosted deployments and emulation)
• latest.tar.gz for a GCP-compatible image file
• latest.vhd for a Microsoft Azure image file
• latest.manifest for a list of all Debian packages included in the image

The efi, tar.gz, and vhd files all contain the full VM image, including the filesystem, kernel, and bootloader. No other files are required to boot the image.

4. Measuring the image

The latest.efi file produced by the build command can be reproduced exactly (bit-for-bit) by anyone as long as they have the exact same source repository. Then, by using the attest command, anyone can verify that a deployed instance is running this exact image.

What's next

• Add your own software, services, and configuration: Creating a Module.
• The layout of this repository: Repository Layout.
• Deploy your image to a cloud or hardware target: Deployment Guide.