Running kinhin on a rented Mac
Run a kinhin fleet on a Mac you rent by the month instead of one on your desk: a colocated Mac mini or a bare-metal cloud Mac. This is also how a team or consultancy can run CI for someone else: one dedicated Mac per customer, their own forge token, no shared hardware.
kinhin is a single-owner tool: one Mac, one set of forge tokens, one operator. Renting a Mac does not change that. You get a machine without having to own or host one, and everything else on this page is the normal install and setup with a few remote-specific steps.
Choosing a host#
Any provider that gives you a dedicated Apple Silicon Mac with a GUI login session works. Compare current prices and terms on each provider's own page; they change often.
| Option | Billing shape | Notes |
|---|---|---|
| Mac mini colocation/rent | Monthly | Cheapest per month for a standing fleet (for example MacStadium) |
| Apple Silicon bare metal | Monthly or hourly, by provider | Check the provider's minimum lease; Apple's license sets one for hosted Macs |
| AWS EC2 Mac | Per hour, with a 24 h minimum | Dedicated host; fine for bursts, costly for an always-on fleet |
Sizing is the same as for a Mac on your desk: see Hardware requirements & sizing.
Remember the macOS ceiling: two concurrent macOS VMs per Mac, whatever the hardware. More
macOS concurrency means more Macs (see running on multiple Macs)
or runners_per_vm.
Bootstrap#
SSH in as the Mac's admin user and run the bootstrap script from a checkout of this repository:
ssh admin@your-mac 'bash -s' < scripts/bootstrap-rented-mac.shIt checks the host (Apple Silicon, macOS 15+, Homebrew), installs Tart and kinhin if they are
missing, creates a starter config.yaml, and prints the remaining steps. It is idempotent, and it
never touches a token.
Configure and authenticate#
Edit ~/Library/Application Support/Kinhin/config.yaml: set the accounts: entry for the
customer's forge and the labels their jobs request. Then, in an SSH session on the Mac:
# Over plain ssh the login Keychain is locked; unlock it for this session
security unlock-keychain ~/Library/Keychains/login.keychain-db
kinhin auth set # prompts for the token; use --gitlab, --gitea, ... for other forges
kinhin doctor # prerequisites, and how many VMs this Mac can hold
kinhin image prepare # once; bakes the runner base imageHave the customer create a token with the minimum scope their forge needs (see Forge support) and type it themselves, or hand it over through a channel you already trust. Do not put it in a script argument, an environment variable or a shell history.
Keep it running unattended#
kinhin daemon install installs a LaunchAgent, which runs in the user's GUI session. On a headless
rented Mac that means:
- Turn on automatic login for the admin user (System Settings → Users & Groups), so the session, and the login Keychain with it, exists after a reboot. Providers typically document this for their machines.
- Keep FileVault off, or you will need to unlock the disk by hand after every reboot. Weigh that against the data on the Mac: it holds only a forge token and throwaway VMs.
- If the fleet runs Linux jobs on apple/container or Docker, start those at login as well. See Start at login.
- Install the daemon from that session (a VNC or Screen Sharing login works), then confirm
with
kinhin statusover SSH.
kinhin daemon install
kinhin statusFinally, dispatch a workflow whose runs-on labels match the config and watch it with
kinhin watch.
What this does not give you#
- No multi-tenant control plane, remote API or billing. Each Mac is operated like any other kinhin host, over SSH.
- No GitHub App authentication yet: kinhin uses a PAT. JIT registration is used only in scale-set mode (see the GitHub notes).
- What has run for real is listed in Forge support.