Skip to content

Commit 8db85e4

Browse files
Test Userclaude
Test User
and
claude
committed
docs: add tutorial for running podman on macOS startup with launchd
Add a new tutorial documenting how to use macOS launchd LaunchAgents to automatically start a Podman machine at login. This includes a working plist example, step-by-step instructions, and troubleshooting guidance (notably warning against using KeepAlive which causes restart loops). Closes #28044 Signed-off-by: veeceey <veeceey@users.noreply.github.com> Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent ec0f63c commit 8db85e4

2 files changed

Lines changed: 181 additions & 0 deletions

File tree

‎docs/tutorials/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,7 @@ Learn how to run containers that support socket activation.
3939
**[Performance](performance.md)**
4040

4141
Performance guide regarding Podman configuration and usage.
42+
43+
**[macOS Autostart](macos_autostart.md)**
44+
45+
How to automatically start a Podman machine at login on macOS using launchd.

‎docs/tutorials/macos_autostart.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Running Podman on macOS startup with launchd
2+
3+
On macOS, Podman requires a virtual machine to run containers. By default,
4+
you must manually start this VM with `podman machine start` each time you
5+
log in. This tutorial shows how to use macOS's `launchd` service manager
6+
to automatically start your Podman machine at login.
7+
8+
## Prerequisites
9+
10+
- macOS with Podman installed (e.g., via `brew install podman`)
11+
- A Podman machine already initialized (`podman machine init`)
12+
- The Podman machine should start successfully when running `podman machine start` manually
13+
14+
## Overview
15+
16+
macOS uses `launchd` to manage services. User-level services are defined by
17+
property list (plist) files placed in `~/Library/LaunchAgents/`. These
18+
"LaunchAgents" run when you log in and stop when you log out.
19+
20+
Key considerations for running `podman machine start` under launchd:
21+
22+
- **Do not use `KeepAlive` or automatic restart.** `podman machine start` is a
23+
one-shot command that starts the VM and then exits. If launchd restarts it,
24+
it will find the machine already running and return an error, which can cause
25+
a restart loop.
26+
- **Use `RunAtLoad` to start the machine once at login.**
27+
- **Use the full path to the `podman` binary** to avoid PATH issues.
28+
29+
## Step 1: Find your Podman binary path
30+
31+
Determine the full path to your `podman` binary:
32+
33+
```
34+
$ which podman
35+
/opt/homebrew/bin/podman
36+
```
37+
38+
If you installed Podman with Homebrew on an Apple Silicon Mac, the path is
39+
typically `/opt/homebrew/bin/podman`. On Intel Macs, it is usually
40+
`/usr/local/bin/podman`.
41+
42+
## Step 2: Create the LaunchAgent plist
43+
44+
Create the file `~/Library/LaunchAgents/com.podman.machine.default.plist`
45+
with the following content. Replace `/opt/homebrew/bin/podman` with the
46+
path from Step 1 if it differs on your system. Replace `podman-machine-default`
47+
with the name of your machine if you are not using the default.
48+
49+
```xml
50+
<?xml version="1.0" encoding="UTF-8"?>
51+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
52+
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
53+
<plist version="1.0">
54+
<dict>
55+
<key>Label</key>
56+
<string>com.podman.machine.default</string>
57+
58+
<key>ProgramArguments</key>
59+
<array>
60+
<string>/opt/homebrew/bin/podman</string>
61+
<string>machine</string>
62+
<string>start</string>
63+
<string>podman-machine-default</string>
64+
</array>
65+
66+
<key>RunAtLoad</key>
67+
<true/>
68+
69+
<key>StandardOutPath</key>
70+
<string>/tmp/podman-machine-start.log</string>
71+
72+
<key>StandardErrorPath</key>
73+
<string>/tmp/podman-machine-start.err.log</string>
74+
</dict>
75+
</plist>
76+
```
77+
78+
### Explanation of the plist keys
79+
80+
| Key | Purpose |
81+
|---|---|
82+
| `Label` | A unique identifier for the service. |
83+
| `ProgramArguments` | The command and arguments to run. Each argument is a separate `<string>`. |
84+
| `RunAtLoad` | Start the command as soon as the agent is loaded (at login). |
85+
| `StandardOutPath` | Where to write stdout for debugging. |
86+
| `StandardErrorPath` | Where to write stderr for debugging. |
87+
88+
### Important: do not use KeepAlive
89+
90+
A common mistake is to add `<key>KeepAlive</key><true/>` to the plist.
91+
This tells launchd to restart the process whenever it exits. Because
92+
`podman machine start` exits after the VM starts, launchd would immediately
93+
try to start it again. The second attempt finds the machine already running
94+
and fails, creating a rapid restart loop. This can interfere with the Podman
95+
CLI and degrade system performance. Always omit `KeepAlive` for this use case.
96+
97+
## Step 3: Load the LaunchAgent
98+
99+
Load the agent so it takes effect without logging out and back in:
100+
101+
```
102+
$ launchctl load ~/Library/LaunchAgents/com.podman.machine.default.plist
103+
```
104+
105+
The Podman machine should start. You can verify with:
106+
107+
```
108+
$ podman machine list
109+
NAME VM TYPE CREATED LAST UP CPUS MEMORY DISK SIZE
110+
podman-machine-default applehv 2 days ago Currently running 4 2GiB 100GiB
111+
```
112+
113+
## Step 4: Verify the logs
114+
115+
If the machine did not start as expected, check the log files for errors:
116+
117+
```
118+
$ cat /tmp/podman-machine-start.log
119+
$ cat /tmp/podman-machine-start.err.log
120+
```
121+
122+
## Managing the LaunchAgent
123+
124+
### Stop the machine from auto-starting
125+
126+
To prevent the Podman machine from starting at login, unload the agent:
127+
128+
```
129+
$ launchctl unload ~/Library/LaunchAgents/com.podman.machine.default.plist
130+
```
131+
132+
### Re-enable auto-starting
133+
134+
```
135+
$ launchctl load ~/Library/LaunchAgents/com.podman.machine.default.plist
136+
```
137+
138+
### Remove the LaunchAgent entirely
139+
140+
```
141+
$ launchctl unload ~/Library/LaunchAgents/com.podman.machine.default.plist
142+
$ rm ~/Library/LaunchAgents/com.podman.machine.default.plist
143+
```
144+
145+
## Troubleshooting
146+
147+
### The machine enters a restart loop
148+
149+
This typically occurs when `KeepAlive` is set to `true` in the plist. Edit the
150+
plist file, remove the `KeepAlive` key and its value, then unload and reload:
151+
152+
```
153+
$ launchctl unload ~/Library/LaunchAgents/com.podman.machine.default.plist
154+
$ launchctl load ~/Library/LaunchAgents/com.podman.machine.default.plist
155+
```
156+
157+
### The machine does not start
158+
159+
1. Check that the `podman` path in the plist is correct (`which podman`).
160+
2. Check the log files at `/tmp/podman-machine-start.log` and
161+
`/tmp/podman-machine-start.err.log`.
162+
3. Verify the machine starts correctly when running `podman machine start`
163+
manually in a terminal.
164+
4. Ensure the machine has been initialized with `podman machine init`.
165+
166+
### Permission issues
167+
168+
LaunchAgents run in your user context, so they have the same permissions
169+
as your terminal session. If `podman machine start` works in a terminal but
170+
not from launchd, check that the plist uses the full absolute path to the
171+
`podman` binary.
172+
173+
## SEE ALSO
174+
175+
**[podman-machine-start(1)](../source/markdown/podman-machine-start.1.md.in)**, **[podman-machine(1)](../source/markdown/podman-machine.1.md)**
176+
177+
Apple's [launchd documentation](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)

0 commit comments

Comments
 (0)