Skip to content

.graft recipes

Graft builds golden images (a base + your toolchain + warm caches baked in) and clones them for both CI runners and dev boxes. The same image on your laptop and your runners means “works on my machine” stops being a thing.

Graft’s vocabulary here: a golden image is a sapling, the recipe that grows it is a seed (a .graft file), a dev box is a nest, and each running VM cloned from a sapling is a leaf.

Tart clones are APFS copy-on-write, so baked caches cost nothing per runner. This page covers the recipe format, the full field reference, and the caching strategy (bake vs. mount, and the read-only rule for shared caches).

A seed is a .graft file (YAML with declarative toolchain fields), or plain .yml/.json. The declarative fields compile into the right provisioning commands, so a whole toolchain is a few lines:

name: rn-detox
from: ghcr.io/cirruslabs/macos-tahoe-xcode:latest
node: "20.19.4" # fnm install + default + corepack + stable /usr/local/bin symlink
ruby: "3.3.5" # rbenv install + bundler
npm: [detox-cli]
brew: [applesimutils]
xcode-first-launch: true
warm-simulators: ["iPhone 17 Pro"]
# Escape hatch: raw bash for anything custom (runs last):
# run: |
# echo custom step
Terminal window
graft sapling template # print a starter seed
graft sapling render --seed image.graft # preview the compiled provisioning script
graft sapling grow --seed image.graft # clone, boot, provision in-guest, snapshot
graft sapling push rn-detox ghcr.io/you/rn-detox:latest # share with the team

