NERUDO
Sign in

macOS runner

The apple driver runs each job in a fresh Linux VM from Apple's container tool. This is the default driver on macOS.

Before you start

  • A Mac with Apple silicon and macOS 26.
  • Apple container 1.6.1 or later. Start its service with container system start.
  • The nerudo-runner binary for aarch64-apple-darwin. See Download the runner.
  • An OCI image that contains the job's tools. See Prepare a job image.

The runner does not install or start Apple container.

Register and test

  1. Enter nerudo-runner login --repo OWNER/REPO --name mac-ci --labels nerudo-ci.
  2. Get an owner or admin approval. See Register the runner.
  3. Enter nerudo-runner doctor --image IMAGE --cpus 4 --memory 8G.
  4. Make sure that each check shows ok or info.
  5. Enter nerudo-runner daemon --image IMAGE --cpus 4 --memory 8G --timeout 1800 --once.
  6. Start a CI job in the repository.

The --once daemon runs one job and stops. Examine the job's logs and result on the Pipelines tab.

Run the runner as a service

The launchd.py helper in cf/nerudo-runner/scripts makes a user LaunchAgent. It checks the state, the runtime, and the image before it writes the service file.

  1. Enter python3 cf/nerudo-runner/scripts/launchd.py prepare with the options in cf/nerudo-runner/README-macos.md.
  2. Examine the generated plist file.
  3. Enter python3 cf/nerudo-runner/scripts/launchd.py install --plist PLIST.
  4. Enter python3 cf/nerudo-runner/scripts/launchd.py status --plist PLIST.

The service starts again after a failure, with a 30-second interval. Its logs go to the --logs-dir directory.

Caution: The plist names the real path of Apple container, which includes its version. After an update of Apple container, prepare and install the service again.

Prepare a job image

The job VM has a read-only root filesystem. Steps can write only in /workspace and /tmp.

  1. Install the job's tools in the image: for example Git, compilers, and package managers.
  2. Set tool caches to paths in /workspace, for example CARGO_HOME=/workspace/.cache/cargo.
  3. Build the image with container build.
  4. Use the image's digest in the service, not a tag.

/tmp is a memory file system on this driver. Files in /tmp use the VM's memory.

Driver details

  • Each VM gets --cpus and --memory. Memory sizes use binary units: 8G is 8 GiB.
  • The workspace is a host directory. It has no size limit. Keep enough free disk on the Mac.
  • nerudo-runner status shows the current job, its VM, and its memory and CPU use.

See also Troubleshoot a runner and Runner limits.