Add a Mac rig

Use your own account and an existing project. A person who contributes compute can remain a project viewer; a project operator separately approves the machine.

1. Accept project access

Ask the project admin to open Projects, choose the project, then Access → Invite Member. Viewer is sufficient for a capacity contributor. The admin copies the generated invitation link to you; project invitations do not send email automatically.

Open the link and sign in with your own matching Google, GitHub or email account. Review the project and role, then accept. An expired or revoked invitation needs the admin to provide a new one. Project access and organisation membership are separate.

2. Install the approved Mac app and runtime

Use Apple menu → About This Mac to identify the chip. Download the project-approved release from Desktop Agent downloads: Apple Silicon uses arm64, Intel uses x86_64. Open the DMG, drag CuttlefishAgent.app into Applications and eject it. Keep macOS signature and Gatekeeper checks enabled.

The signed, notarized latest desktop channel was 0.2.61 when this guide was qualified on 10 October 2026. The separately published 0.2.62 candidate is not a claim of installed adoption. Desktop and standalone CLI versions are separate.

Install the runtime approved by your project owner before accepting work. Micropod’s native Apple runtime requires an Apple Silicon Mac and its supported API to be healthy. Intel Macs need a separately qualified compatible runtime, such as Docker; an Intel agent download does not qualify Apple’s runtime on Intel.

3. Install the CLI that supports approval requests

The desktop app does not include a standalone cuttle. Use the official CLI installer after your operator confirms the approved contributor release is published. Legacy 0.2.25 has join-code enrollment, but does not support the request command below. Do not substitute it or disable download verification.

mkdir -p "$HOME/.local/bin"
installer="$(mktemp)"
curl -fsSL https://app.cuttlefish.sh/install.sh -o "$installer"
CUTTLE_INSTALL_DIR="$HOME/.local/bin" sh "$installer"
rm "$installer"
export PATH="$HOME/.local/bin:$PATH"
cuttle --version
cuttle agent enroll --help

Help must include --request. The operator’s approval CLI must include --capacity-contributor. If either is missing, stop and ask for the qualified release. Hosted Cuttlefish is the default; a custom server is only needed for self-hosting. The new automatic cuttle setup browser flow requires separate server activation, so this guide does not depend on it.

4. Request approval from this Mac

Open the rig setup guide, select your authorised project and choose a unique rig name. On the Mac, replace the example project and name below with those approved by the owner:

cuttle agent enroll --request --project YOUR_PROJECT --name teammate-mac-01

This command needs no human CLI login or copied operator token. Keep it running while it prints the request code and key fingerprint and waits. Share the code and fingerprint with your operator; never share the machine’s private key. An interrupted request can be resumed using the existing --key-file option with a private file kept only on that Mac.

5. Have the operator approve the matching machine

The operator opens Rigs in the intended project and compares the owner, project, name and key fingerprint. The operator selects Capacity contributor — viewer control API credential, reviews the pool and capabilities, and approves only the matching new request.

cuttle login --project YOUR_PROJECT
cuttle --project YOUR_PROJECT runners approve CODE --capacity-contributor

The machine receives a project-scoped credential through its enrollment key. Its control API role is viewer: it can read project results and execute admitted work through the runner channel, but cannot mutate workflows, start jobs or mint credentials. Your personal membership stays unchanged. Contributor approval cannot replace an existing credential or grant org-wide scope; use a new name.

The host owner can inspect private code and secrets delivered to jobs. The operator must agree which workloads may run here before admission. A contributor credential is not isolation from the host owner. Legacy approval without this option still issues an operator machine credential; do not use that as a shortcut or elevate a human viewer merely to add capacity.

6. Verify the rig and its work path

After approval, launch CuttlefishAgent from Applications. The operator checks the expected identity, project, fresh heartbeat, runtime, chip and available resources in Rigs. These are availability checks. Before admitting private workloads, the workflow owner qualifies one harmless job pinned to this machine and verifies its actual runner ID and execution platform.

Cuttlefish enrollment does not register a GitHub self-hosted runner or add the Mac to an ARC scale set. Jobs selecting an ARC runner name continue to use that separate pool. The repository owner must explicitly select and qualify a supported Mac or native Cuttlefish lane. Do not copy shared labels, change repository routing, or grant persistent GitHub runner authority as part of installation.

Organisation invitation email

Organisation email invitations and verified-email automatic acceptance require a separately approved mail provider and server activation. They remain disabled on the hosted service at this guide’s qualification checkpoint. Use the existing manual project invitation link. An organisation invitation never grants access to existing projects or approves a rig.