Skip to content

cli: add colima autostart to start at login or at boot - #1636

Draft
resker wants to merge 1 commit into
abiosoft:mainfrom
resker:feat/autostart
Draft

cli: add colima autostart to start at login or at boot#1636
resker wants to merge 1 commit into
abiosoft:mainfrom
resker:feat/autostart

Conversation

@resker

@resker resker commented Sep 12, 2026

Copy link
Copy Markdown

Refs #74 (also #262, #1265, #1490).

Lima can register an instance with launchd or systemd to start automatically — either at
login, or on macOS at system boot before anyone logs in. The second is what a headless
machine needs, and is what users have been approximating with hand-rolled plists.

This exposes it as a Colima subcommand:

colima autostart enable          # at login
colima autostart enable --boot   # at system boot (macOS, prompts for sudo)
colima autostart disable

It is a thin delegation to limactl autostart. Colima's docker socket is already a
PortForward in the generated Lima YAML, so limactl start <instance> restores it
without Colima's involvement — no separate plist generation is needed here.

Draft: depends on an unreleased Lima

A Colima instance lives under ~/.colima/_lima, not the default ~/.lima, so this only
works once the generated launchd/systemd unit carries LIMA_HOME. That landed in
lima-vm/lima#5489, which is merged but not in any release yet — the current stable is
Lima v2.2.0, and it missed v2.3.0-beta.0. Marking this draft until Lima v2.3.0 ships.

Open questions

1. Provision scripts, and the relationship to brew services. This delegates to limactl autostart, so the generated unit runs limactl start <instance> --foreground. Lima's plist hardcodes its own binary, so there is no way to point the unit at colima start instead. The consequence is that the provision scripts Colima runs itself — those with mode after-boot or ready, per Provision.IsColimaMode — do not run on an automatic start. colima autostart enable warns when the instance has any, rather than failing silently.

That may well be the wrong trade. brew services start colima runs colima start -f, the full path, and preserves them. The alternative here is for Colima to generate its own LaunchAgent/LaunchDaemon (and systemd unit) invoking colima start -f, which would give parity, drop the Lima version requirement entirely, and make autostart and brew services the same path — at the cost of Colima owning plist generation, the sudo write, launchctl bootstrap/bootout, and the Linux equivalent, all of which Lima maintains today.

I took the smaller option to keep this reviewable, but I suspect you may want the parity. Happy to rework it that way — or to close this if sudo brew services start colima covers enough of the need.

2. Command shape. colima autostart enable|disable mirrors limactl autostart. A colima start --autostart flag is the alternative.

3. Profile. Targeted with the global --profile flag rather than a positional arg, since the positional-profile handling in cmd/root is a fixed list of command names.

Known limitations

  • Provision scripts with mode after-boot or ready do not run on an automatic start (see open question 1). Warned about at enable time, and documented in the FAQ and the command help.
  • The version check rejects development builds of Lima: 2.3.0-beta.0 and 2.3.0-17-gabc1234 both sort below 2.3.0 under semver. That is deliberate — it fails closed — but it does mean someone testing against Lima master is refused.

LLM usage disclosure

Per docs/CONTRIBUTE.md. Drafted with Claude Code (Opus 5): cmd/autostart.go,
environment/vm/lima/limautil/autostart.go, and the FAQ addition were AI-generated from
my direction, then reviewed, corrected and tested by me before submitting. One defect
caught in review: the subcommands initially took a positional [profile] argument that
cmd/root's whitelist would have silently ignored. I take responsibility for the code.

Lima can register an instance with launchd or systemd to start automatically,
either when the user logs in or, on macOS, at system boot before anyone has
logged in. The latter is what a headless machine needs, and it is what users
have been hand-rolling LaunchAgent and LaunchDaemon plists to approximate (abiosoft#74,
abiosoft#262, abiosoft#1265, abiosoft#1490).

Expose it as `colima autostart enable|disable`, delegating to `limactl
autostart`. `--boot` selects the system LaunchDaemon, which requires sudo to
write to /Library/LaunchDaemons.

This relies on the generated unit carrying LIMA_HOME (lima-vm/lima#5489), since
a Colima instance lives under ~/.colima/_lima rather than the default ~/.lima,
so Lima v2.3.0 or newer is required and the version is checked before
registering, rather than letting limactl fail on an unknown flag.

The unit runs `limactl start`, not `colima start`, so the provision scripts
Colima runs itself -- those with mode after-boot or ready, per
Provision.IsColimaMode -- do not run on an automatic start. Enabling autostart
warns when the instance has any, and the limitation is noted in the FAQ and the
command help.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Robert Esker <resker@gmail.com>
@resker

resker commented Sep 12, 2026

Copy link
Copy Markdown
Author

@abiosoft — before I invest any more into this, please advise:

This PR presently delegates to limactl autostart (merged but not yet shipped lima feature), which keeps the diff small but the generated unit runs limactl start rather than colima start — so after-boot/ready scripts don't run on an automatic start. Lima's plist hardcodes its own binary, so there's no way to point it at colima.

The alternative would be Colima generating its own LaunchAgent/LaunchDaemon (and systemd unit) running colima start -f. That'd give parity w/ what brew services does today at the cost of Colima owning plist generation, the sudo write, and launchctl bootstrap/bootout — though it'd also drop the Lima version dependency entirely.

I probably should have mentioned at the outset that the whole point is brew services can't cover the boot case w/o auto login. This PR would implement something that'd autostart on every boot regardless of whether logged in or not (e.g. on a headless system).

I suspect this initial version isn't sufficient given the gaps around after-boot/ready… but wanted to check prior to implementing the "parity" flavor of things.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant