Skip to main content

🍎 macOS

LaraKube CLI is a first-class citizen on macOS. What you need to install depends entirely on what you plan to do with it, and larakube setup asks which it is.

🛠 Prerequisites​

If you only want Cluster Tools​

Self-hosting chat, a wiki, single sign-on or any other Cluster Tool needs no container runtime at all — those are installed with kubectl against a cluster, and nothing is built on your Mac. larakube setup installs kubectl for you.

See Cluster Tools Without a Dev Setup, and skip the rest of this page.

If you want to build and deploy your own apps​

  1. OrbStack (recommended) or Docker Desktop — the engine that runs your containers and Kubernetes nodes.
  2. Homebrew — optional, but the smoothest way to manage local dependencies.
warning
larakube setup does not install a cluster on macOS

Native k3s needs a Linux kernel. On macOS, Kubernetes runs inside a Linux VM managed by OrbStack or Docker Desktop — enable their built-in Kubernetes instead. larakube setup still runs, and still installs kubectl, Traefik and your developer CLI tools; it just won't provide the runtime or the cluster itself.

🚀 Setup Instructions​

1. Install LaraKube CLI​

Option A — Homebrew (recommended)​

The cleanest path on Mac. You get versioned upgrades via brew upgrade:

brew tap luchavez-technologies/larakube
brew trust luchavez-technologies/larakube
brew install larakube
note
Why brew trust?

Recent Homebrew versions refuse to load formulae from third-party taps until you explicitly trust them. It's a one-time acknowledgement per tap — if you skip it, brew install fails with "Refusing to load formula … from untrusted tap."

Migrating from the standalone installer?

If you previously ran install.sh, a larakube binary lives in /usr/local/bin and can shadow the Homebrew version on your PATH. Remove it and let Homebrew take over:

sudo rm -f /usr/local/bin/larakube
hash -r
which larakube       # should now resolve to your Homebrew prefix
larakube --version   # confirm the Homebrew version

Upgrade later with:

brew upgrade larakube

Option B — Standalone binary​

curl -fsSL https://cli.larakube.app/install.sh | bash

2. Enable Kubernetes​

LaraKube CLI needs a Kubernetes cluster running locally. Enable the built-in one from your container engine:

  • OrbStack: Settings → Kubernetes → toggle On
  • Docker Desktop: Settings → Kubernetes → check Enable Kubernetes

LaraKube CLI automatically detects these contexts.

3. Set up this machine​

larakube setup

Choose Local development. With a runtime already running, that is the default answer. It installs kubectl, deploys Traefik, configures wildcard DNS through dnsmasq, and offers the developer CLI tools.

4. Trust SSL​

larakube trust

5. Create and start your first app​

larakube new my-app
cd my-app
larakube up

📐 Why OrbStack?​

OrbStack runs a Linux VM with built-in Kubernetes that starts in seconds, uses less memory than Docker Desktop, and mounts your Mac filesystem into the VM with near-native performance. LaraKube CLI uses Kustomize patches specifically tuned for macOS to resolve common volume permission issues in storage/ and bootstrap/cache/.