Upgrading marina

Upgrading is two commands: pull the new release, then re-create the VM so it re-provisions on the new version. The image cache survives, so the rebuild is fast.

Coming from klimax

marina was called klimax before v0.3. Moving an existing installation over is one command after the upgrade:

$ brew update && brew upgrade --cask klimax     # installs marina
$ marina migrate --dry-run                      # shows the plan, changes nothing
$ marina migrate
$ marina up

marina migrate deletes the klimax VM and its clusters, copies ~/.klimax/config.yaml to ~/.marina/ (renaming the VM, and the DNS zone if it is still the pre-v0.2.5 klimax.internal), moves the registry cache so no image is downloaded again, and removes the klimax login agent. marina up refuses to start until it has run. Re-create your clusters afterwards.

Was	Now
`klimax …`	`marina …` — `klimax` stays installed as an alias for now
`~/.klimax/`	`~/.marina/`
`*.<cluster>.klimax.internal`	`*.<cluster>.demo.internal` — unchanged if you were already on `demo.internal`, the default since v0.2.5
label `klimax.dev/fleet`	`marina.run/fleet`
`apiVersion: klimax.dev/v1alpha1`	`apiVersion: marina.run/v1alpha1`
the klimax local CA	a new marina CA — one `sudo` prompt to trust it

ℹ

marina migrate prints the few steps it leaves to you: untrusting the old CA, marina docker-context, marina skill install --force, and marina autostart install if you used it. Delete ~/.klimax once marina works.

The two steps

marina ships as a single binary with its VM provisioning baked in. Bump the binary, then rebuild the VM on it:

# 1. Refresh the tap, then pull the new release
$ brew update
$ brew upgrade --cask marina

# 2. Rebuild the VM on it (sudo — the host route is re-added)
$ marina destroy && marina up

brew update refreshes the bcollard/marina tap so Homebrew sees the newest cask version — without it, brew upgrade may report you're already up to date.

Built from source instead of Homebrew? Replace step 1 with a git pull and go build (see Getting started), then run the same marina destroy && marina up.

⬆

Always re-create the VM after an upgrade. A plain marina down/up only restarts the existing VM — it does not re-provision it, so Docker, containerd, the guest agent, and the routing rules keep running the old version until you destroy and rebuild.

Why a rebuild?

marina provisions the VM once, on first marina up: it installs a specific Docker and containerd, downloads the matching Lima guest agent, writes the registry-mirror and DNS config, and applies the iptables rules that make L3 routing work. All of that logic lives in the binary. A new release can change any of it — a containerd bump, a new certs.d layout, a routing fix — but an already-provisioned VM won't pick those changes up just by restarting. Destroying and re-creating the VM is what re-runs provisioning against the new binary.

What survives, what's recreated

Item	On `destroy && up`
`~/.marina/config.yaml`	Survives. Your CPUs, memory, bridge CIDR, and mirror tweaks are untouched.
Registry image cache	Survives with the default `cacheStorage: "host"` — kept in `~/.marina/registry-cache/`, so the rebuild pulls from local disk, not the internet.
Container image store	Survives. It lives on its own Lima disk (`vm.imageDisk`), unpacked node images included.
The VM	Recreated from scratch on the new binary.
Local DNS	Recreated by `up`. The Mac's `/etc/resolver/demo.internal` is removed by `destroy` and rewritten by `up` (one `sudo` prompt). Clusters you re-create get their names back automatically.
kind clusters	Removed — cluster state lives inside the VM. Re-create the ones you need afterwards.

🔄

Bring your clusters back with marina cluster create <name> once the VM is up — the warm image cache keeps that quick. Need to wipe config and caches too for a truly clean slate? See Reset.

Verify the upgrade

Confirm the new version is running, then check the VM, route, and iptables rules came back healthy:

$ marina version        # confirms the new binary
$ marina status         # VM state, host mounts, clusters, route, iptables
$ marina doctor         # diagnoses issues, prints fix commands