@localctl/cli 0.4.2 → 0.5.0-beta.2

package/README.md

@@ -73,14 +73,15 @@ JSON file per app.
 
 | Requirement | Notes |
 |---|---|
-| **macOS** or **Windows** | Windows commands run in PowerShell. |
+| **macOS**, **Windows** or **Linux** | Windows commands run in PowerShell. Linux support is [experimental](#linux-experimental). |
 | **Node.js 18+** | Needed to install the CLI from npm. |
 | **Container engine** | [Podman Desktop](https://podman-desktop.io/) (or Docker Desktop / Rancher Desktop), running. See [supported container engines](#supported-container-engines). |
-| **Homebrew** or **winget** | Used once by `localctl setup` to install missing tools. |
+| **Homebrew** (macOS) or **winget** (Windows) | Used once by `localctl setup` to install missing tools. Linux needs only `curl`. |
 
 `localctl setup` installs `k3d`, `kubectl`, `tilt`, `mkcert` and `helm` for you if they're missing.
 On Windows, Tilt isn't on winget, so it's downloaded from its GitHub release into
-`~.localctl	ools` and added to your user PATH.
+`~\.localctl\tools` and added to your user PATH. On Linux, all five tools are downloaded as
+official release binaries into `~/.localctl/tools` (no sudo, no distro packages).
 
 ### Supported container engines
 
@@ -89,12 +90,63 @@ On Windows, Tilt isn't on winget, so it's downloaded from its GitHub release int
 | [Podman Desktop](https://podman-desktop.io/) | ✅ Tested |
 | [Docker Desktop](https://www.docker.com/products/docker-desktop/) | 🧪 Experimental — setup and app deploy verified on Windows |
 | [Rancher Desktop](https://rancherdesktop.io/) | 🧪 Experimental — not yet tested |
+| Docker Engine / native Podman (Linux) | 🧪 Experimental — see [Linux](#linux-experimental) |
 
 Experimental engines are detected and should work, since k3d only needs a Docker-compatible API,
 but they haven't been through a full test cycle yet. `localctl setup` and `localctl doctor` print
 a warning when one is in use. If you try one, please
 [report how it went](https://github.com/psilvmoreira/localctl/issues/new).
 
+### Required tools
+
+What has to be on your machine **before** `localctl setup`, and what `setup` installs for you:
+
+| | You install | `localctl setup` installs |
+|---|---|---|
+| **All platforms** | **Node.js 18+** (to install and run the CLI), a **container engine** | `k3d`, `kubectl`, `tilt`, `mkcert`, `helm` |
+| **macOS** | [Homebrew](https://brew.sh) | via `brew` (plus `nss` for Firefox, optional) |
+| **Windows** | `winget` (ships with Windows) | via `winget`, Tilt from its GitHub release |
+| **Linux** | `curl` and `tar`, `sudo` (hosts file, CA trust) | downloaded as release binaries into `~/.localctl/tools` |
+
+`localctl setup` needs administrator rights once, for the `*.local.test` hosts entry and the local
+CA trust.
+
+### Linux (experimental)
+
+Linux support is **experimental**: it hasn't been through a full test cycle (CI only runs the
+smoke tests there), and `setup`/`doctor` print a warning. It's published on the `beta` dist-tag:
+
+```sh
+npm install -g @localctl/cli@beta
+```
+
+Targeted distributions, all with systemd and a mkcert-supported trust store:
+
+| Family | Distributions | Docker Engine install |
+|---|---|---|
+| Debian | Ubuntu, Debian, Linux Mint, Pop!_OS | `localctl setup --install-docker` (Docker's official script) |
+| Red Hat | Fedora, RHEL, Rocky, AlmaLinux, CentOS Stream | `localctl setup --install-docker` (Docker's official script) |
+| Arch | Arch, Manjaro, EndeavourOS | `localctl setup --install-docker` (`pacman`) |
+| SUSE | openSUSE Leap/Tumbleweed | `localctl setup --install-docker` (`zypper`) |
+
+Other distributions (Alpine, Void, Gentoo, NixOS, immutable/atomic desktops) may work if you
+bring Docker (or Podman) and Node.js yourself, but aren't targeted. WSL needs the Windows hosts
+file edited too.
+
+What's different on Linux:
+
+- **Docker Engine** is the recommended engine (root daemon, nothing else to configure). If none is
+  running, `localctl setup --install-docker` installs it for the families above. It needs `sudo`,
+  and you must **log out and back in** afterwards so your user joins the `docker` group.
+- **Podman** runs natively, no VM. The insecure-registry entry goes in
+  `~/.config/containers/registries.conf.d/` (no sudo, no restart). k3d needs Podman's API socket:
+  `systemctl --user enable --now podman.socket`. Rootless Podman also can't bind :80/:443 by
+  default: `sudo sysctl net.ipv4.ip_unprivileged_port_start=80`.
+- **Firefox/Chromium trust** needs `certutil` (`libnss3-tools` on Debian/Ubuntu, `nss-tools` on
+  Fedora). `setup` prints the command for your distro; install it and re-run `mkcert -install`.
+
+Hit a problem? [Open an issue](https://github.com/psilvmoreira/localctl/issues/new).
+
 ## Installation
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localctl/cli",
-  "version": "0.4.2",
+  "version": "0.5.0-beta.2",
   "description": "localctl - local Kubernetes dev platform CLI",
   "keywords": [
     "kubernetes",
@@ -36,7 +36,9 @@
     "sync-assets": "node scripts/sync-assets.js",
     "prepack": "node scripts/sync-assets.js",
     "test": "node scripts/smoke-test.js",
-    "test:pack": "node scripts/pack-test.js"
+    "test:pack": "node scripts/pack-test.js",
+    "test:e2e": "node scripts/e2e/run.js",
+    "test:e2e:distros": "node scripts/e2e/distros.js"
   },
   "dependencies": {
     "chalk": "^4.1.2",
@@ -48,6 +50,11 @@
     "node": ">=18"
   },
   "localctl": {
+    "platforms": {
+      "darwin": "tested",
+      "win32": "tested",
+      "linux": "experimental"
+    },
     "containerEngines": {
       "podman": "tested",
       "docker": "experimental",

package/src/commands/doctor.js

@@ -1,5 +1,7 @@
 const { commandExists, capture } = require('../lib/exec');
-const { detectEngine, warnIfExperimental } = require('../lib/engine');
+const { detectEngine, warnIfExperimental, warnIfExperimentalPlatform } = require('../lib/engine');
+const { ensurePodmanSocket, blockedPrivilegedPorts, engineMemoryMb } = require('../lib/podman');
+const { DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT } = require('../lib/constants');
 const { getActive, clusterNameFor } = require('../lib/profileStore');
 const ui = require('../lib/ui');
 const logger = require('../lib/logger');
@@ -21,6 +23,7 @@ module.exports = (program) => {
     .description('Check the local environment for missing/broken pieces')
     .action(() => {
       logger.step('Checking environment...');
+      warnIfExperimentalPlatform();
       const detected = detectEngine();
       check(`container engine available${detected ? ` (${detected.engine})` : ''}`, () => Boolean(detected));
       if (detected) warnIfExperimental(detected.engine);
@@ -38,6 +41,18 @@ module.exports = (program) => {
         const res = capture('k3d', ['cluster', 'list']);
         return res.stdout.split('\n').some((line) => line.trim().split(/\s+/)[0] === activeCluster);
       });
+      if (process.platform === 'linux' && detected && detected.engine === 'podman') {
+        check('podman API socket available (needed by k3d)', () => ensurePodmanSocket() === null);
+        check('rootless podman can bind :80/:443', () => blockedPrivilegedPorts([DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT]).length === 0);
+      }
+      if (detected) {
+        // One k3s cluster idles around 0.6-0.7 GB, and apps/addons come on top. Below ~3 GB the
+        // engine's VM starts swapping and the API server times out.
+        const mb = engineMemoryMb(detected.bin);
+        if (mb !== null) {
+          check(`engine has at least 3 GB of memory (${(mb / 1024).toFixed(1)} GB available)`, () => mb >= 3000);
+        }
+      }
       check('kubectl context reachable', () => capture('kubectl', ['cluster-info']).status === 0);
       logger.step(`Fix any ${ui.cross} above, or run "localctl setup" (or "localctl profiles switch ${active}" for a non-default project) to (re)install/repair.`);
     });

package/src/commands/setup.js

@@ -3,8 +3,17 @@ const { syncHosts } = require('../lib/hostsFile');
 const { setActive } = require('../lib/profileStore');
 const { DEFAULT_CLUSTER_NAME, DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT, DOMAIN, REGISTRY_HOST_PORT } = require('../lib/constants');
 const logger = require('../lib/logger');
+const { detectEngine } = require('../lib/engine');
+const { installDocker } = require('../lib/linuxDistro');
 
-function setup() {
+function setup(opts) {
+  if (opts.installDocker) {
+    if (process.platform !== 'linux') {
+      throw new Error('--install-docker is only available on Linux. Install Docker Desktop or Podman Desktop instead.');
+    }
+    if (detectEngine()) logger.success('A container engine is already running, nothing to install');
+    else installDocker();
+  }
   provisionCluster({
     clusterName: DEFAULT_CLUSTER_NAME,
     httpPort: DEFAULT_HTTP_PORT,
@@ -32,5 +41,6 @@ module.exports = (program) => {
   program
     .command('setup')
     .description('One-click local infra setup for the default project: container engine, tools, k3d cluster, TLS, hosts')
+    .option('--install-docker', 'Linux only: install Docker Engine first if no container engine is running (needs sudo)')
     .action(setup);
 };

package/src/commands/uninstall.js

@@ -1,4 +1,3 @@
-const os = require('os');
 const fs = require('fs');
 const path = require('path');
 const { isRunning } = require('../lib/exec');
@@ -8,7 +7,7 @@ const { teardownInsecureRegistry } = require('../lib/podman');
 const { clearHosts } = require('../lib/hostsFile');
 const { listProfiles } = require('../lib/profileStore');
 const { confirm } = require('../lib/prompt');
-const { RUN_DIR, PROFILES_PATH } = require('../lib/paths');
+const { RUN_DIR, PROFILES_PATH, CERTS_DIR, APPS_REGISTRY_PATH } = require('../lib/paths');
 const logger = require('../lib/logger');
 
 // Every Main (cluster-isolation) project this machine knows about - each one owns a real,
@@ -24,7 +23,7 @@ async function uninstall(opts) {
   console.log('This will remove everything "localctl setup"/"localctl profiles" set up:');
   console.log(`  - Every project's k3d cluster (${projects.map((p) => p.cluster).join(', ')}) and everything deployed in them`);
   console.log('  - Their local image registry containers');
-  console.log('  - Podman VM insecure-registry config (Podman only, if present)');
+  console.log('  - Podman insecure-registry config (Podman only, if present)');
   console.log('  - The *.local.test block in your hosts file');
   console.log('  - Any background dev loop `localctl app up` left running, and its state');
   console.log('  - ~/.localctl/certs, the app registry state, and the project registry (~/.localctl/profiles.json)');
@@ -80,8 +79,8 @@ async function uninstall(opts) {
     fs.rmSync(RUN_DIR, { recursive: true, force: true });
   }
 
-  const certsDir = path.join(os.homedir(), '.localctl', 'certs');
-  const appsRegistry = path.join(os.homedir(), '.localctl', 'apps.json');
+  const certsDir = CERTS_DIR;
+  const appsRegistry = APPS_REGISTRY_PATH;
   if (fs.existsSync(certsDir)) fs.rmSync(certsDir, { recursive: true, force: true });
   if (fs.existsSync(appsRegistry)) fs.rmSync(appsRegistry, { force: true });
   if (fs.existsSync(PROFILES_PATH)) fs.rmSync(PROFILES_PATH, { force: true });
@@ -94,6 +93,8 @@ async function uninstall(opts) {
   if (process.platform === 'win32') {
     console.log('  winget uninstall k3d.k3d Kubernetes.kubectl FiloSottile.mkcert Helm.Helm   # only if nothing else needs them');
     console.log('  Remove-Item -Recurse -Force ~\\.localctl\\tools   # tilt, if localctl installed it');
+  } else if (process.platform === 'linux') {
+    console.log('  rm -rf ~/.localctl/tools   # k3d, kubectl, tilt, mkcert and helm, if localctl installed them');
   } else {
     console.log('  brew uninstall k3d kubectl tilt mkcert helm   # only if nothing else needs them');
   }

package/src/lib/addonDirs.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { HOME_STATE_DIR } = require('./paths');
 
 // Addons are searched in two places, in precedence order:
 //   1. USER_DIR   - yours, never touched by a `localctl` update/reinstall. Defaults to
@@ -11,7 +12,7 @@ const path = require('path');
 // This is what lets someone install this tool without inheriting its author's addon set, and
 // without forking the tool to add their own - see docs/adding-tools.md.
 const BUILTIN_DIR = path.join(__dirname, 'addons');
-const USER_DIR = process.env.LOCALCTL_ADDONS_DIR || path.join(os.homedir(), '.localctl', 'addons');
+const USER_DIR = process.env.LOCALCTL_ADDONS_DIR || path.join(HOME_STATE_DIR, 'addons');
 
 function roots(...segments) {
   return [path.join(USER_DIR, ...segments), path.join(BUILTIN_DIR, ...segments)];

package/src/lib/clusterProvision.js

@@ -3,11 +3,13 @@ const fs = require('fs');
 const path = require('path');
 const yaml = require('js-yaml');
 const { run, capture, sleepSync, commandExists } = require('./exec');
-const { detectEngine, warnIfExperimental } = require('./engine');
-const { installIfMissing, installTiltWindows } = require('./toolInstall');
-const { ensureInsecureRegistry } = require('./podman');
+const { detectEngine, warnIfExperimental, warnIfExperimentalPlatform } = require('./engine');
+const { installIfMissing, installTiltWindows, nssInstallHint } = require('./toolInstall');
+const { ensureInsecureRegistry, ensurePodmanSocket, blockedPrivilegedPorts } = require('./podman');
 const { DOMAIN } = require('./constants');
 const logger = require('./logger');
+const { CERTS_DIR } = require('./paths');
+const { detectDistro, dockerInstallSteps } = require('./linuxDistro');
 
 // Cluster-level manifests: bundled under cli/assets/ in the npm package (copied there by
 // scripts/sync-assets.js at pack time), or read straight from the repo root in a git checkout.
@@ -16,6 +18,15 @@ const MANIFESTS_DIR = fs.existsSync(BUNDLED_MANIFESTS_DIR)
   ? BUNDLED_MANIFESTS_DIR
   : path.resolve(__dirname, '..', '..', '..', 'cluster', 'manifests');
 
+function isWsl() {
+  if (process.platform !== 'linux') return false;
+  try {
+    return /microsoft/i.test(fs.readFileSync('/proc/version', 'utf8'));
+  } catch (e) {
+    return false;
+  }
+}
+
 function registryNameFor(clusterName) {
   return `${clusterName}-registry`;
 }
@@ -27,16 +38,163 @@ function clusterExists(clusterName) {
     .includes(clusterName);
 }
 
+// k3d writes the API server as https://0.0.0.0:<port> into kubeconfig. Linux and Windows treat
+// 0.0.0.0 as "this host", but macOS refuses to connect to it ("can't assign requested address"),
+// so every kubectl call fails. Selects the cluster's context and points it at 127.0.0.1 instead,
+// which also repairs clusters created before this fix.
+function useClusterContext(clusterName) {
+  const context = `k3d-${clusterName}`;
+  // The cluster can exist while this kubeconfig knows nothing about it (a deleted or replaced
+  // ~/.kube/config, a different KUBECONFIG): ask k3d to write it back instead of failing.
+  const known = capture('kubectl', ['config', 'get-contexts', '-o', 'name']).stdout.split('\n');
+  if (!known.includes(context)) {
+    run('k3d', ['kubeconfig', 'merge', clusterName, '--kubeconfig-merge-default'], { stdio: 'ignore', allowFail: true });
+  }
+  run('kubectl', ['config', 'use-context', context], { stdio: 'ignore' });
+  const server = capture('kubectl', [
+    'config', 'view', '--minify', '-o', 'jsonpath={.clusters[0].cluster.server}',
+  ]).stdout;
+  if (server.includes('//0.0.0.0:')) {
+    run('kubectl', [
+      'config', 'set-cluster', context, `--server=${server.replace('//0.0.0.0:', '//127.0.0.1:')}`,
+    ], { stdio: 'ignore' });
+  }
+}
+
+// Generated fresh per call, not a static file: every Main project needs its own cluster name,
+// ports, and registry mirror name baked in.
+function buildK3dConfig({ clusterName, httpPort, httpsPort, registryName }) {
+  return {
+    apiVersion: 'k3d.io/v1alpha5',
+    kind: 'Simple',
+    metadata: { name: clusterName },
+    servers: 1,
+    agents: 0,
+    ports: [
+      { port: `${httpPort}:80`, nodeFilters: ['loadbalancer'] },
+      { port: `${httpsPort}:443`, nodeFilters: ['loadbalancer'] },
+    ],
+    options: {
+      k3s: {
+        // metrics-server only feeds `kubectl top` and HPAs, which a local dev loop doesn't use;
+        // dropping it saves memory. servicelb must stay: it's what opens :80/:443 on the node for
+        // Traefik's LoadBalancer Service, so disabling it would break every ingress.
+        extraArgs: [{ arg: '--disable=metrics-server', nodeFilters: ['server:*'] }],
+      },
+    },
+    // Plain container + mirror config, not k3d's built-in `registries.create`: that hard-codes
+    // attaching to a network literally named "bridge", which Docker has by default but Podman
+    // does not, breaking cluster creation there.
+    registries: {
+      config: yaml.dump({ mirrors: { [`${registryName}:5000`]: { endpoint: [`http://${registryName}:5000`] } } }),
+    },
+  };
+}
+
+// Right after a (re)start the load balancer can accept connections before the API server is
+// answering (EOF / connection refused), so wait for it before the first real kubectl call.
+// Also after an engine restart the server container can get a new IP while the load balancer
+// (nginx, resolves upstreams only at startup) keeps the old one, so the API never answers;
+// restarting the load balancer once re-resolves it. Returns true once the API is ready.
+function waitForClusterApi(engineBin, clusterName, { attempts = 60, quiet = false } = {}) {
+  if (!quiet) logger.step('Waiting for the Kubernetes API...');
+  let lbRestarted = false;
+  for (let i = 0; i < attempts; i += 1) {
+    if (capture('kubectl', ['get', '--raw', '/readyz']).status === 0) return true;
+    if (i === 5 && !lbRestarted) {
+      lbRestarted = true;
+      run(engineBin, ['restart', `k3d-${clusterName}-serverlb`], { stdio: 'ignore', allowFail: true });
+    }
+    sleepSync(2000);
+  }
+  return false;
+}
+
+// k3d's --wait only waits for node readiness, not for Traefik's helm-install job to finish
+// registering its CRDs, so applying TLSStore any earlier races and fails intermittently. On a slow
+// machine (first image pulls, a nested engine) that takes minutes, so poll for the CRD to be
+// *Established* instead of giving up after one fixed wait, and say why if it never is.
+function waitForTraefikCrds(attempts = 150) {
+  logger.step('Waiting for Traefik CRDs...');
+  let last = 'not found yet';
+  for (let i = 0; i < attempts; i += 1) {
+    const r = capture('kubectl', [
+      'get', 'crd', 'tlsstores.traefik.io',
+      '-o', 'jsonpath={.status.conditions[?(@.type=="Established")].status}',
+    ]);
+    if (r.status === 0 && r.stdout === 'True') return;
+    last = r.status === 0 ? `Established=${r.stdout || 'unknown'}` : (r.stderr.split('\n')[0] || 'not found yet');
+    sleepSync(2000);
+  }
+  throw new Error(
+    `Traefik's CRDs (tlsstores.traefik.io) were not ready after ${Math.round((attempts * 2) / 60)} minutes (${last}). ` +
+    'Check "kubectl -n kube-system get pods" - the traefik helm-install jobs are probably still pulling images.',
+  );
+}
+
+// The CRDs existing does not mean Traefik is serving: on a slow machine its pod can still be
+// starting minutes later, and an app deployed in that window answers with a dropped connection.
+// Waiting here makes "cluster ready" mean the ingress actually accepts traffic.
+function waitForTraefik(attempts = 150) {
+  logger.step('Waiting for Traefik to accept traffic...');
+  for (let i = 0; i < attempts; i += 1) {
+    if (capture('kubectl', ['get', 'deployment', 'traefik', '-n', 'kube-system']).status === 0) break;
+    sleepSync(2000);
+  }
+  const res = capture('kubectl', ['rollout', 'status', 'deployment/traefik', '-n', 'kube-system', '--timeout=300s']);
+  if (res.status !== 0) {
+    throw new Error(
+      `Traefik did not become ready in 5 minutes (${(res.stderr || res.stdout).split('\n')[0]}). ` +
+      'Check "kubectl -n kube-system get pods".',
+    );
+  }
+}
+
+// A CRD can be Established a moment before the API server's discovery serves it, which surfaces as
+// "no matches for kind". Retrying the apply covers that window.
+function applyWithRetry(file, attempts = 15) {
+  let res;
+  for (let i = 0; i < attempts; i += 1) {
+    res = capture('kubectl', ['apply', '-f', file]);
+    if (res.status === 0) {
+      if (res.stdout) console.log(res.stdout);
+      return;
+    }
+    sleepSync(2000);
+  }
+  throw new Error(`kubectl apply -f ${path.basename(file)} failed after ${attempts} attempts: ${res.stderr}`);
+}
+
 // Brings up (idempotently) one Main project's cluster: container engine + tool checks, the k3d
 // cluster itself (own ports, since two clusters can't both bind host :80/:443), its own local
 // registry container, and the shared *.local.test TLS cert wired into its Traefik. Used by both
 // `localctl setup` (the "default" profile, unchanged ports/names from before multi-project
 // support) and `localctl profiles new`/`switch` (any other Main project).
 function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
+  warnIfExperimentalPlatform();
+  if (isWsl()) {
+    logger.warn('WSL detected: browsers on Windows read C:\\Windows\\System32\\drivers\\etc\\hosts, not this distro\'s /etc/hosts, and WSL may regenerate /etc/hosts on restart. Add the *.local.test entries to the Windows hosts file too (localctl prints them), or run localctl from Windows instead.');
+  }
   logger.step('Detecting container engine...');
   const detected = detectEngine();
   if (!detected) {
-    throw new Error('No running container engine found. Start Docker Desktop, Podman, or Rancher Desktop and re-run.');
+    let linuxHint = '';
+    if (process.platform === 'linux') {
+      if (commandExists('docker') || commandExists('podman')) {
+        // Installed but not usable: reinstalling won't help, the daemon or permissions are the issue.
+        linuxHint = '\nA container engine is installed but not responding. Start the service' +
+          ' (`sudo systemctl enable --now docker`, or `systemctl --user enable --now podman.socket` for Podman;' +
+          ' without systemd, start `dockerd` yourself) and make sure your user can reach it' +
+          ' (member of the "docker" group, then log out and in).';
+      } else {
+        const { family, id } = detectDistro();
+        const steps = dockerInstallSteps(family, id);
+        linuxHint = steps
+          ? `\nTo install Docker Engine, run "localctl setup --install-docker", or by hand:\n  ${steps.join('\n  ')}`
+          : '\nInstall Docker Engine for your distro: https://docs.docker.com/engine/install/';
+      }
+    }
+    throw new Error(`No running container engine found. Start Docker Desktop, Podman, or Rancher Desktop and re-run.${linuxHint}`);
   }
   const { engine, bin: engineBin } = detected;
   logger.success(`Using container engine: ${engine} (${engineBin} CLI)`);
@@ -47,6 +205,14 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
   // exist, but re-running it per registry port is cheap and idempotent.
   if (engine === 'podman') {
     ensureInsecureRegistry(registryPort);
+    if (process.platform === 'linux') {
+      const socketProblem = ensurePodmanSocket();
+      if (socketProblem) logger.warn(socketProblem);
+      const blocked = blockedPrivilegedPorts([httpPort, httpsPort]);
+      if (blocked.length) {
+        logger.warn(`Rootless Podman can't bind host port(s) ${blocked.join(', ')}. Allow it with: sudo sysctl net.ipv4.ip_unprivileged_port_start=80 (add it to /etc/sysctl.d/ to persist).`);
+      }
+    }
   }
 
   installIfMissing('k3d', 'k3d', 'k3d.k3d');
@@ -54,39 +220,53 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
   installIfMissing('tilt', 'tilt', installTiltWindows);
   installIfMissing('mkcert', 'mkcert', 'FiloSottile.mkcert');
   installIfMissing('helm', 'helm', 'Helm.Helm');
+  // mkcert can only add its CA to Firefox's trust store when NSS's certutil is present. It's
+  // optional (Safari/Chrome don't need it), so a failed or impossible install - e.g. no Homebrew -
+  // only warns. macOS installs it automatically; Linux needs sudo, so it only prints the command.
+  if (!commandExists('certutil')) {
+    if (process.platform === 'darwin') {
+      if (commandExists('brew')) {
+        try {
+          installIfMissing('certutil', 'nss');
+        } catch (e) {
+          logger.warn(`Couldn't install nss (${e.message}). Firefox won't trust the local CA until you run "brew install nss && mkcert -install".`);
+        }
+      } else {
+        logger.warn('Homebrew not found, skipping nss. Firefox won\'t trust the local CA until certutil is installed and "mkcert -install" is re-run.');
+        logger.info('Tip: install Homebrew (https://brew.sh) so localctl can install missing tools for you, then run "brew install nss".');
+      }
+    } else if (process.platform === 'linux') {
+      logger.warn(`certutil not found, so Firefox/Chromium won't trust the local CA. Install it with: ${nssInstallHint()} - then re-run "mkcert -install".`);
+    }
+  }
 
   const registryName = registryNameFor(clusterName);
 
   if (clusterExists(clusterName)) {
     logger.success(`k3d cluster '${clusterName}' already exists`);
+    // A reboot or engine restart leaves the cluster stopped; `start` is a no-op when it's running.
+    run('k3d', ['cluster', 'start', clusterName, '--wait'], { stdio: 'ignore', allowFail: true });
   } else {
     logger.step(`Creating k3d cluster '${clusterName}'...`);
-    // Generated fresh per call, not a static file: every Main project needs its own cluster
-    // name, ports, and registry mirror name baked in.
-    const k3dConfig = {
-      apiVersion: 'k3d.io/v1alpha5',
-      kind: 'Simple',
-      metadata: { name: clusterName },
-      servers: 1,
-      agents: 0,
-      ports: [
-        { port: `${httpPort}:80`, nodeFilters: ['loadbalancer'] },
-        { port: `${httpsPort}:443`, nodeFilters: ['loadbalancer'] },
-      ],
-      // Plain container + mirror config, not k3d's built-in `registries.create`: that hard-codes
-      // attaching to a network literally named "bridge", which Docker has by default but Podman
-      // does not, breaking cluster creation there.
-      registries: {
-        config: yaml.dump({ mirrors: { [`${registryName}:5000`]: { endpoint: [`http://${registryName}:5000`] } } }),
-      },
-    };
+    const k3dConfig = buildK3dConfig({ clusterName, httpPort, httpsPort, registryName });
     const tmpConfig = path.join(os.tmpdir(), `localctl-k3d-config-${clusterName}.yaml`);
     fs.writeFileSync(tmpConfig, yaml.dump(k3dConfig));
     run('k3d', ['cluster', 'create', '--config', tmpConfig, '--wait']);
     fs.rmSync(tmpConfig, { force: true });
     logger.success('Cluster created');
   }
-  run('kubectl', ['config', 'use-context', `k3d-${clusterName}`], { stdio: 'ignore' });
+  useClusterContext(clusterName);
+
+  // Up to ~5 minutes: k3s can exit once during start-up (a known race between its cloud controller
+  // and RBAC bootstrap) and is restarted by the engine, which a 2-minute wait would not outlast on
+  // a slow machine. If it never answers, stop here with the reason instead of failing later on an
+  // unrelated "EOF" from kubectl apply.
+  if (!waitForClusterApi(engineBin, clusterName, { attempts: 150 })) {
+    throw new Error(
+      `The Kubernetes API of cluster '${clusterName}' did not become ready in 5 minutes. ` +
+      `See why with: ${engineBin} logs --tail 50 k3d-${clusterName}-server-0`,
+    );
+  }
 
   const registryNetwork = `k3d-${clusterName}`;
   const existingNames = capture(engineBin, ['ps', '-a', '--format', '{{.Names}}']).stdout.split('\n');
@@ -110,7 +290,7 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
   // domain everywhere; only the namespace/subdomain prefix or the cluster differs).
   logger.step(`Setting up local TLS for *.${DOMAIN}...`);
   run('mkcert', ['-install']);
-  const certDir = path.join(os.homedir(), '.localctl', 'certs');
+  const certDir = CERTS_DIR;
   fs.mkdirSync(certDir, { recursive: true });
   const certFile = path.join(certDir, 'local-dev.pem');
   const keyFile = path.join(certDir, 'local-dev-key.pem');
@@ -127,15 +307,10 @@ function provisionCluster({ clusterName, httpPort, httpsPort, registryPort }) {
 
   // k3d's --wait only waits for node readiness, not for Traefik's helm-install job to finish
   // registering its CRDs, so applying TLSStore any earlier races and fails intermittently.
-  logger.step('Waiting for Traefik CRDs...');
-  for (let i = 0; i < 60; i += 1) {
-    if (capture('kubectl', ['get', 'crd', 'tlsstores.traefik.io']).status === 0) break;
-    sleepSync(2000);
-  }
-  run('kubectl', ['wait', '--for=condition=Established', 'crd/tlsstores.traefik.io', '--timeout=60s'], { stdio: 'ignore' });
-
-  run('kubectl', ['apply', '-f', path.join(MANIFESTS_DIR, 'tls-store.yaml')]);
-  run('kubectl', ['apply', '-f', path.join(MANIFESTS_DIR, 'namespace-addons.yaml')]);
+  waitForTraefikCrds();
+  applyWithRetry(path.join(MANIFESTS_DIR, 'tls-store.yaml'));
+  applyWithRetry(path.join(MANIFESTS_DIR, 'namespace-addons.yaml'));
+  waitForTraefik();
   logger.success('TLS configured, default cert wired into Traefik');
 }
 
@@ -165,7 +340,7 @@ function ensureClusterUp(clusterName, profileName) {
     const fix = profileName === 'default' ? 'localctl setup' : `localctl profiles switch ${profileName}`;
     throw new Error(`No cluster running for project "${profileName}". Run "${fix}" to start it.`);
   }
-  run('kubectl', ['config', 'use-context', `k3d-${clusterName}`], { stdio: 'ignore' });
+  useClusterContext(clusterName);
 }
 
-module.exports = { provisionCluster, teardownCluster, clusterExists, registryNameFor, ensureClusterUp };
+module.exports = { buildK3dConfig, useClusterContext, waitForClusterApi, provisionCluster, teardownCluster, clusterExists, registryNameFor, ensureClusterUp };

package/src/lib/engine.js

@@ -4,8 +4,8 @@ const logger = require('./logger');
 // Support status per engine lives in cli/package.json ("localctl.containerEngines"), so marking an
 // engine as tested is a one-word config change, not a code change. "tested" means verified end to
 // end; anything else (or an engine missing from the map) gets the experimental warning.
-const { localctl: { containerEngines = {} } = {} } = require('../../package.json');
-const ENGINE_LABELS = { docker: 'Docker Desktop', podman: 'Podman', 'rancher-desktop': 'Rancher Desktop' };
+const { localctl: { containerEngines = {}, platforms = {} } = {} } = require('../../package.json');
+const ENGINE_LABELS = { docker: 'Docker', podman: 'Podman', 'rancher-desktop': 'Rancher Desktop' };
 const ISSUES_URL = 'https://github.com/psilvmoreira/localctl/issues';
 
 // Returns { engine, bin } - `engine` names what's actually running (docker/podman/rancher-desktop),
@@ -33,4 +33,14 @@ function warnIfExperimental(engine) {
   logger.warn(`If something breaks, please report it: ${ISSUES_URL}`);
 }
 
-module.exports = { detectEngine, warnIfExperimental };
+const PLATFORM_LABELS = { darwin: 'macOS', win32: 'Windows', linux: 'Linux' };
+
+// Same idea as warnIfExperimental(), for the operating system: platform status lives in
+// cli/package.json ("localctl.platforms").
+function warnIfExperimentalPlatform() {
+  if (!platforms[process.platform] || platforms[process.platform] === 'tested') return;
+  logger.warn(`${PLATFORM_LABELS[process.platform] || process.platform} support is experimental - it hasn't been through a full test cycle yet.`);
+  logger.warn(`If something breaks, please report it: ${ISSUES_URL}`);
+}
+
+module.exports = { detectEngine, warnIfExperimental, warnIfExperimentalPlatform };

package/src/lib/exec.js

@@ -21,9 +21,12 @@ function capture(cmd, args, opts = {}) {
 }
 
 function commandExists(cmd) {
-  const probe = process.platform === 'win32' ? 'where' : 'which';
-  const res = spawnSync(probe, [cmd], { stdio: 'ignore' });
-  return res.status === 0;
+  if (process.platform === 'win32') {
+    return spawnSync('where', [cmd], { stdio: 'ignore' }).status === 0;
+  }
+  // `command -v` is a POSIX shell builtin; `which` is a separate program that minimal installs
+  // (Fedora/openSUSE server images, containers) don't ship.
+  return spawnSync('sh', ['-c', 'command -v "$0"', cmd], { stdio: 'ignore' }).status === 0;
 }
 
 // Blocking sleep with no native dependency - used for poll loops (e.g. waiting on a CRD to

package/src/lib/hostsFile.js

@@ -8,8 +8,10 @@ const { DOMAIN } = require('./constants');
 
 const MARK_START = '# >>> localctl managed block >>>';
 const MARK_END = '# <<< localctl managed block <<<';
-const HOSTS_PATH =
-  process.platform === 'win32' ? 'C:\\Windows\\System32\\drivers\\etc\\hosts' : '/etc/hosts';
+// $LOCALCTL_HOSTS_FILE points it at another file - used by the e2e suite so tests never touch
+// (or need sudo for) the real hosts file.
+const HOSTS_PATH = process.env.LOCALCTL_HOSTS_FILE ||
+  (process.platform === 'win32' ? 'C:\\Windows\\System32\\drivers\\etc\\hosts' : '/etc/hosts');
 
 function registerApp(subdomain) {
   ensureHomeState();

package/src/lib/linuxDistro.js

@@ -0,0 +1,122 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { run, commandExists } = require('./exec');
+const logger = require('./logger');
+
+// Families localctl knows how to give exact commands for. Anything else is "unknown" and gets
+// generic guidance instead of a guess.
+const FAMILY_BY_ID = [
+  ['debian', ['debian', 'ubuntu']],
+  ['rhel', ['fedora', 'rhel', 'centos', 'rocky', 'almalinux']],
+  ['arch', ['arch']],
+  ['suse', ['suse', 'opensuse']],
+  ['alpine', ['alpine']],
+];
+
+// Reads ID and ID_LIKE from os-release, so derivatives resolve to their parent (Mint, Pop!_OS ->
+// debian; Rocky, Alma -> rhel; Manjaro -> arch).
+function detectDistro() {
+  let release = null;
+  // /usr/lib/os-release is the documented fallback when /etc/os-release is missing.
+  for (const file of ['/etc/os-release', '/usr/lib/os-release']) {
+    try {
+      release = fs.readFileSync(file, 'utf8');
+      break;
+    } catch (e) {
+      // try the next location
+    }
+  }
+  if (release === null) return { id: 'unknown', family: 'unknown' };
+  const value = (key) => {
+    const m = release.match(new RegExp(`^${key}=(.*)$`, 'm'));
+    return m ? m[1].replace(/"/g, '').trim() : '';
+  };
+  const id = value('ID') || 'unknown';
+  const ids = [id, ...value('ID_LIKE').split(/\s+/)].filter(Boolean);
+  const match = FAMILY_BY_ID.find(([, names]) => names.some((n) => ids.includes(n)));
+  return { id, family: match ? match[0] : 'unknown' };
+}
+
+function hasSystemd() {
+  return fs.existsSync('/run/systemd/system');
+}
+
+function isRoot() {
+  return typeof process.getuid === 'function' && process.getuid() === 0;
+}
+
+// What `localctl setup --install-docker` would do, as printable steps. Shown in the "no engine"
+// error too, so the user can run them by hand. Returns null for families without a known recipe.
+function dockerInstallSteps(family, id) {
+  const sudo = isRoot() ? '' : 'sudo ';
+  const user = os.userInfo().username;
+  let install;
+  if (family === 'rhel' && id !== 'fedora') {
+    // Docker's convenience script derives the repo path from the distro ID, and publishes
+    // .../linux/centos and .../linux/rhel but not .../linux/rocky or .../linux/almalinux: it adds
+    // a repo whose packages don't exist ("Unable to find a match: docker-ce"). The CentOS repo is
+    // what Docker documents for the RHEL rebuilds.
+    install = [
+      `${sudo}dnf -y install dnf-plugins-core`,
+      `${sudo}dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo`,
+      `${sudo}dnf -y install docker-ce docker-ce-cli containerd.io`,
+    ];
+  } else if (family === 'debian' || family === 'rhel') {
+    install = [`curl -fsSL https://get.docker.com -o get-docker.sh && ${sudo}sh get-docker.sh`];
+  } else if (family === 'arch') {
+    install = [`${sudo}pacman -S --noconfirm docker`];
+  } else if (family === 'suse') {
+    install = [`${sudo}zypper --non-interactive install docker`];
+  } else {
+    return null;
+  }
+  const steps = [...install];
+  if (hasSystemd()) steps.push(`${sudo}systemctl enable --now docker`);
+  if (!isRoot()) steps.push(`${sudo}usermod -aG docker ${user}`);
+  return steps;
+}
+
+// Runs dockerInstallSteps() for real. The download goes to a temp file first (never piped into a
+// shell) and Docker's official script is the only remote code involved. Needs sudo, so it only
+// ever runs on an explicit `--install-docker`.
+function installDocker() {
+  const { family, id } = detectDistro();
+  if (!dockerInstallSteps(family, id)) {
+    throw new Error(`No automatic Docker install for "${id}". Install Docker Engine for your distro (https://docs.docker.com/engine/install/) and re-run.`);
+  }
+  const viaScript = family === 'debian' || (family === 'rhel' && id === 'fedora');
+  if (!commandExists('curl') && viaScript) {
+    throw new Error('curl is needed to download the Docker install script. Install it and re-run.');
+  }
+  logger.step(`Installing Docker Engine (${id}). This needs sudo and will prompt for your password...`);
+  const sudo = isRoot() ? [] : ['sudo'];
+  const exec = (cmd, args) => run(sudo.length ? sudo[0] : cmd, sudo.length ? [cmd, ...args] : args);
+
+  if (viaScript) {
+    const script = path.join(os.tmpdir(), 'localctl-get-docker.sh');
+    run('curl', ['-fsSL', 'https://get.docker.com', '-o', script]);
+    try {
+      exec('sh', [script]);
+    } finally {
+      fs.rmSync(script, { force: true });
+    }
+  } else if (family === 'rhel') {
+    exec('dnf', ['-y', 'install', 'dnf-plugins-core']);
+    exec('dnf', ['config-manager', '--add-repo', 'https://download.docker.com/linux/centos/docker-ce.repo']);
+    exec('dnf', ['-y', 'install', 'docker-ce', 'docker-ce-cli', 'containerd.io']);
+  } else if (family === 'arch') {
+    exec('pacman', ['-S', '--noconfirm', 'docker']);
+  } else if (family === 'suse') {
+    exec('zypper', ['--non-interactive', 'install', 'docker']);
+  }
+  if (hasSystemd()) exec('systemctl', ['enable', '--now', 'docker']);
+  if (!isRoot()) exec('usermod', ['-aG', 'docker', os.userInfo().username]);
+
+  logger.success('Docker installed.');
+  if (!isRoot()) {
+    logger.warn('Group membership only applies to new sessions: log out and back in (or run "newgrp docker"), then re-run "localctl setup".');
+  }
+}
+
+module.exports = { detectDistro, hasSystemd, dockerInstallSteps, installDocker };

package/src/lib/paths.js

@@ -5,7 +5,10 @@ const fs = require('fs');
 const APP_DIR = process.cwd();
 const LOCAL_DIR = path.join(APP_DIR, '.local');
 const CONFIG_PATH = path.join(LOCAL_DIR, 'config.json');
-const HOME_STATE_DIR = path.join(os.homedir(), '.localctl');
+// $LOCALCTL_HOME relocates all machine-level state (profiles, apps, certs, run files). The e2e
+// suite uses it to run against a throwaway directory instead of your real ~/.localctl.
+const HOME_STATE_DIR = process.env.LOCALCTL_HOME || path.join(os.homedir(), '.localctl');
+const CERTS_DIR = path.join(HOME_STATE_DIR, 'certs');
 const APPS_REGISTRY_PATH = path.join(HOME_STATE_DIR, 'apps.json');
 const PROFILES_PATH = path.join(HOME_STATE_DIR, 'profiles.json');
 const RUN_DIR = path.join(HOME_STATE_DIR, 'run');
@@ -33,6 +36,7 @@ module.exports = {
   LOCAL_DIR,
   CONFIG_PATH,
   HOME_STATE_DIR,
+  CERTS_DIR,
   APPS_REGISTRY_PATH,
   PROFILES_PATH,
   RUN_DIR,

package/src/lib/podman.js

@@ -1,8 +1,46 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const { run, capture } = require('./exec');
 const logger = require('./logger');
 
 const CONF_PATH = '/etc/containers/registries.conf.d/999-local-dev.conf';
 
+// Native Podman (Linux) has no VM: its registries.conf lives on the host. Rootless Podman reads
+// the per-user drop-in directory (no sudo needed); root reads the system one.
+function nativeConfPath() {
+  if (typeof process.getuid === 'function' && process.getuid() === 0) return CONF_PATH;
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(configHome, 'containers', 'registries.conf.d', '999-local-dev.conf');
+}
+
+// Linux native Podman: no `podman machine`. Containers-image re-reads registries.conf on every
+// invocation, so unlike the VM case there's nothing to restart.
+function ensureInsecureRegistryNative(hostPort) {
+  const file = nativeConfPath();
+  const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  if (current.includes(`location = "localhost:${hostPort}"`)) {
+    logger.success(`Podman already trusts localhost:${hostPort} as an insecure registry`);
+    return;
+  }
+  logger.step(`Marking localhost:${hostPort} as an insecure registry for Podman (${file})...`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const next = `${current.trimEnd()}\n\n${registryBlock(hostPort)}`.trim().concat('\n');
+  fs.writeFileSync(file, next);
+  logger.success('Podman registry config updated');
+}
+
+function teardownInsecureRegistryNative() {
+  const file = nativeConfPath();
+  if (!fs.existsSync(file)) return;
+  fs.rmSync(file, { force: true });
+  logger.success(`Removed insecure-registry config ${file}`);
+}
+
+function isNativePodman() {
+  return process.platform === 'linux';
+}
+
 function machineName() {
   const res = capture('podman', ['machine', 'list', '--format', '{{.Name}}']);
   const [first] = res.stdout.split('\n').filter(Boolean);
@@ -34,7 +72,10 @@ function registryBlock(hostPort) {
 // something tried to use it. One file, one block per port ever provisioned on this machine.
 function ensureInsecureRegistry(hostPort) {
   const machine = machineName();
-  if (!machine) return;
+  if (!machine) {
+    if (isNativePodman()) ensureInsecureRegistryNative(hostPort);
+    return;
+  }
 
   const current = capture('podman', ['machine', 'ssh', machine, `cat ${CONF_PATH} 2>/dev/null`]).stdout;
   if (current.includes(`location = "localhost:${hostPort}"`)) {
@@ -57,7 +98,10 @@ function ensureInsecureRegistry(hostPort) {
 
 function teardownInsecureRegistry() {
   const machine = machineName();
-  if (!machine) return;
+  if (!machine) {
+    if (isNativePodman()) teardownInsecureRegistryNative();
+    return;
+  }
 
   const exists = capture('podman', ['machine', 'ssh', machine, `test -f ${CONF_PATH} && echo yes`]).stdout;
   if (exists.trim() !== 'yes') return;
@@ -69,4 +113,50 @@ function teardownInsecureRegistry() {
   logger.success('Podman VM config removed and machine restarted');
 }
 
-module.exports = { ensureInsecureRegistry, teardownInsecureRegistry };
+// k3d talks to the container engine through the Docker API socket. Docker exposes it by default;
+// Podman only when its socket service is running, and k3d finds it through DOCKER_HOST. Points
+// DOCKER_HOST at Podman's socket when it exists, and returns a problem description (or null).
+function ensurePodmanSocket() {
+  if (process.env.DOCKER_HOST) return null;
+  const res = capture('podman', ['info', '--format', '{{.Host.RemoteSocket.Path}}']);
+  const socket = res.status === 0 ? res.stdout.replace(/^unix:\/\//, '') : '';
+  if (socket && fs.existsSync(socket)) {
+    process.env.DOCKER_HOST = `unix://${socket}`;
+    logger.info(`Using the Podman socket at ${socket} (DOCKER_HOST)`);
+    return null;
+  }
+  return 'Podman\'s API socket isn\'t running, which k3d needs. Start it with: systemctl --user enable --now podman.socket';
+}
+
+// Rootless Podman can't bind host ports below net.ipv4.ip_unprivileged_port_start (1024 by
+// default), and the cluster maps host :80/:443. Returns the ports that will fail to bind.
+function blockedPrivilegedPorts(ports) {
+  const rootless = capture('podman', ['info', '--format', '{{.Host.Security.Rootless}}']).stdout === 'true';
+  if (!rootless) return [];
+  let start = 1024;
+  try {
+    start = parseInt(fs.readFileSync('/proc/sys/net/ipv4/ip_unprivileged_port_start', 'utf8'), 10);
+  } catch (e) {
+    // keep the default
+  }
+  return ports.filter((p) => p < start);
+}
+
+// Memory (MB) available to containers: the Podman VM on macOS/Windows, the host on native Linux.
+// Returns null when it can't be determined. Docker Desktop's VM size comes from `docker info`.
+function engineMemoryMb(engineBin) {
+  const res = capture(engineBin, ['info', '--format', '{{.MemTotal}}']);
+  const bytes = parseInt(res.stdout, 10);
+  if (res.status === 0 && Number.isFinite(bytes) && bytes > 0) return Math.round(bytes / 1024 / 1024);
+  const info = capture(engineBin, ['info', '--format', '{{.Host.MemTotal}}']);
+  const hostBytes = parseInt(info.stdout, 10);
+  return info.status === 0 && Number.isFinite(hostBytes) && hostBytes > 0 ? Math.round(hostBytes / 1024 / 1024) : null;
+}
+
+module.exports = {
+  engineMemoryMb,
+  ensureInsecureRegistry,
+  teardownInsecureRegistry,
+  ensurePodmanSocket,
+  blockedPrivilegedPorts,
+};

package/src/lib/toolInstall.js

@@ -1,7 +1,9 @@
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
-const { commandExists, run } = require('./exec');
+const { commandExists, run, capture } = require('./exec');
 const logger = require('./logger');
+const { detectDistro } = require('./linuxDistro');
 const { HOME_STATE_DIR } = require('./paths');
 
 // Tools that have no package-manager package on a platform get downloaded here instead. The
@@ -65,6 +67,141 @@ function installTiltWindows() {
   logger.success(`tilt installed in ${TOOLS_DIR} (added to your PATH for new terminals)`);
 }
 
+
+// ---- Linux ----
+// There's no single package manager to lean on across distros, so missing tools are fetched as
+// the vendors' own release binaries straight into TOOLS_DIR (no sudo, no distro packages). That
+// directory is on this process's PATH via addToolsDirToPath(), so setup carries on immediately.
+// Needs only curl (and tar for tilt/helm), which every mainstream distro ships.
+
+const LINUX_ARCH = { x64: 'amd64', arm64: 'arm64' };
+
+function linuxArch() {
+  const arch = LINUX_ARCH[process.arch];
+  if (!arch) throw new Error(`Unsupported CPU architecture "${process.arch}". Install the tool manually.`);
+  return arch;
+}
+
+function requireLinuxDownloadTools(...tools) {
+  const missing = tools.filter((t) => !commandExists(t));
+  if (missing.length) {
+    throw new Error(`${missing.join(' and ')} ${missing.length > 1 ? 'are' : 'is'} needed to download missing tools. Install ${missing.length > 1 ? 'them' : 'it'} with your package manager and re-run.`);
+  }
+}
+
+function download(url, dest) {
+  logger.info(`Downloading ${url}`);
+  run('curl', ['-fsSL', '--retry', '3', '-o', dest, url]);
+}
+
+// Final path segment of the URL a redirect lands on, e.g. ".../releases/tag/v0.33.0" -> "v0.33.0".
+function latestGitHubTag(repo) {
+  const res = capture('curl', [
+    '-fsSLI', '-o', '/dev/null', '-w', '%{url_effective}',
+    `https://github.com/${repo}/releases/latest`,
+  ]);
+  const tag = res.stdout.split('/').pop();
+  if (res.status !== 0 || !/^v?\d/.test(tag)) throw new Error(`Couldn't resolve the latest ${repo} release.`);
+  return tag;
+}
+
+function makeExecutable(file) {
+  fs.chmodSync(file, 0o755);
+}
+
+function installBinaryLinux(bin, url) {
+  fs.mkdirSync(TOOLS_DIR, { recursive: true });
+  const dest = path.join(TOOLS_DIR, bin);
+  download(url, dest);
+  makeExecutable(dest);
+}
+
+// Downloads a .tar.gz and moves one file out of it into TOOLS_DIR.
+function installFromTarballLinux(bin, url, innerPath) {
+  fs.mkdirSync(TOOLS_DIR, { recursive: true });
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), `localctl-${bin}-`));
+  try {
+    const archive = path.join(tmp, 'archive.tar.gz');
+    download(url, archive);
+    run('tar', ['-xzf', archive, '-C', tmp]);
+    const dest = path.join(TOOLS_DIR, bin);
+    fs.copyFileSync(path.join(tmp, innerPath), dest);
+    makeExecutable(dest);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+const LINUX_INSTALLERS = {
+  k3d() {
+    installBinaryLinux('k3d', `https://github.com/k3d-io/k3d/releases/latest/download/k3d-linux-${linuxArch()}`);
+  },
+  kubectl() {
+    const version = capture('curl', ['-fsSL', 'https://dl.k8s.io/release/stable.txt']).stdout;
+    if (!/^v\d/.test(version)) throw new Error("Couldn't resolve the latest kubectl release.");
+    installBinaryLinux('kubectl', `https://dl.k8s.io/release/${version}/bin/linux/${linuxArch()}/kubectl`);
+  },
+  mkcert() {
+    installBinaryLinux('mkcert', `https://dl.filippo.io/mkcert/latest?for=linux/${linuxArch()}`);
+  },
+  helm() {
+    const version = capture('curl', ['-fsSL', 'https://get.helm.sh/helm-latest-version']).stdout;
+    if (!/^v\d/.test(version)) throw new Error("Couldn't resolve the latest helm release.");
+    const arch = linuxArch();
+    installFromTarballLinux('helm', `https://get.helm.sh/helm-${version}-linux-${arch}.tar.gz`, `linux-${arch}/helm`);
+  },
+  tilt() {
+    const version = latestGitHubTag('tilt-dev/tilt').replace(/^v/, '');
+    const arch = process.arch === 'arm64' ? 'arm64' : 'x86_64';
+    installFromTarballLinux('tilt', `https://github.com/tilt-dev/tilt/releases/download/v${version}/tilt.${version}.linux.${arch}.tar.gz`, 'tilt');
+  },
+};
+
+// Tools land in TOOLS_DIR, which localctl puts on its own PATH, but a terminal opened later (to
+// run `kubectl` by hand, say) wouldn't see them. Persist it in the shell's rc file, with the same
+// marker bin/bootstrap.sh uses so bin/uninstall.sh cleans it up. bash and zsh only: other shells
+// get the line to add themselves.
+function persistToolsDirOnPath() {
+  const shell = path.basename(process.env.SHELL || '');
+  const rcName = { zsh: '.zshrc', bash: '.bashrc' }[shell];
+  const line = 'export PATH="$HOME/.localctl/tools:$PATH"';
+  if (!rcName) {
+    logger.info(`Add ${TOOLS_DIR} to your PATH to use these tools from your own terminal: ${line}`);
+    return;
+  }
+  const rc = path.join(os.homedir(), rcName);
+  const current = fs.existsSync(rc) ? fs.readFileSync(rc, 'utf8') : '';
+  if (current.includes('.localctl/tools')) return;
+  fs.appendFileSync(rc, `\n# Added by localctl bootstrap\n${line}\n`);
+  logger.info(`Added ${TOOLS_DIR} to PATH in ~/${rcName} - open a new terminal to pick it up.`);
+}
+
+function installLinux(bin) {
+  const installer = LINUX_INSTALLERS[bin];
+  if (!installer) {
+    throw new Error(`"${bin}" is missing and automatic install isn't supported for it on Linux. Install it with your package manager.`);
+  }
+  requireLinuxDownloadTools('curl', ...(bin === 'helm' || bin === 'tilt' ? ['tar'] : []));
+  logger.step(`Installing ${bin} from its official release (no sudo, into ${TOOLS_DIR})...`);
+  installer();
+  addToolsDirToPath();
+  persistToolsDirOnPath();
+  logger.success(`${bin} installed in ${TOOLS_DIR}`);
+}
+
+// Distro-specific command for the NSS tools (certutil), which mkcert needs to trust its CA in
+// Firefox/Chromium. Not installed automatically: it needs sudo, and it's optional.
+function nssInstallHint() {
+  const { family } = detectDistro();
+  return {
+    debian: 'sudo apt install libnss3-tools',
+    rhel: 'sudo dnf install nss-tools',
+    arch: 'sudo pacman -S nss',
+    suse: 'sudo zypper install mozilla-nss-tools',
+    alpine: 'sudo apk add nss-tools',
+  }[family] || "your distro's NSS tools package (provides certutil)";
+}
+
 // macId: Homebrew formula name. winId: winget package id, or a function that installs the tool
 // when winget doesn't have it.
 function installIfMissing(bin, macId, winId) {
@@ -92,9 +229,11 @@ function installIfMissing(bin, macId, winId) {
       '--accept-package-agreements', '--accept-source-agreements',
     ]);
     addWingetLinksToPath();
+  } else if (process.platform === 'linux') {
+    installLinux(bin);
   } else {
     throw new Error(`"${bin}" is missing and automatic install isn't supported on this platform. Install it manually.`);
   }
 }
 
-module.exports = { installIfMissing, installTiltWindows, addToolsDirToPath, TOOLS_DIR };
+module.exports = { installIfMissing, installTiltWindows, addToolsDirToPath, nssInstallHint, TOOLS_DIR };