macOS Startup

macOS Startup

EPAR's pool up command is a foreground supervisor. On a personal Mac, you can start it after login with either a .command file in macOS Open at Login or a user launchd LaunchAgent.

The .command approach is easy to test and easy to remove. It opens a Terminal window, and closing that window stops EPAR. Use launchd when you want a quieter background service.

Open At Login With A .command File

Copy the example startup script into ignored local state:

cd /path/to/ephemeral-action-runner
mkdir -p .local
cp examples/macos/start-epar.command .local/start-epar.command
chmod +x .local/start-epar.command

Build the EPAR binary and create .local/config.yml before starting the script:

go build -o ./bin/ephemeral-action-runner ./cmd/ephemeral-action-runner
test -f .local/config.yml

Double-click .local/start-epar.command in Finder or run it from Terminal:

.local/start-epar.command

The script:

• finds the EPAR repo root when it lives under the repo, such as .local/start-epar.command;
• uses .local/config.yml by default;
• waits for Docker to become ready before starting EPAR;
• starts an existing epar-dockerhub-cache mirror container if one exists;
• runs ephemeral-action-runner pool up.

To start it automatically after login, open macOS System Settings, go to General, then Login Items & Extensions, then add .local/start-epar.command under Open at Login.

This starts only after the user logs in. It is not a boot-time system daemon.

Customization

You can edit the copied .local/start-epar.command file or set environment variables near the top of your local copy:

export EPAR_ROOT="/path/to/ephemeral-action-runner"
export EPAR_CONFIG="${EPAR_ROOT}/.local/config.yml"
export EPAR_BIN="${EPAR_ROOT}/bin/ephemeral-action-runner"
export EPAR_MIRROR_CONTAINER="epar-dockerhub-cache"
export EPAR_WAIT_FOR_DOCKER=1
export EPAR_DOCKER_WAIT_ATTEMPTS=120

Set EPAR_WAIT_FOR_DOCKER=0 only when the selected provider does not need Docker at startup.

If you use the optional Docker registry mirror, create the mirror container separately. The startup script starts the container if it already exists, but it does not create or configure the mirror service.

launchd Alternative

For a background service without a Terminal window, create a user LaunchAgent that runs the same .local/start-epar.command script.

Example ~/Library/LaunchAgents/com.example.epar.plist:

<?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.example.epar</string>

    <key>ProgramArguments</key>
    <array>
      <string>/path/to/ephemeral-action-runner/.local/start-epar.command</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>WorkingDirectory</key>
    <string>/path/to/ephemeral-action-runner</string>

    <key>StandardOutPath</key>
    <string>/path/to/ephemeral-action-runner/work/logs/launchd.out.log</string>

    <key>StandardErrorPath</key>
    <string>/path/to/ephemeral-action-runner/work/logs/launchd.err.log</string>
  </dict>
</plist>

Load it:

launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.example.epar.plist
launchctl enable "gui/$(id -u)/com.example.epar"
launchctl kickstart -k "gui/$(id -u)/com.example.epar"

Stop and remove it:

launchctl bootout "gui/$(id -u)" ~/Library/LaunchAgents/com.example.epar.plist

Operational Notes

• pool up cleans up prefixed instances when it exits. Use --keep-on-exit only for debugging.
• If Docker Desktop, OrbStack, or Docker Engine cannot start, the script exits before EPAR starts.
• For Docker-DinD, the host Docker runtime must support privileged containers.
• For Tart-only pools that do not use host Docker or a local registry mirror, disable the Docker wait in your local copy.