Advanced

• One runner per job. Each runner registers with GitHub just in time, takes one job and exits. Its folder is wiped and a fresh runner starts.
• Sized to the machine. Each runner budgets 4 GB of memory, 15 GB of disk and 2 performance cores; 4 GB of memory and 20 GB of disk stay free for the system. At least 1 runner, at most 32. codemany capacity prints how many fit.
• Repos share runners. Each repo keeps a warm runner while there are spares; idle runners move to repos with waiting jobs. Busy runners are never touched.
• Keep-awake while jobs run (or while runners are online, or never), until 2 minutes after the last job.
• Crashes and hangs. A crashed runner is replaced, backing off from 5 seconds up to 5 minutes. A runner offline for 2 minutes is stopped, with leftover processes such as simulators, and replaced.
• Updates wait until running jobs finish. GitHub errors and rate limits never stop a running job.

A job's runs-on lists labels, and GitHub gives the job to a runner that has every one of them. Codemany's runners register with the labels shown in Settings, so paste the workflow example into a job and it runs on your Mac. Add xcode-… or docker only when a job needs them: each label you add narrows which runners can take it.

self-hosted

Every runner GitHub doesn't host carries self-hosted. Put it first in runs-on so a job never lands on a GitHub-hosted machine by mistake. On its own it matches any self-hosted runner in the repository, including ones that aren't Codemany's, so pair it with codemany.

macOS

The runner's operating system, added by GitHub's runner on every Mac. Ask for it to keep a job off any Linux or Windows self-hosted runners you also have, for example runs-on: [self-hosted, macOS].

ARM64

The CPU architecture, added by GitHub's runner. Codemany runs on Apple silicon, so it is always ARM64. Ask for it when a job builds or runs native code for one architecture, such as a simulator build or a Docker image that must match the host.

codemany

Codemany adds it to every runner it starts. runs-on: [self-hosted, codemany] sends a job to your Mac's fleet and nowhere else. Each job gets a fresh, single-use runner that Codemany registers just in time and removes when the job ends.

xcode-<version>

Follows the Xcode chosen with xcode-select, for example xcode-26.0. Pin a job to it when the build needs that Xcode's SDKs or Swift version. When you switch Xcode, new runners carry the new label, so jobs asking for the old one wait instead of building with the wrong toolchain.

docker

Present only while a Docker engine (Docker Desktop or Colima) answers on your Mac. Jobs that run docker build, docker compose or service containers should ask for it, so they wait for a runner that can run them. Turn on Keep Docker running in Settings › Tools to keep the label steady.

On Linux, runners carry Linux and X64 or ARM64 instead of macOS.

• Checked every 30 minutes, and on demand in Settings › Tools or with codemany doctor. New runners pick up changes.
• Installs on request, as your user, never root: Colima (never Docker Desktop), and Homebrew packages such as CocoaPods, fastlane, gh, xcbeautify, SwiftLint, XcodeGen and Git LFS.
• Keep Docker running (off by default) checks Docker every 60 seconds and restarts it when it is down.
• Shared tool cache. Downloads from actions/setup-go, setup-node, setup-python and other actions/setup-* steps stay in ~/.codemany/toolcache between jobs, pruned past 20 GB. Pre-warm fills it with the versions your workflows ask for.

codemany integrations list
codemany integrations install <id>   # or update, start, cancel
codemany integrations prewarm

The two opt-in modes never fall back to running a job as you, and their caches start cold. On a Mac, turn on Settings › Isolation › Separate user per runner. From a terminal:

codemany isolation status
codemany isolation user   # or host, or vm

On Linux, install the helper first: sudo codemany system-setup --user "$USER" --user-isolation. The vm mode needs KVM (ls /dev/kvm). Changing modes restarts the background service and stops running jobs.

• apt (Debian, Ubuntu) keeps it updated with apt upgrade. Add the repository, after checking the key's fingerprint is 92EA E8F4 E140 E71F E883 C291 DBC1 D871 7AE5 E521:

curl --proto '=https' --tlsv1.2 -fsSLo codemany.gpg \
  https://codemany.com/download/linux/apt/codemany-archive-keyring.gpg
gpg --show-keys --with-colons codemany.gpg | grep -qx 'fpr:::::::::92EAE8F4E140E71FE883C291DBC1D8717AE5E521:' \
  && sudo install -m 644 codemany.gpg /usr/share/keyrings/codemany-archive-keyring.gpg \
  || echo "codemany.gpg is not Codemany's key: stop" >&2
echo "deb [signed-by=/usr/share/keyrings/codemany-archive-keyring.gpg] https://codemany.com/download/linux/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/codemany.list
sudo apt update && sudo apt install codemany   # and codemany-desktop on a desktop

• Setup over SSH: ssh -L 18825:127.0.0.1:8825 you@server, then codemany setup-link --port 18825 on the server.
• Setup in a terminal: codemany setup --target your-org/your-repo --token-from-gh, then codemany install-service. It runs as a systemd user service and keeps running after you log out.
• Restart without cutting a job short: codemany drain --wait && systemctl --user restart codemany && codemany resume.
• Logs: journalctl --user -u codemany. Health: codemany doctor.
• Uninstall: codemany uninstall-service, remove /usr/local/bin/codemany (or sudo apt remove codemany), then rm -rf ~/.codemany ~/.local/share/com.codemany.cli.

Sizes: 4 threads and 16 GB run 2 jobs; 8 threads and 32 GB run 4; 16 threads and 64 GB run 8.

Machines on one network can pair, so each one can open and control the others. GitHub still hands each job to one free runner; there is no leader.

• Pair: on your Mac, open Machines and choose Add to the fleet… next to a nearby machine, then type the code it shows (codemany pair prints it on a server). Or: codemany machines add 192.168.1.50:8825 CODE.
• Codes have 8 characters, last 10 minutes and allow 5 tries. Only an admin of that machine can see one.
• Manage: codemany machines list, rename ID NAME, remove ID.
• Trust: every request between machines is signed and can't be replayed. Pairing runs over plain HTTP, so pair on a network you trust.

• Setup: the provider creates an Ubuntu 24.04 machine. Codemany installs itself from the apt repository, takes a seat, and joins your fleet over SSH.
• Locked down: only SSH is open, key-only, with a host key the app pins. Each runner is its own user, and jobs can't reach the cloud's metadata service.
• Only its own machines: Codemany only touches machines labelled codemany=managed (codemany-managed tag on DigitalOcean).
• Manage it from the Mac that created it; only that machine holds the SSH key.
• Remove deletes the machine at the provider, removes its runners from GitHub, frees its seat and forgets its key.

• Sign in at console.codemany.com with GitHub. It asks only for read:org. Sessions last 1 hour.
• It shows each machine, its runners, its repos, its 50 newest runs and its cloud machines.
• Commands: drain, resume, stop or start runners, change the runner count, add or remove cloud machines. Only the seat's account, an organization's admins or whoever pays can send them. A machine runs them the next time it reports, usually within a minute.
• Turn it off in Settings › This Mac, in the dashboard's Settings › This machine, or with codemany console off.

codemany comes with the Mac app and is the whole package on Linux. codemany help lists everything.