Repository navigation
Releases
v0.5.6 — fast React Native iOS builds
Fast React Native iOS builds
Everything a warm RN iOS job needs now bakes into the image and survives the shrink step — no actions/cache zip/unzip anywhere.
repos: path:keeps a precache clone at a stable path.path: workspaceresolves to the runner's_work/<repo>/<repo>, sonode_modules,Pods/, and a warm DerivedData land exactly whereactions/checkoutwill look.originis normalised so checkout fetches on top of the baked tree instead of wiping it. (GFT-34, #22)cleanup: truepreserves warm caches — CocoaPods, ccache, DerivedData, SPM, yarn/npm — instead of wiping~/Library/Caches.cleanup: { preserve: [...] }adds your own. (GFT-35, #24)ccache: trueinstalls and configures ccache with a path-independent, React-Native-superset config, and printsccache -safter the bake fill. Point RN's wrapper at it with oneCCACHE_CONFIGPATHbuild setting in your Podfile (see docs). (GFT-36, #23)examples/images/rn-ios.graft+docs/rn-ios-fast-builds.md— a reference image and workflow:clean: falseon checkout,pod installgated on a baked Podfile.lock hash, workspace-relative DerivedData. (GFT-37, #25)- VS Code extension schema and hover docs cover the new keys.
Requires a workflow with actions/checkout clean: false to keep the baked tree — see the docs.
v0.5.5 — Sakura 🌸 (self-contained tend reconnect)
Highlights
Self-contained reconnect for graft arborist tend (GFT-33). No more un-reattachable foreground supervisor — and no launchd/nohup needed.
- Detached by default:
tendbackgrounds the supervisor as its own session (survives the launching terminal closing) and attaches a live view. Ctrl-C detaches the view; the supervisor keeps tending. graft arborist attach: re-attach a faithful, read-only dashboard any time (polls the supervisor's persisted per-slot phases — no IPC).- Collision-safe: starting
tendwhile one is already running detects it and offers reconnect / kill / cancel instead of silently double-supervising. --foregroundkeeps the old blocking behavior;--daemon(launchd) unchanged.
Install
brew update && brew upgrade graft # CLINote: the menu-bar app cask (graft-app) is published separately and requires notarization.
v0.5.4 — Sakura 🌸 (registry image picker)
Feature release on top of v0.5.3 "Sakura".
Added
- Registry image picker — browse a registry and pull an image not yet on disk instead of typing the ref by hand, across the desktop app's pool editor and the CLI picker.
- Configurable catalog at
~/.graft/registries.json— seeded with the cirruslabs bases but fully yours: add or remove any repository. The app isn't bound to cirruslabs' naming, and the same catalog backs the GUI and the CLI. (Registries don't expose a repo list, so "browse" is your curated set; tags come from the anonymous OCI pull-token flow, which works for any public repo.) - 3-panel browser — Sources → Images → Versions: sources grouped by registry host, images newest-first, versions fetched live with a skeleton-loading state. Your local on-disk images show up as a "local" source, and "on disk" badges flag what's already cached.
- Saplings → Pull… now opens the same browser (replacing the old plain-ref text box), and the CLI
graft pool new/graft initpicker gained a "search a registry…" option.
Changed
- Growing a sapling lives in Seeds now — the Saplings tab is purely pull + manage on-disk images (its Grow menu + build-network field moved out).
- Pool-editor Image field is single-line (no more wrap).
- Seed editor: the precache-repo "run after clone" box is now labeled (was an unlabeled text area).
Notes
- CLI:
graft-0.5.4-arm64-macos.tar.gz(Apple Silicon). - Desktop app:
Graft-0.5.4.zip(notarized) — attached separately.
Full changelog: v0.5.3...v0.5.4
v0.5.3 — Sakura 🌸 (headless secrets)
Patch release on top of v0.5.0 "Sakura".
Added
- File-based secret store —
"secrets": { "store": "file", "path": "~/.graft/keys" }reads each App key from a plain<app-id>.pemfile instead of the macOS keychain. The keychain is hostile on headless SSH hosts (locks, no GUI to unlock, root/session mismatches); achmod 600PEM just works. Warns on loose file perms;check/validatereport the real source. graft sapling grow --network— set the build-VM network (e.g.bridged:en8) per host instead of baking it into the shareable seed. Also a host-level "Build network" field in the desktop app (Seeds + Saplings).
Fixed
- Login-scope keychain isolation — login-scope operations now confine to the login keychain, so the idempotent delete in
secrets importcan't collide with a System-keychain item (theerrSecWrPerm"Write permissions error"). - Silenced two unused-result build warnings.
Notes
- CLI:
graft-0.5.3-arm64-macos.tar.gz(Apple Silicon). - Desktop app:
Graft-0.5.3.zip(notarized) — attached separately.
Full changelog: v0.5.2...v0.5.3
v0.5.2 — Sakura 🌸 (App-token precache)
Patch release on top of v0.5.0 "Sakura".
Added
-
Private repo cache-warming with zero deploy keys.
graft sapling growcan now pre-warm dependency caches from a private repo in a.graftseed'srepos:block by authenticating as graft's own GitHub App — no SSH deploy key, no org coordination. graft mints a short-lived installation token and clones over HTTPS via a command-scopedgit -c http.extraheader(the same mechanismactions/checkoutuses), so nothing auth-bearing bakes into the image. An explicitssh-key:still overrides; public repos clone anonymously.repos: - url: https://github.com/me/app.git ref: main run: [yarn install --frozen-lockfile] # auto-authed as graft's App
Notes
- CLI:
graft-0.5.2-arm64-macos.tar.gz(Apple Silicon). - Desktop app:
Graft-0.5.2.zip(notarized) — attached separately.
Full changelog: v0.5.1...v0.5.2
v0.5.1 — Sakura 🌸
Patch release on top of v0.5.0 "Sakura".
Fixed
graft arborist tendon EC2 Mac dedicated hosts over plain SSH. Leaves were cloned but never booted (sat atstopped) while the supervisor looped boot → IP timeout → replace. Root cause:tart runwas launched vianohup … &, and on these hostsnohupaborts withcan't detach from console: Inappropriate ioctl for device(ENOTTY) before ever starting the VM. graft no longer usesnohupto detach the boot.- Boot failures are no longer swallowed. A detached
tart runnow logs to~/.graft/logs/<vm>.log; when a leaf fails to get an IP, graft surfaces the realtartoutput in the error instead of a bare timeout. Logs are cleaned up on release.
Notes
- CLI:
graft-0.5.1-arm64-macos.tar.gz(Apple Silicon). - Desktop app:
Graft-0.5.1.zip(notarized) — attached separately.
Full changelog: v0.5.0...v0.5.1
v0.5.0 — Sakura 🌸
Graft v0.5.0 — Sakura 🌸
The release where Graft grew a full desktop app — and the supervisor learned to scale itself.
TL;DR —
Graft.appis now a real windowed app: manage profiles/pools/secrets, watch the live runner pool and your Orchard fleet, run dev boxes, build images, and compose.graftrecipes in a structured builder — including creating a GitHub App end-to-end from inside the app. Under the hood, the runner supervisor became elastic (it self-fills and drains as fleet capacity changes, no restart) and several reliability sharp edges are gone.
🌸 Why "Sakura"?
Graft releases are named for tree species. Sakura (桜) — the Japanese cherry blossom — is the tree you plant purely to be looked at: no fruit, no timber, just the bloom. Fitting for the release where Graft grew a face — the part that's finally lovely to look at. (v0.4.0 was Aspen: one clonal organism sharing a root system, resprouting dead stems — the self-healing supervisor.)
🌸 The desktop app (the headline)
The menu-bar app grew into a full sidebar app — every surface that used to need the CLI or hand-edited JSON is now point-and-click:
- Dashboard — live runners/leaves with phase + age, start/stop, orphan banner.
- Canopy — the Orchard fleet at a glance: trunk reachability, capacity bar, branches (live/paused/stale + last-seen), and the leaves Graft owns.
- Nests — dev boxes: open in VS Code (Remote-SSH) or a shell, start/stop, open the VM's screen, and live provisioning status (creating → cloning → ready) instead of a misleading instant "running".
- Saplings — images: grow from a seed, pull, remove, and Inspect (boots the base and reports what's already baked in — Xcode/Node/Ruby/brew/…).
- Seeds — a structured
.graftbuilder: start with name/from, "+ Add" only the components you want (Add toolchain → Python; multiple custom-script blocks; sims; caches; …), with version dropdowns and a base-image inspector — or flip to Raw YAML. Round-trips through the recipe model; Render previews the compiled provisioning script. - Profiles · Pools · Secrets — full config with no JSON editing; the Orchard token lives with its profile.
Create a GitHub App without leaving the app
Graft.app can create a GitHub App for you via GitHub's manifest flow — it opens your browser to a pre-filled "Create App" page (runner permissions baked in), catches the redirect, and stores the App ID and private key automatically. No copying the ID, no downloading a .pem. It also smart-imports an existing key (pick the .pem, it auto-detects the App from the filename) and confirms installation. (graft secrets create-app does the same from the CLI.)
Two dialects
A Standard ↔ Graft vocabulary toggle (Settings ⌘,) — see plain software terms (Dashboard, Pools, Secrets…) or the botanical theme (Tend, Stands, Roots…). Defaults to Standard.
⚙️ Elastic supervision + reliability (post-Aspen)
- Elastic supervision (GFT-18):
pool.countis now the source of truth — the supervisor spawns one slot per desired runner and treats capacity as a throttle (atomic, actor-side). Starttendagainst an empty fleet, add branches, and parked slots acquire on their own; shrink the fleet and it drains — no restart. (Also fixed a latent capacity false-positive when the fleet was full of Graft's own runners.) - GFT-20: an in-flight leaf (created but mid-
acquire) is no longer false-flagged as leaked deadwood. - GFT-21:
plant/bonsainow trap Ctrl-C (no more orphanedorchard controller) and refuse-with-a-clear-message if a trunk is already running. - Worker Ctrl-C cleanup:
branch/bonsaiSIGTERM the worker, sweep the leaves they booted, and self-deregister from the trunk so capacity frees immediately instead of waiting out the heartbeat-stale window.staleThresholdaligned to Orchard's 180s. graft sapling inspect <image>— boot a base and report its installed tools.- The tend dashboard groups by pool with a fixed row per desired slot (never blank).
📋 Design epics banked (not in this release)
Two future directions are written up in docs/design/:
- Remote host management + aggregated health ("Sapflow") — control trunk/branch hosts and stream fleet health into one panel, with a full security/threat model.
- Share
.graftseeds, not images — a hosted minimal base ladder so a recipe is the unit you distribute.
Install
brew update
brew upgrade graft # CLI
brew upgrade --cask graft-app # desktop app
# first time: brew install briancorbin/tap/graft + --cask briancorbin/tap/graft-appIf brew upgrade complains about the cirruslabs/cli/tart dependency, run brew trust cirruslabs/cli once.
Apple Silicon only. Tart is pulled in as a dependency.
Notes
- No config migration needed since 0.4.0.
- The app reads/writes the same Keychain items as the CLI — macOS may prompt "Always Allow" once.
v0.4.0 — Aspen 🌲
🌲 Aspen — the fleet that watches itself
The biggest release since the multi-host backend: a near-total rework of how the supervisor boots, monitors, and recovers runners — it's now self-healing and never execs into your runner VMs — plus a ground-up CLI redesign around a single tree vocabulary.
TL;DR —
graft run→graft arborist tend. The supervisor hands each leaf its runner via a StartupScript at create time and watches it through GitHub, so a controller blip mid-job is a non-event and a supervisor crash re-adopts running jobs instead of killing them. The CLI is reorganized undergraft arborist;image→sapling,dev→nest. See the migration table below.
🌲 Why "Aspen"?
Graft releases are named for tree species. An aspen grove looks like a forest of separate trees but is really one organism — a single root system that keeps resprouting fresh stems as old ones die. That's exactly this release: a distributed fleet watched as one living thing, self-healing from a shared root.
The big idea
Before Aspen, the supervisor SSH'd into each leaf and held that connection open for the entire job to stream the runner's output. A controller blip mid-job killed the stream and cascaded into "parked at 0 capacity forever" and phantom "deadwood."
Aspen flips it. The supervisor hands each leaf its runner bootstrap as a StartupScript at create time — the worker (local to the VM) launches the runner — and the supervisor then watches the runner entirely through GitHub's API. There's no long-lived connection to lose:
- A controller bounce mid-job is a non-event — monitoring polls GitHub, not the controller.
- A supervisor crash re-adopts its still-running leaves on restart, monitoring them to completion instead of killing live jobs.
✨ What's new
Self-healing supervisor
- Create-with-startup-script + GitHub-poll monitoring — no exec into guests, no held stream.
- Re-adoption on restart — a crashed supervisor reconciles its leaves against GitHub: still-running ones are picked back up; finished/dead ones are cleaned up. Running jobs survive a supervisor restart.
- Startup grace — "offline" means still booting until a runner has been seen online (then it means done), so a fresh leaf is never reaped mid-boot.
- Stale-worker exclusion — a dead branch stops counting toward capacity after 180s (matching Orchard's own offline timeout).
- Park-on-zero-capacity — a full fleet waits instead of churning create→pending→timeout→delete.
- Runner-husk cleanup — runners are deregistered by name on every teardown path (normal, re-adopt, reconcile), so offline husks don't pile up;
graft arborist runners pruneclears any stragglers.
Detection-first health monitoring — graft arborist tend --monitor (also on plant/branch)
- Pluggable sinks: a structured JSONL log, a current-state snapshot, and a generic webhook (the foundation for Slack / PagerDuty / Sentry formatters later).
- Detectors for auth, capacity, wedged slots, deadwood, controller reachability, and host vitals (disk / memory / tart).
- Optional
monitorconfig block: webhook URLs, poll interval, heartbeat, thresholds.
Live job signal
- The dashboard now shows
running job: <name>(resolved from GitHub's in-progress runs), not just "ready · waiting for jobs."
💥 Breaking changes — the CLI is reorganized
Everything operational now lives under graft arborist, the structural verbs are top-level, and several commands moved into the tree vocabulary. There are no compatibility aliases — graft run and graft tree are gone.
| Old (≤ 0.3.0) | New (0.4.0) |
|---|---|
graft run |
graft arborist tend |
graft arborist (bare doctor) |
graft arborist check |
graft tree status |
graft arborist canopy |
graft tree branches / leaves |
graft arborist branches / leaves |
graft runners … |
graft arborist runners … |
graft tree plant |
graft plant |
graft tree branch <url> |
graft branch <url> |
graft tree prune <name> |
graft prune <name> |
graft tree bonsai |
graft bonsai |
graft image build -f X.graft |
graft sapling grow --seed X.graft |
graft image … |
graft sapling … |
graft dev … |
graft nest … |
--tend flag |
--monitor |
The launchd plist and the menu-bar app were updated to invoke graft arborist tend. If you run graft as a daemon, re-install the plist.
🌳 The vocabulary
Graft's whole model is one tree:
a seed (a
.graftrecipe) grows a sapling (a golden image) → which sprouts leaves (ephemeral runner VMs) → onto branches (workers) → of a tree (one fleet) → tended by an arborist → and one day, a forest (many fleets). You nest in it to develop.
📦 Install / upgrade
brew update
brew trust cirruslabs/cli # once — graft pulls in the tart CLI
brew install briancorbin/tap/graft # CLI
brew install --cask briancorbin/tap/graft-app # menu-bar app (Developer-ID signed + notarized)
# upgrading from an earlier version:
brew upgrade graft && brew upgrade --cask graft-appApple Silicon + macOS Sonoma or newer. Running headless / on an EC2 Mac? See docs/ec2-mac-setup.md for the auto-login requirement.
🔬 Validated
Built against verified Orchard source behavior (heartbeat 15s / offline 180s, reconcile semantics, the StartupScript delivery path) and live-validated end-to-end on a real Apple-Silicon Orchard fleet — including a hard-kill of the supervisor mid-job and confirming it re-adopts the running leaves on restart.
🔭 What's next
- Richer live job status pushed from the leaf (steps, timing) via the runner's job hooks — the leaf telling the arborist, rather than the supervisor polling.
- Opt-in auto-remediation (
graft arborist sweep) building on the always-on detection layer.
Full lifecycle & failure-mode design: docs/design/lifecycle-and-failures.md.
v0.3.0 — the tree 🌳
graft's multi-host fleet is now a tree, named so the CLI describes itself — and the product name becomes the verb it performs (graft grafts leaves onto branches).
The tree 🌳
A coherent model for the Orchard backend: trunk = controller · branch = worker · leaf = a runner VM · graft = joining a leaf onto a branch.
graft tree plant— run the controller (captures the admin token for you)graft tree plant --bonsai— a tiny self-contained local tree (trunk + a branch), one commandgraft tree branch <url> [--reserve N]— graft a worker on (mints its own bootstrap token; reserve host RAM)graft tree prune <name>— remove a workergraft tree status | branches | leaves— inspect the fleetgraft initis now backend-aware (Local Tart · Orchard tree); the oldgraft orchard …is gone — nothing user-facing says the vendor's name anymore.
Renames (hard, no aliases)
graft doctor→graft arborist(the tree-doctor; now defaults to checking your active profile's pools)graft vm→graft leaf(create/rm/list/ip)
Per-pool leaf sizing + memory-aware scheduling
graft pool add … --cpu --memory— a pool declares its workload's shape, independent of the image (one toolchain image, a small lint pool + a fat e2e pool; labels still route viaruns-on:).- graft requests memory from Orchard's scheduler, so a branch is never over-packed into OOM.
Also
- Live capacity (graft sizes to real free slots, not a static ceiling)
- One-stop Orchard lifecycle from graft
- Fix: captured subprocesses get
/dev/nullstdin — interactivegraft runagainst Orchard no longer churns (was an inherited-TTY hang)
Full history: GFT-11, GFT-12, GFT-13, GFT-15, GFT-16.
Config schema cleanup (breaking)
provideris now a self-contained object:{ "type": "tart" }or{ "type": "orchard", "controllerURL": …, "serviceAccount": …, "maxVMs": … }— no more disconnected top-levelorchardblock.github(App + target) is declared once at the profile level; pools inherit it (a pool may override). Labels move onto the pool. Pools are now pure workload defs (name, image, os, count, cpu, memory, labels).- No migration — re-run
graft initto recreate profiles in the new shape.
v0.2.0 — dev *in* the VM
The headline: graft dev --code — turn a golden image into your actual dev box.
A dev box is a VM cloned from one of your images (same toolchain as CI). --code opens VS Code over Remote-SSH into the box — editor, terminal, language servers, and builds all run guest-side. It's GitHub Codespaces, but for native macOS/iOS (which containers can't do — Xcode + the simulator need a real macOS VM). Your dev box is a clone of the same image your CI runs, so "works on my machine" is gone.
graft dev # picker: resume a box / clone a repo / mount here / scratch
graft dev owner/app # clone → persistent box, shell in (--code for VS Code)
graft dev app # resume it
graft dev . # mount $PWD → ephemeral box → run here
graft dev ls / rm [box] # list / remove boxesModel: clone → persistent + resumable (repo + state live in the box); mount (.) / scratch → ephemeral. Shell is the default; --code opens VS Code (the picker asks which). Repos clone over HTTPS with a short-lived gh token via GIT_ASKPASS — nothing stored in the VM; git push/pull use VS Code's forwarded credentials. --name/--ref/--network/--mount are advanced.
Full guide: docs/dev-boxes.md.
Since 0.1.6 (0.1.7 folded in)
- Image builder depth: full declarative
.graftfield set (toolchain/system/cache-warming/verify/VM-shape),repos:warm-cache pre-caching, orphan build-VM sweep +graft image prune, VM networking (bridged:<iface>for Zscaler), auto-pull. - Robustness fixes hunted down the hard way: a Foundation
Process/pipe write-end leak + a TTY-onlygh auth tokenhang, the$HOME-not-expanding clone-path bug, bounded SSH-readiness on fresh boots, bounded guest-readiness probes. - Docs reorganized into
docs/with a README index.
The menu-bar app is unchanged from v0.1.6 (CLI release).