Skip to content

Instantly share code, notes, and snippets.

@fardjad

fardjad/how-to-start-colima-automatically-on-macos.md

Last active May 19, 2025 01:13
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save fardjad/a83c30b9b744b9612d793666f28361a5 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save fardjad/a83c30b9b744b9612d793666f28361a5 to your computer and use it in GitHub Desktop.
Download ZIP
[How to start Colima automatically on macOS] Instructions for starting Colima automatically on macOS similar to Docker Desktop #macos #colima #docker
Raw
how-to-start-colima-automatically-on-macos.md

⚠️ Note: Since the merge of the commit Homebrew/homebrew-core#149670, starting Colima is as easy as running brew services start colima. You can skip the following work-around.

Steps

  1. Create an executable script to run in foreground and manage colima:
cat <<-EOF | sudo tee /usr/local/bin/colima-start-fg
#!/bin/bash

export PATH="/usr/local/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

function shutdown() {
  colima stop
  exit 0
}

trap shutdown SIGTERM
trap shutdown SIGINT

# wait until colima is running
while true; do
  colima status &>/dev/null
  if [[ \$? -eq 0 ]]; then
    break;
  fi

  colima start
  sleep 5
done

tail -f /dev/null &
wait \$!
EOF

sudo chmod +x /usr/local/bin/colima-start-fg
  1. Create a launchd agent to run colima automatically:
cat > $HOME/Library/LaunchAgents/com.github.abiosoft.colima.plist <<-EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.github.abiosoft.colima</string>
    <key>Program</key>
    <string>/usr/local/bin/colima-start-fg</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <false/>
  </dict>
</plist>
EOF

launchctl load -w $HOME/Library/LaunchAgents/com.github.abiosoft.colima.plist
@fardjad
Copy link
Author

fardjad commented Sep 11, 2024

@tj-smith47 I am mostly using Linux for development these days and cannot test Colima on macOS now, but last time I tried it (a few months ago) it was working as expected.

Ignoring the brew service, does colima start when you run colima start? If it doesn't, then something might be wrong with the installation or the configuration.

If starting colima manually works, I suggest looking at the launchd/brew logs to see what goes wrong.

@tj-smith47
Copy link

tj-smith47 commented Sep 11, 2024 •
edited
Loading

Speaking for my company as a whole - "sometimes" - but typically for me, yes. We have been advised to start it with homebrew rather than just colima start, so we're trying to work around that requirement. But something you said made something click: if you start it with homebrew, it is actually starting, but it's not ready right away.

We have had intermittent reports of people saying starting with homebrew made colima start, and the inconsistency brought us to the understanding that starting with homebrew was pretty much just acting like systemd enable to make sure it comes back up automatically. I think the perception of a problem is caused by the whole "if I can't see it happening, it isn't" misconception because the twitch response to colima status returning that it isn't running has always been to run colima start, so we never see that if we do nothing, it will come up.

So now my task is to figure out how to poll colima status until it reports that it's up before moving on so it continues to work in our scripts. I don't know much about launchd, but I'm pretty sure I can do this in a shell script somehow. If you can think of an easy way though, would love your input. Thank you for the response btw!

@fardjad
Copy link
Author

fardjad commented Sep 13, 2024 •
edited
Loading

@tj-smith47 No problem :)

It seems like colima in your case is sort of a dependency in a more complex setup.

So now my task is to figure out how to poll colima status until it reports that it's up before moving on so it continues to work in our scripts. I don't know much about launchd, but I'm pretty sure I can do this in a shell script somehow. If you can think of an easy way though, would love your input. Thank you for the response btw!

So, my initial thought/reaction is, what does your script do? Does it really need to be aware of the whole machinery (i.e. Colima, OrbStack, Docker Desktop, etc.) that runs the Docker Engine?

  • For use-cases such as running containers at startup, you can set a restart-policy for your containers.

  • If your script really depends on Docker (and for example needs the docker socket), you could wait/retry until your docker command succeeds (or the exit code of docker info is 0).

  • If your script really needs to be aware of Colima, you could do something like this:

    # wait until colima is running
while true; do
  colima status &>/dev/null
  if [[ $? -eq 0 ]]; then
    break;
  fi
  sleep 5
done

# the rest of your script

Also, kind of unrelated but noteworthy: at some point Colima changed the default VM type to qemu. QEMU has better compatibility but it can be slower than the native macOS virtualization framework (vz). So you might want to play around with the options (run colima start --edit to edit the VM config) to find the optimal setup for your hardware.

@tj-smith47
Copy link

tj-smith47 commented Sep 17, 2024

@fardjad Thanks, I'll give the colima status a shot 👌

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment