feat: containerd/nerdctl engine backend

[AaronFeledy]

Summary

Adds containerd + nerdctl + BuildKit as an alternative container engine backend. Lando can run independently of Docker with engine: "containerd" in config.

What

• Backend abstraction — DaemonBackend, ContainerBackend, ComposeBackend interfaces
• Docker backend — existing code wrapped as implementations, zero behavior changes
• Containerd backend — ContainerdDaemon (containerd + buildkitd + finch-daemon lifecycle), ContainerdContainer (nerdctl ops), NerdctlCompose (compose adapter)
• finch-daemon — Docker API compatibility socket for Traefik proxy
• Platform support — Linux/WSL2 native, macOS via Lima VM
• Setup UX — lando setup prompts for engine selection, downloads binaries from GitHub
• Doctor checks — binary/daemon/connectivity health checks
• Error messages — 9 user-friendly containerd-specific messages
• Perf tooling — timer utility, benchmark script, debug-mode perf logging

Config

engine: containerd  # or "docker" (default) or "auto"

Stats

72 files changed, ~10,000 lines added. 467 tests passing. No existing behavior changed — Docker path works exactly as before.

Not yet done

• Leia integration tests do not run against containerd in CI (default is auto → Docker)
• Needs a dedicated CI job with engine: containerd to exercise the backend end-to-end

---

Note

High Risk
Introduces a new container engine backend (containerd/nerdctl) and changes engine bootstrap/setup paths, which can impact core lifecycle, orchestration, and proxy behavior across platforms. Risk is mitigated by preserving the existing Docker codepath but the surface area is large and includes new daemon/process management.

Overview
Adds an experimental containerd engine option (and default engine: auto) that lets Lando run via containerd + buildkitd + nerdctl instead of Docker, including engine selection during lando setup and containerd-specific compatibility/health checks.

Replaces utils/setup-engine.js bootstrapping with a new BackendManager that instantiates either the Docker-backed engine or a new containerd-backed engine; the containerd path manages its own daemons, uses nerdctl compose for orchestration, and introduces a Docker-API compatibility socket (finch-daemon) to keep the Traefik proxy working.

Extends CI to run core Leia tests against both docker and containerd, adds engine documentation and developer benchmarking tooling (scripts/benchmark-engines.sh).

^{Written by Cursor Bugbot for commit 9f53c2d. This will update automatically on new commits. Configure here.}

[netlify]

✅ Deploy Preview for lando-core ready!

Name	Link
🔨 Latest commit	a1ce102
🔍 Latest deploy log	https://app.netlify.com/projects/lando-core/deploys/69b73e53fdd229000841b608
😎 Deploy Preview	https://deploy-preview-445--lando-core.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 87 (no change from production) Accessibility: 89 (no change from production) Best Practices: 92 (no change from production) SEO: 90 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[AaronFeledy]

@cursor review

[cursor]

Cursor Bugbot has reviewed your changes and found 4 potential issues.

Autofix Details

Bugbot Autofix prepared fixes for all 4 issues found in the latest run.

• ✅ Fixed: Compose wrapper missing default for opts parameter
  • Added || {} default to datum.opts in both Docker and containerd compose wrappers to match original setup-engine.js behavior.
• ✅ Fixed: Warning function ignores version info argument
  • Updated update-nerdctl-warning to accept and display version, update, and link parameters in the warning message.
• ✅ Fixed: Unbounded recursion in container list retry logic
  • Added _retryCount parameter with a limit of 10 retries to prevent stack overflow in containerd-container list method.
• ✅ Fixed: Containerd getVersions returns false causing semver.clean crash
  • Added filtering to remove false and 'skip' values from containerd versions before processing in getCompatibility.

Or push these changes by commenting:

@cursor push abd2ef0b38

Preview (abd2ef0b38)

