You are reading the docs for v0.0.1-beta-6. Latest (main) →

Running kinhin on a rented Mac

View .mdEdit on GitHub

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.

← Back to README

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.

OptionBilling shapeNotes
Mac mini colocation/rentMonthlyCheapest per month for a standing fleet (for example MacStadium)
Apple Silicon bare metalMonthly or hourly, by providerCheck the provider's minimum lease; Apple's license sets one for hosted Macs
AWS EC2 MacPer hour, with a 24 h minimumDedicated 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.sh

It 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 image

Have 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 status over SSH.
kinhin daemon install
kinhin status

Finally, 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.