Strict Docs

Install Strict on macOS & Linux

Drop-in replacement for GitHub Actions, Blacksmith, and WarpBuild runners.

1-click macOS app or single-line CLI install behind tailscale serve—persistent local NVMe caches, self-healing maintenance, and $0/min CI runs.

Download Strict

Strict for macOS icon
Strict for macOS
Latest release · Signed Apple Silicon · macOS 15+
Download
Installs strict CLI and Strict.app
curl -fsSL https://strict.ai/install.sh | sh -s -- --app

Local Server

Runs on an always-on Mac or Linux host behind tailscale serve. Uses Tailscale-User-Login headers and persists state in ~/.local/share/strict-server/state.json (workspace ws0000000000).

LaunchAgent (macOS) / systemd --user (Linux)
bun install && bun run standalone:install -- --tailscale-serve

Enroll Host & Agent

Install the strict CLI and self-healing maintenance daemon without any token—it auto-pairs with a running local standalone server or opens a one-click browser approval prompt via strict login. Adding a runner mints registration tokens automatically via gh (or accepts STRICT_RUNNER_TOKEN / --pair <code> for scripted CI).

Token-free CLI install & browser pairing
curl -fsSL https://strict.ai/install.sh | sh
strict login
Add a zero-sudo GitHub Actions runner (uses gh automatically)
strict add-runner <owner/repo>

Use in GitHub Actions