from is any Tart ref (start from a cirruslabs/*-xcode base: Xcode and simulators are already baked). Declarative fields (node, ruby, brew, gems, npm, xcode-first-launch, warm-simulators) expand in order; run: (a | block or list) and script: (a file) are escape hatches that run after. Whatever the steps leave on disk is baked into the image. mounts (optional) expose host dirs during the build, e.g. to warm a project’s caches. See Example recipes for working seeds.

Reference the sapling from a pool ("image": "rn-detox") or with graft nest open --image rn-detox.

graft sapling grow also takes --name (override the sapling name from the seed), --network (override the seed’s network:), and --config / --profile (the GitHub App credentials used to clone private repos:).

Everything runs in one guest shell, in this order: env → toolchain → system config → script → run → prefetch → verify → cleanup. VM-shape fields are applied to the finished image with tart set. Run graft sapling template for a starter, or hover any field in the VS Code extension.

Toolchain (installed in this order — version managers are installed if missing):

Field Type Compiles to
xcode version sudo xcodes select <v>
node version fnm install/use/default + corepack + stable /usr/local/bin symlink
ruby version rbenv install/global + shims + bundler
python version pyenv install/global + pip upgrade
java version brew install openjdk@<v> + JavaVirtualMachines symlink
go boolean brew install go
rust toolchain rustup toolchain install + default (e.g. stable)
package-manager pnpm|yarn|bun corepack (pnpm/yarn) or brew (bun)
brew string[] brew install …
cocoapods version gem install cocoapods -v <v> (pair with ruby:)
fastlane boolean gem install fastlane
gems string[] gem install … --no-document
npm string[] npm install -g …
xcode-first-launch boolean sudo xcodebuild -runFirstLaunch
simulator-runtimes string[] xcodebuild -downloadPlatform <platform> (e.g. ["iOS 26"])
warm-simulators string[] cold-boot each once to warm caches, then shut down

System config (baked into the image):

Field Type Compiles to
env map export now + persist to /etc/zshenv (runner shells inherit)
git {user, email} git config --global user.name/.email
known-hosts string[] ssh-keyscan → ~/.ssh/known_hosts (no clone prompts)
write map (path→contents) write config files into the guest (.npmrc, .gemrc, …)
timezone string systemsetup -settimezone
hostname string scutil --set HostName/LocalHostName/ComputerName
disable-spotlight boolean mdutil -a -i off (CI perf)
disable-sleep boolean pmset -a sleep 0 … (long jobs)
description / labels string / map metadata baked to /etc/graft-image

Cache warming, verify, hygiene:

Field Type Compiles to
pod-repo-warm boolean pod repo update / pod setup
prefetch string[] commands run in the repo mount dir (bundle/yarn/pod install → baked in)
repos list clone repos into the guest, warm global caches, discard the source (see below)
ccache boolean | {max-size} brew install ccache + a path-independent config, filled by xcodebuild (see below) — a bare number for max-size (e.g. 20) is treated as gigabytes
verify string[] each must exit 0 at the end, or the build fails
cleanup boolean or object brew cleanup + clear non-warm caches → smaller image (see below)

cleanup: true shrinks the image but never undoes the cache warming above: it clears ~/Library/Caches/* except a default preserve list — CocoaPods, ccache, Xcode DerivedData, Swift Package Manager, and Yarn/npm — plus brew cleanup -s and Homebrew’s download cache. Add your own paths (relative to $HOME) with the object form:

cleanup:
preserve: [Library/Caches/MyThing]

Only the first path component under Library/Caches is ever matched, so a nested preserve entry (e.g. Library/Caches/MyThing/nested) preserves the whole Library/Caches/MyThing top-level directory, not just the nested path.

VM shape (via tart set, inherited by every clone):

Field Type Compiles to
cpu int tart set --cpu
memory int (MB) tart set --memory
disk int (GB) tart set --disk-size (grow-only)
display WxH tart set --display

Escape hatches: script (a file, runs before run), run (a | block or list), mounts (host dirs shared during the build), os (macos|linux), network (nat default, bridged:<iface>, or softnet).

Networking behind a corporate proxy (Zscaler etc.): the default shared NAT can be blocked or mangled. Set network: bridged:en0 (your active interface — tart run --net-bridged=list lists them) to put the VM directly on the LAN. The same applies to a runner pool (network: bridged:en0 in the pool config) and graft nest open --network bridged:en0.

Pre-caching repos (repos:) — warm caches, no workflow changes

Section titled “Pre-caching repos (repos:) — warm caches, no workflow changes”

A runner job runs actions/checkout, which clones into $GITHUB_WORKSPACE (_work/<repo>/<repo>) — not wherever the image baked anything. So a baked working tree at, say, ~/app does not link to the job. What does transfer is the global package-manager caches (yarn/npm download cache, CocoaPods CDN + spec repo, bundler gems, SPM): they live in $HOME, are path-independent, and the job’s normal yarn install / pod install / bundle install just hit them — killing the network-fetch cost with zero workflow changes.

repos: automates exactly that warming: clone → run installs → discard the working tree, keeping only the warmed $HOME caches. No source is baked into the image.

For a React Native iOS team, repos: + path: + ccache: together get a job’s xcodebuild down to a couple of minutes — see React Native iOS fast builds for the full recipe and the paired clean: false / conditional-pod-install workflow.

known-hosts: [github.com] # so the clone doesn't prompt on the host key
mounts:
- { name: ssh, source: "~/.ssh", readOnly: true } # credentials — NOT baked (mounts never are)
repos:
- url: git@github.com:your-org/app.git
ref: main # branch or tag (shallow clone)
ssh-key: "/Volumes/My Shared Files/ssh/id_ed25519" # the mounted key
run:
- bundle install
- yarn install
- cd ios && bundle exec pod install

Private repos: the build VM needs credentials to clone. Mount your key/credentials read-only — because mounts are never written into the image, nothing sensitive is baked — and point ssh-key at the mounted path. (Public repos need neither.)

Make sure your tools use a global cache, or there’s nothing to warm: Yarn Berry defaults to a project-local .yarn/cache (discarded with the source). Force a global cache with env: { YARN_ENABLE_GLOBAL_CACHE: "true" } (or use yarn classic / bundler’s default global gem dir / CocoaPods’ global CDN cache, which already qualify).

The default (above) discards the clone, so node_modules, Pods/, and Xcode DerivedData still start cold in the job — DerivedData in particular is keyed by a hash of the project’s path, and a discarded-then-recloned tree never lands at the same path twice. Set path: on a repo to keep the clone at a stable guest path instead of rm -rf-ing it, so those path-keyed caches bake straight into the image:

repos:
- url: git@github.com:your-org/app.git
ref: main
ssh-key: "/Volumes/My Shared Files/ssh/id_ed25519"
path: workspace # keep the tree instead of discarding it
run:
- yarn install
- cd ios && bundle exec pod install
- cd ios && xcodebuild -workspace App.xcworkspace -scheme App build # warms DerivedData at this path

path: workspace resolves to the exact directory actions/checkout will use in a job — $HOME/actions-runner/_work/<repo>/<repo> — so the checkout step lands on top of the baked tree instead of somewhere else, and DerivedData’s path hash matches. Any other value is used literally (a leading ~ expands to $HOME) if you’d rather pin a custom location. Rebaking an image (e.g. a nightly rebuild) refreshes an existing kept tree with git fetch + reset --hard rather than re-cloning from scratch.

Two workflow adjustments are required for the kept tree to actually help:

  • actions/checkout needs clean: false. Its default behavior runs git clean -ffdx before checking out, which deletes anything not tracked by git — including node_modules, Pods/, and .yarn/ — wiping out exactly what you baked.
  • Skip pod install when Podfile.lock is unchanged. CocoaPods’ install is not idempotent-cheap the way yarn install is; if ios/Podfile.lock matches what’s already in the baked Pods/, skip the step entirely rather than re-running it.

For a github.com repo, graft also normalises the kept clone’s origin to the bare https://github.com/<owner>/<name> (no .git) that actions/checkout expects when the job uses its default token-based auth — otherwise checkout sees a mismatched origin (whatever form you cloned with — ssh, .git-suffixed https, etc.) and wipes the directory before re-cloning cold, even with clean: false. If your workflow instead passes checkout its own ssh-key: input, it expects origin in the git@github.com: scp form instead, which graft’s normalisation doesn’t match — in that case, point path: at a literal path and accept a re-clone each run, or don’t pass checkout an ssh-key: input.

Tradeoff: with path: set, the repo’s source is now baked into the image, not just its caches. That’s fine for a private runner pool, but matters if the image is ever pushed to Orchard or another registry — anyone who can pull the image can read the source. Don’t use path: on an image you intend to share or publish.

repos:/prefetch: warm caches keyed to a path — Xcode’s DerivedData is fast but fragile: it’s invalidated wholesale (a scheme change, a clean build, a bump in Xcode) and it’s keyed to where the build ran, so a bake-time path doesn’t help a job’s ~/actions-runner/_work/<repo>/<repo> checkout. ccache: is the floor under that: a content-addressed object store, cached per translation unit, on the image disk — so every ObjC/C++ pod is still a hit even when DerivedData gets thrown away. It does not cover Swift — Xcode’s own incremental build (via DerivedData) is what makes Swift fast; ccache only ever sees the ObjC/C++ compiler invocations React Native’s pods emit (and any C/C++/Objective-C++ of your own).

ccache: true # or: ccache: { max-size: "40G" } (default 20G)

When enabled, graft (after brew: packages install):

  • brew install ccache (idempotent)

  • writes ccache’s macOS default config, $HOME/Library/Preferences/ccache/ccache.conf. This is a strict superset of React Native’s own shipped scripts/xcode/ccache.conf — see below for why that matters:

    cache_dir = $HOME/Library/Caches/ccache
    max_size = 20G
    base_dir = $HOME
    hash_dir = false
    compiler_check = content
    compression = false
    depend_mode = true
    file_clone = true
    inode_cache = true
    sloppiness = clang_index_store,file_stat_matches,include_file_ctime,include_file_mtime,ivfsoverlay,pch_defines,modules,system_headers,time_macros

    base_dir + hash_dir = false make cache hits path-independent — a hit from the bake path still hits at the job’s _work/... path. compiler_check = content means an Xcode point update doesn’t silently invalidate the whole store (it hashes the actual compiler, not its mtime/path). compression = false trades a little disk for removing the only compute cost a cache hit has — and disk is cheap on an APFS clone. cache_dir is pinned to ~/Library/Caches/ccache so the store’s location is deterministic, and cleanup: true preserves it (see the cleanup preserve list above). The rest — depend_mode/file_clone/inode_cache and the sloppiness list — is carried over verbatim from RN’s own config: CocoaPods targets default CLANG_ENABLE_MODULES=YES, and ccache refuses to cache -fmodules compiles unless sloppiness=modules is paired with direct + depend mode; Xcode passes -index-store-path under DerivedData (which differs bake vs. job, hence clang_index_store) and -ivfsoverlay for mixed ObjC/Swift pods.

  • at the end of the prefetch/repos phase — after a warm pod install && xcodebuild would have filled the store — runs ccache -s so the bake log shows the fill.

graft does not export CC/CXX — xcodebuild ignores them; wiring ccache into your build is a Podfile change you own, via React Native’s post-install hook:

react_native_post_install(
installer,
config[:reactNativePath],
:mac_catalyst_enabled => false,
:ccache_enabled => true
)
# Point RN's ccache wrapper (scripts/xcode/ccache-clang.sh) at graft's config instead of
# its own. The wrapper only sets CCACHE_CONFIGPATH when it isn't already set — but once
# CCACHE_CONFIGPATH *is* set, ccache reads that file and ONLY that file (per the ccache
# manual), so without this, graft's baked config is never read and every setting above is
# dead. graft's config is a strict superset of RN's own, so pointing here doesn't regress
# any of RN's tuning.
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['CCACHE_CONFIGPATH'] = "#{ENV['HOME']}/Library/Preferences/ccache/ccache.conf"
end
end

To read the hit rate from a job, add ccache -s as a step after the build — a healthy warm image should show most ObjC/C++ compiles as cache hits.

Recommended: workspace-relative DerivedData. base_dir rewriting only makes a hit path-independent when the other absolute paths baked into a translation unit — notably the -F/-I search paths into DerivedData’s Build/Products — are also under base_dir and identical relative to the checkout. With Xcode’s default DerivedData location, ~/Library/Developer/Xcode/DerivedData/<Name>-<hash-of-project-path>, the hash means those paths differ whenever the bake and job checkout paths differ, defeating the rewrite for anything that references DerivedData directly. Pass -derivedDataPath ios/build (workspace-relative) to xcodebuild at both bake time (in a repos[].run step) and in the job — that keeps the build directory inside the checked-out tree, so ccache’s path rewriting covers it too, and makes the DerivedData path-hash mismatch moot in the first place.

Why baking caches is (almost) free: APFS copy-on-write

Section titled “Why baking caches is (almost) free: APFS copy-on-write”

tart clone uses APFS clonefile — the clone’s disk shares the same physical blocks as the source image; no data is copied. Copy-on-write then diverges per block, on writes only:

  • Reading node_modules / Pods / DerivedData → shared blocks. Free, instant, no duplication.
  • Writing (a pod install delta, a build) → only the changed blocks get a private copy, in the clone. The golden image is never touched.
cirruslabs xcode base
└─ build → rn-detox (+ Pods / node_modules / DerivedData blocks)
├─ clone → runner-abc (writable; diverges only where it writes)
└─ clone → runner-def (its own divergence)

So bake your heavy, slow-moving caches into the image and every ephemeral runner gets them instantly, privately, and writably — diverging only on the delta. Two concurrent runners can’t corrupt each other, because each write lands in its own block. “Refresh the caches” = rebuild the image on a schedule (e.g. nightly); the job’s incremental install/build catches up the small drift since the last build.

Only works because ~/.tart is on an APFS volume — which it is by default.

What to bake: Pods, node_modules, DerivedData, and HOME caches (~/.npm, ~/Library/Caches/CocoaPods). HOME caches bake automatically when a run step like npm ci / pod install runs in the guest; project-dir caches (node_modules, Pods) bake if the project is present during the build (clone the repo in a run step, or mount it via mounts).

Host mounts (the escape hatch for volatile caches)

Section titled “Host mounts (the escape hatch for volatile caches)”

When a cache moves faster than your rebuild cadence, mount it from the host instead of baking it. Pools take a mounts list; graft pool add takes --mount:

Terminal window
graft pool add --name mac --image rn-detox \
--mount pods:/opt/graft-cache/pods:ro \
--mount npm:/opt/graft-cache/npm:ro
"mounts": [
{ "name": "pods", "source": "/opt/graft-cache/pods", "readOnly": true }
]

Each appears in the guest at /Volumes/My Shared Files/<name>.

Ephemeral runners are supposed to be isolated. A read-write cache mounted into two concurrent runners will corrupt each other (two pod installs writing the same dir). So:

  • Read-only, shared (:ro) → safe. Pre-warm the cache out of band; runners get fast warm reads, zero corruption risk. This is the recommended default.
  • Read-write → must be per-runner (its own directory), never shared. CocoaPods and DerivedData especially want RO-shared. npm’s content-addressed store tolerates RW better, but RO is still safest.

For most setups: bake into the image (CoW gives you a private writable copy for free), and use RO mounts only for the volatile long-tail.

Command What it does
graft sapling list List local images and VMs.
graft sapling inspect <image> Boot an image and report the tools and versions baked into it.
graft sapling rm <name> Delete a local image or VM.
graft sapling prune [--force] Remove leftover throwaway build VMs from failed builds. --force also removes running build VMs, which may kill an in-progress build.
graft sapling push <name> <ref> Push a local image to a registry, e.g. ghcr.io/me/rn-detox:latest.
graft sapling pull <ref> Pull an image from a registry.
graft sapling template Print a starter seed.
graft nest CI (graft arborist tend)
VM persistent (or --ephemeral) always ephemeral
repo host-mounted RW ($PWD) cloned into the guest
mounts your repo + --mount optional RO caches
image the same sapling the same sapling

Same image, two workflows: your local box and your runners stay identical.