Skip to content

Install katamaran

Install katamaran on an Apple silicon Mac and connect the Docker command-line tools to it.

  • An Apple silicon Mac (M1 or later)
  • macOS 15 or later
  • The Docker command-line tools (docker, docker-buildx, and docker-compose)

Install the Docker command-line tools with Homebrew if you do not have them yet:

Terminal window
brew install docker docker-buildx docker-compose

If you plan to run linux/amd64 images at native translation speed, install Apple Rosetta:

Terminal window
softwareupdate --install-rosetta
Terminal window
brew install --cask nklmilojevic/katamaran/katamaran

Open Katamaran from /Applications after Homebrew finishes.

  1. Download and open the latest signed Katamaran.dmg (or browse all versions on GitHub releases). To build the disk image yourself, follow Build from source.
  2. Drag Katamaran.app into /Applications.
  3. Open Katamaran from /Applications.

On first launch, Katamaran runs katamaran setup --default automatically. Setup installs:

  • A LaunchAgent in ~/Library/LaunchAgents/ that runs the katamaran daemon process at login
  • A Docker context named katamaran pointing to unix://$HOME/.katamaran/run/docker.sock, set as the default Docker context whenever Katamaran launches
  • A symlink at ~/.local/bin/kat pointing to the katamaran binary inside the app bundle

Add ~/.local/bin to your shell PATH so you can run kat from any terminal.

To run setup from the command line, execute:

Terminal window
katamaran setup

To also make katamaran your default Docker context, pass --default:

Terminal window
katamaran setup --default

If you run a second isolated development instance with KATAMARAN_HOME, pass --suffix so its LaunchAgent, Docker context, and symlink do not collide with your main installation:

Terminal window
KATAMARAN_HOME=~/.katamaran-dev katamaran setup --suffix dev

Check that the VM is running and Docker responds:

Terminal window
kat status
docker --context katamaran info

To remove the LaunchAgent, the Docker context, and the ~/.local/bin/kat symlink, run:

Terminal window
kat uninstall

kat uninstall stops the daemon and leaves ~/.katamaran intact so your containers, images, volumes, and Linux machines stay on disk. Delete ~/.katamaran manually if you want to remove all stored data.