diff --git a/lib/backend-manager.js b/lib/backend-manager.js
--- a/lib/backend-manager.js
+++ b/lib/backend-manager.js
@@ -54,7 +54,7 @@
    * Returns a fully wired `Engine` instance ready for use by `lando.engine`.
    *
    * @param {string} [id='lando'] - The Lando instance identifier.
-   * @returns {Engine} A configured Engine instance.
+   * @return {Engine} A configured Engine instance.
    */
   createEngine(id = 'lando') {
     const engineType = this.config.engine || 'auto';
@@ -80,7 +80,7 @@
    * - Returns `new Engine(daemon, docker, compose, config)`
    *
    * @param {string} id - The Lando instance identifier.
-   * @returns {Engine} A Docker-backed Engine instance.
+   * @return {Engine} A Docker-backed Engine instance.
    * @private
    */
   _createDockerEngine(id) {
@@ -104,7 +104,7 @@
     );
 
     const compose = (cmd, datum) => {
-      const run = dockerCompose[cmd](datum.compose, datum.project, datum.opts);
+      const run = dockerCompose[cmd](datum.compose, datum.project, datum.opts || {});
       return this.shell.sh([orchestratorBin].concat(run.cmd), run.opts);
     };
 
@@ -124,7 +124,7 @@
    * `{cmd, opts}` shell descriptor, then executes via `shell.sh([nerdctlBin, ...cmd], opts)`.
    *
    * @param {string} id - The Lando instance identifier.
-   * @returns {Engine} A containerd-backed Engine instance.
+   * @return {Engine} A containerd-backed Engine instance.
    * @private
    */
   _createContainerdEngine(id) {
@@ -171,7 +171,7 @@
     // as the Docker path. Gets {cmd, opts} from NerdctlCompose, then executes
     // via shell.sh([nerdctlBin, ...cmd], opts).
     const compose = (cmd, datum) => {
-      const run = nerdctlCompose[cmd](datum.compose, datum.project, datum.opts);
+      const run = nerdctlCompose[cmd](datum.compose, datum.project, datum.opts || {});
       return this.shell.sh([nerdctlBin].concat(run.cmd), run.opts);
     };
 
@@ -193,7 +193,7 @@
    * Logs which engine was selected.
    *
    * @param {string} id - The Lando instance identifier.
-   * @returns {Engine} An Engine instance using the auto-detected backend.
+   * @return {Engine} An Engine instance using the auto-detected backend.
    * @private
    */
   _createAutoEngine(id) {

diff --git a/lib/backends/containerd/containerd-container.js b/lib/backends/containerd/containerd-container.js
--- a/lib/backends/containerd/containerd-container.js
+++ b/lib/backends/containerd/containerd-container.js
@@ -15,7 +15,7 @@
  * Helper to determine if any file exists in an array of files.
  *
  * @param {Array<string>} files - Array of file paths to check.
- * @returns {boolean}
+ * @return {boolean}
  * @private
  */
 const srcExists = (files = []) => _.reduce(files, (exists, file) => fs.existsSync(file) || exists, false);
@@ -33,7 +33,7 @@
  * - Labels whose values contain `,` within values that also contain `=`
  *
  * @param {string|Object} labels - Labels string from nerdctl or object from inspect.
- * @returns {Object} Docker-compatible labels object.
+ * @return {Object} Docker-compatible labels object.
  * @private
  */
 const parseLabels = labels => {
@@ -91,7 +91,7 @@
  * - `Status`   → status text
  *
  * @param {Object} nerdctlContainer - A parsed JSON line from `nerdctl ps --format json`.
- * @returns {Object} Docker API-compatible container object.
+ * @return {Object} Docker API-compatible container object.
  * @private
  */
 const normalizeContainer = nerdctlContainer => {
@@ -164,7 +164,7 @@
    * "No such container", "no such object", "not found".
    *
    * @param {Error} err - The error to inspect.
-   * @returns {boolean} `true` if the error indicates a missing resource.
+   * @return {boolean} `true` if the error indicates a missing resource.
    * @private
    */
   _isNotFoundError(err) {
@@ -184,7 +184,7 @@
    * @param {Array<string>} args - nerdctl subcommand and arguments.
    * @param {Object} [opts={}] - Additional options passed to `run-command`.
    * @param {boolean} [opts.ignoreReturnCode=false] - Whether to suppress non-zero exit errors.
-   * @returns {Promise<string>} The trimmed stdout from the command.
+   * @return {Promise<string>} The trimmed stdout from the command.
    * @throws {Error} If the command exits non-zero and `ignoreReturnCode` is false.
    * @private
    */
@@ -216,7 +216,7 @@
    *
    * @param {string} name - The name of the network to create.
    * @param {Object} [opts={}] - Additional network creation options.
-   * @returns {Promise<Object>} Network inspect data.
+   * @return {Promise<Object>} Network inspect data.
    */
   async createNet(name, opts = {}) {
     const args = ['network', 'create'];
@@ -254,7 +254,7 @@
    * Docker-compatible JSON.
    *
    * @param {string} cid - A container identifier (hash, name, or short id).
-   * @returns {Promise<Object>} Container inspect data.
+   * @return {Promise<Object>} Container inspect data.
    * @throws {Error} If the container does not exist.
    */
   async scan(cid) {
@@ -270,7 +270,7 @@
    * to prevent race conditions when containers are removed between checks.
    *
    * @param {string} cid - A container identifier.
-   * @returns {Promise<boolean>}
+   * @return {Promise<boolean>}
    */
   async isRunning(cid) {
     try {
@@ -303,9 +303,10 @@
    * @param {string}  [options.project] - Filter to a specific project name.
    * @param {Array<string>} [options.filter] - Additional `key=value` filters.
    * @param {string}  [separator='_'] - Container name separator.
-   * @returns {Promise<Array<Object>>} Array of Lando container descriptors.
+   * @param {number}  [_retryCount=0] - Internal retry counter to prevent unbounded recursion.
+   * @return {Promise<Array<Object>>} Array of Lando container descriptors.
    */
-  async list(options = {}, separator = '_') {
+  async list(options = {}, separator = '_', _retryCount = 0) {
     // Get raw container list from nerdctl (JSONL: one JSON object per line)
     let rawOutput;
     try {
@@ -380,7 +381,10 @@
     // If any container has been up for only a brief moment, retry
     // (matches Landerode behavior to avoid transient states)
     if (_.find(containers, container => container.status === 'Up Less than a second')) {
-      return this.list(options, separator);
+      if (_retryCount < 10) {
+        return this.list(options, separator, _retryCount + 1);
+      }
+      this.debug('list retry limit reached, proceeding with transient container states');
     }
 
     // Add running status flag
@@ -401,7 +405,7 @@
    * @param {Object} [opts={v: true, force: false}] - Removal options.
    * @param {boolean} [opts.v=true] - Also remove associated anonymous volumes.
    * @param {boolean} [opts.force=false] - Force-remove a running container.
-   * @returns {Promise<void>}
+   * @return {Promise<void>}
    */
   async remove(cid, opts = {v: true, force: false}) {
     const args = ['rm'];
@@ -428,7 +432,7 @@
    *
    * @param {string} cid - A container identifier.
    * @param {Object} [opts={}] - Stop options (e.g. `{t: 10}` for timeout in seconds).
-   * @returns {Promise<void>}
+   * @return {Promise<void>}
    */
   async stop(cid, opts = {}) {
     const args = ['stop'];
@@ -458,7 +462,7 @@
    * handle interface.
    *
    * @param {string} id - The network id or name.
-   * @returns {Object} A network handle with `inspect()` and `remove()` methods.
+   * @return {Object} A network handle with `inspect()` and `remove()` methods.
    */
   getNetwork(id) {
     return {
@@ -467,7 +471,7 @@
 
       /**
        * Inspect the network and return its metadata.
-       * @returns {Promise<Object>} Network inspect data.
+       * @return {Promise<Object>} Network inspect data.
        */
       inspect: async () => {
         const data = await this._nerdctl(['network', 'inspect', id]);
@@ -477,7 +481,7 @@
 
       /**
        * Remove the network.
-       * @returns {Promise<void>}
+       * @return {Promise<void>}
        */
       remove: async () => {
         try {
@@ -498,7 +502,7 @@
    *
    * @param {Object} [opts={}] - Filter options.
    * @param {Object} [opts.filters] - Filters object (e.g. `{name: ['mynet']}` or `{id: ['abc']}`).
-   * @returns {Promise<Array<Object>>} Array of network objects.
+   * @return {Promise<Array<Object>>} Array of network objects.
    */
   async listNetworks(opts = {}) {
     let rawOutput;
@@ -565,7 +569,7 @@
    * Dockerode Container handle interface.
    *
    * @param {string} cid - The container id or name.
-   * @returns {Object} A container handle with `inspect()`, `remove()`, and `stop()` methods.
+   * @return {Object} A container handle with `inspect()`, `remove()`, and `stop()` methods.
    */
   getContainer(cid) {
     return {
@@ -574,21 +578,21 @@
 
       /**
        * Inspect the container and return its metadata.
-       * @returns {Promise<Object>} Container inspect data.
+       * @return {Promise<Object>} Container inspect data.
        */
       inspect: () => this.scan(cid),
 
       /**
        * Remove the container.
        * @param {Object} [opts] - Removal options.
-       * @returns {Promise<void>}
+       * @return {Promise<void>}
        */
       remove: opts => this.remove(cid, opts),
 
       /**
        * Stop the container.
        * @param {Object} [opts] - Stop options.
-       * @returns {Promise<void>}
+       * @return {Promise<void>}
        */
       stop: opts => this.stop(cid, opts),
     };

diff --git a/lib/engine.js b/lib/engine.js
--- a/lib/engine.js
+++ b/lib/engine.js
@@ -194,7 +194,7 @@
     const semver = require('semver');
 
     // helper to normalize a supported versions object into comparison-ready format
-    const normalize = (sv) => _(sv)
+    const normalize = sv => _(sv)
       .map((data, name) => _.merge({}, data, {name}))
       .map(data => ([data.name, {
         satisfies: data.satisfies || `${data.min} - ${data.max}`,
@@ -207,12 +207,19 @@
 
     return this.daemon.getVersions().then(versions => {
       // Detect containerd backend: versions have containerd key instead of desktop/engine
-      const isContainerd = versions.hasOwnProperty('containerd');
+      const isContainerd = Object.prototype.hasOwnProperty.call(versions, 'containerd');
 
       let normalizedVersions;
       if (isContainerd) {
         // containerd format: {containerd, buildkit, nerdctl}
         normalizedVersions = normalize(this.supportedContainerdVersions);
+
+        // Remove false values (binaries that couldn't be versioned)
+        Object.keys(versions).forEach(key => {
+          if (versions[key] === false || versions[key] === 'skip') {
+            delete versions[key];
+          }
+        });
       } else {
         // Docker format: {desktop, engine, compose}
         normalizedVersions = normalize(supportedVersions);

diff --git a/messages/update-nerdctl-warning.js b/messages/update-nerdctl-warning.js
--- a/messages/update-nerdctl-warning.js
+++ b/messages/update-nerdctl-warning.js
@@ -1,13 +1,14 @@
 'use strict';
 
 // checks to see if a setting is disabled
-module.exports = () => ({
+module.exports = ({version, update, link} = {}) => ({
   type: 'warning',
   title: 'Recommend updating NERDCTL',
   detail: [
-    'Looks like you might be falling a bit behind on nerdctl.',
+    `You have version ${version || 'unknown'} but we recommend updating to ${update || 'the latest version'}.`,
     'In order to ensure the best stability and support we recommend you update',
     'by running the hidden "lando setup" command.',
   ],
   command: 'lando setup --skip-common-plugins',
+  url: link,
 });