Once at least one machine is enrolled, you can switch existing .github/workflows/*.yml files in one step: copy a tailored handoff prompt for a coding agent (Claude Code, Cursor, Codex, or Antigravity) or update runs-on: directly in two lines.

Paste into Claude Code, Cursor, Codex, or Antigravity
Migrate this repository's GitHub Actions workflows to run on my self-hosted Strict fleet.

## Target Labels
- macOS Apple Silicon (`macos-*`): `[self-hosted, macOS, ARM64]`
- macOS Intel: `[self-hosted, macOS, X64]`
- Linux x64 (`ubuntu-*`): `[self-hosted, Linux, X64]`
- Linux ARM64: `[self-hosted, Linux, ARM64]`

## Instructions
1. Inspect `.github/workflows/*.yml` and `strict status` (or list configured runners) to verify which platforms and repositories have runners registered.
2. If this repo does not have a runner slot yet, provide or run `strict add-runner <owner/repo>` (auto-mints the registration token via `gh` and installs Strict's `before-job.sh` barrier hook).
3. Update matching jobs' `runs-on:` fields to the self-hosted label arrays above. Preserve existing `strategy.matrix` entries where applicable and leave jobs requiring unsupported OS environments (such as Windows) on GitHub-hosted runners.
4. Keep `actions/checkout` intact—Strict handles pre-job disk reclamation and draining via `before-job.sh` on persistent runner workspaces. Prefer repo-local tool installs/caches over mutating global host state.
5. If Tailnet Build Cache is enabled on the fleet, optionally add `strict cache restore` / `strict cache save` steps; never commit `STRICT_CACHE_TOKEN` or host secrets to workflows.
6. Summarize every workflow change and print a `gh workflow run` verification command.

Reference docs: https://strict.ai/docs#use-ci
  • One-command repo setup — Run strict add-runner <owner/repo> on any enrolled host (auto-mints the registration token via gh, installs the before-job.sh hook, and starts the user service without sudo).
  • Native runner labels — GitHub automatically assigns [self-hosted, macOS, ARM64], [self-hosted, macOS, X64], [self-hosted, Linux, X64], or [self-hosted, Linux, ARM64] (plus any custom --labels passed during setup).
  • Automatic hygiene & spillover — Strict's before-job.sh barrier hook, tiered cleanup, and computeFleetDirective load-draining run automatically across peers.
  • Persistent workspace hygiene — Keep standard actions/checkout steps and prefer repo-local installs/caches instead of mutating global system state; use strict cache env if you need STRICT_CACHE_URL outside runner .env (never commit STRICT_CACHE_TOKEN).

GitHub Actions, Blacksmith & WarpBuild Drop-in

Switching from hosted GitHub, Blacksmith, or WarpBuild runners takes 1-click app install (or one CLI command), strict add-runner owner/repo, and changing one line per job. Existing steps, secrets, matrices, and actions/cache calls stay identical. See detailed cost & hardware comparisons →

  1. Install with 1 click or CLI — Launch Strict.app on macOS or run curl -fsSL https://strict.ai/install.sh | sh -s -- --app.
  2. Register your repository — Run strict add-runner <owner/repo> (no sudo needed) to configure the runner and barrier hooks.
  3. Swap runs-on — Point macOS or Linux jobs at your fleet labels below.
.github/workflows/ci.yml (GitHub macOS → Strict Mac)
jobs:
  build:
-   runs-on: macos-15
+   runs-on: [self-hosted, macOS, ARM64]
Previous runner Drop-in Strict label Notes
macos-15 / macos-latest [self-hosted, macOS, ARM64] Apple Silicon Mac mini / Mac Studio
blacksmith-6vcpu-macos-latest [self-hosted, macOS, ARM64] Keeps warm Xcode DerivedData on NVMe
warp-macos-latest-arm64-6x [self-hosted, macOS, ARM64] Full Apple Silicon cores + warm NVMe
ubuntu-24.04 / ubuntu-latest [self-hosted, Linux, X64] Also supports ARM64 with custom --labels
blacksmith-4vcpu-ubuntu-2404 [self-hosted, Linux, X64] Retains Docker & BuildKit layers locally
warp-ubuntu-latest-x64-4x [self-hosted, Linux, X64] Persistent Docker layers without snapshot fees

NVMe & Tailnet Caches

Unlike ephemeral VMs that re-download toolchains and build caches on every job, Strict keeps local caches warm on fast NVMe storage across runs—and lets multi-node fleets share artifacts over Tailscale using ACTIONS_CACHE_URL.

Wire a shared tailnet cache or inspect local cache state
strict add-runner <owner/repo> --cache-url http://cache.your-tailnet.ts.net:8788
strict cache status
strict cache env
  • Automatic local warmth — Xcode DerivedData, SwiftPM packages, Docker layers, Homebrew bottles, Bun, Cargo, Go, and pip caches persist safely between jobs.
  • strict cache env & --cache-url — Exports STRICT_CACHE_URL and ACTIONS_CACHE_URL (with --cache-token-env for auth) into the runner .env so multi-host builds stay fast.

Doctor & Drift Checks

Long-lived self-hosted hosts fail in predictable ways: unallocated APFS container space, macOS sleep timers, unsigned Xcode licenses after OS updates, or silent toolchain version drift across nodes. Run strict doctor anytime—or automatically inside fleet monitoring—to verify all 9 preflight checks.

Run preflight checks (9 host checks + JSON/strict gate)
strict doctor
strict doctor --strict
strict doctor --json
  • 9 automated checks — Verifies GitHub DNS reachability, free disk headroom, unallocated APFS container space, macOS sleep settings, macOS autologin, Linux loginctl linger, before-job.sh runner hooks, Xcode license acceptance, and Tailscale daemon health.
  • Toolchain & Xcode drift — Every heartbeat inventories Xcode, Swift, Node, Bun, Python, Rust, and Docker versions across peers and flags mismatched hosts before builds break.

Remote SSH CLI

Provision servers, enroll Mac or Linux hosts, install GitHub runners via stdin tokens, and inspect fleet status over SSH.

scripts/strict-remote.sh
bun run remote -- server --host <user@host> --tailscale-serve
bun run remote -- enroll --target <user@host> --server http://<server>:8787 --code <CODE> --runner-repo <owner/repo> --runner-token-stdin
bun run remote -- add-runner --target <user@host> --repo <owner/repo> --token-stdin
bun run remote -- status --server http://127.0.0.1:8787

Disk Cleanup Tiers

Below lowGiB, strict_maintenance.py reclaims down to targetGiB, skipping active Runner.Worker builds across caches, checkouts, and Xcode:

  • Tier 1 — Stale _diag logs and idle _work/_temp
  • Tier 2 — Package caches (npm, bun, pip, go, cargo, Homebrew, CocoaPods, SwiftPM)
  • Tier 3 — Git-ignored build artifacts in idle checkouts
  • Tier 4 — Stale Xcode DerivedData and unavailable iOS simulators
  • Tier 5 — Docker prunes and >24h idle checkouts
  • Tier 6 (opt-in) — APFS snapshot thinning, CoreSimulator caches & old iOS DeviceSupport
  • Tier 7 (opt-in) — Safe user Trash sweep per host
Preview reclaimable GiB or trigger manual maintenance
strict check
strict clean --target-gib 60
strict clean --deep-macos --empty-trash

Auto Load-Balancing

computeFleetDirective drains runner slots under disk, RAM, CPU, or skew pressure only when a healthy peer covers the repo pool, and auto-recovers after 5 minutes offline. Read the load-balancer deep dive & simulator or how Strict works.

Tailscale Provisioner

Pass --provisioner to enable remote SSH probes, agent updates, runner installs, and uninstalls from the console or macOS app.

Questions

Do I change anything besides runs-on when migrating?

No. Replace macos-15, ubuntu-24.04, blacksmith-*, or warp-* with [self-hosted, macOS, ARM64] or [self-hosted, Linux, X64]. Your workflow steps, matrices, and secrets keep working as written.

Does Strict need sudo or root to install GitHub Actions runners?

No. Both Strict.app and strict add-runner run as standard user services under macOS launchd and Linux systemd --user (with loginctl enable-linger checked by strict doctor).

What if I have multiple Macs—how does Strict keep Xcode in sync?

Strict collects toolchain versions (Xcode, Swift, Node, Bun, Python, Rust, Docker) on every heartbeat and flags same-OS mismatches right in the console and CLI status output.