Offload heavy agent tests and builds from local worktrees.
Prefix any command with sx. Run test suites, Playwright browsers, typecheckers, linters, and formatters on an
SSH box or scale-to-zero AWS Spot fleet—keeping your Mac cool while paying pennies per
hour.
$brew install daintreehq/tap/spotexec$ sx pnpm vitest run -u src/auth.test.ts
✓ src/auth.test.ts (12 tests) 340ms
↳ 2 snapshots updated
● 4.1s on aws#3 · synced 4 files (18 KB) · pulled 2 files
$ sx pnpm prettier --write src/
src/auth.ts 42ms
src/session.ts 19ms
● 0.9s on homelab#1 · fingerprint hit (0 B) · pulled 2 filesTypical 2 vCPU / 4–8 GB Spot workers (t3a.large, c7a.large, m7a.large) run around $0.024–$0.038/hr—65–70% below On-Demand—and
terminate to $0.00/hr when idle.
Free your Mac from concurrent V8 heaps, TypeScript AST graphs, and headless Chromium workers. Run 4–8+ coding agents, your editor, and local dev servers side by side without swap thrashing.
Formatters, autofixes, and snapshot updates compare against the synced Git blob SHA-1. Edits made locally mid-run are never overwritten, and VMs hold zero AWS credentials.
Coding agents drove up CPU and memory—because they verify everything.
AI coding agents don't just edit text. To close the loop reliably, every Claude Code or
Codex session constantly runs unit tests, end-to-end browsers, tsc --noEmit, linters, and code formatters. Running those verification loops across 4–6 parallel Git
worktrees multiplies CPU spikes and multi-gigabyte memory footprints—slowing your entire
machine down.
Install once with spotexec hook install --claude. Heavy verification commands rewrite to spotexec run -- '<cmd>' automatically,
while git, rg, file reads, and localhost dev servers stay local.
when_load_above = 0.6)Keep single quick runs local when your laptop is quiet, and spill automatically to your SSH box or AWS Spot fleet the moment parallel agent worktrees push local CPU load above 60%.
Offload the heavy task, not the whole agent loop.
Running an entire coding agent workflow on Spot instances is fragile: if AWS reclaims the
VM mid-session, your agent state and unpushed progress vanish. SpotExec flips the model.
Your agents, Git worktrees, and editor stay safely on your Mac, while only the heavy individual task runs on Spot. If a VM gets reclaimed, nothing is lost—sx replays that single task on another slot and you keep the 65–70% Spot discount.
Long-lived agent state, open shells, and in-progress edits live on a preemptible VM. A 2-minute Spot reclamation notice can interrupt an entire multi-step workflow.
Agents stay local on your Mac. Only stateless, repeatable checks (vitest, eslint, tsc, builds) run on 2 vCPU / 4–8 GB
Spot VMs. Reclaimed mid-run? Re-dispatch on a fresh slot with zero lost work.
$0.00/hr after idle_timeout.Fill hardware you own first. Overflow to AWS Spot. Scale back to $0.00/hr.
Every sx invocation schedules
cooperatively through local flock state. Static SSH boxes absorb baseline runs at zero marginal cost; Spot instances launch
on overflow, pack jobs onto the oldest VMs first, and power themselves off when idle.
version = 1
default_pool = ["homelab", "aws"]
[runners.homelab]
type = "ssh"
hosts = ["me@192.168.1.50", "me@box.ts.net"]
max_slots = 4
priority = 10 # fills first ($0/hr)
[runners.aws]
type = "aws-spot"
profile = "spotexec"
region = "us-east-2"
instance_types = ["c7a.xlarge", "c6a.xlarge"]
max_slots = 2
max_instances = 4
priority = 20 # takes overflow
idle_timeout = "10m" # self-terminatesOnce all 4 homelab slots fill up, overflow demand boots two Spot instances automatically—coordinated locally via flock with zero cloud scheduler.
Built for the edge cases skeptical engineers ask about first.
Click through each scenario below to inspect how spotexec handles concurrent local edits, closed laptop lids, and 2-minute AWS Spot reclamation notices.
Single Go binary · Hand-signed AWS SigV4
- • Isolated slot process groups
- • Reflink + S3 presigned deps
- • systemd idle → poweroff
- • IMDSv2 5s Spot notice
Clean tracked files reuse SHA-1 blob IDs directly from .git/index without reading disk. Only blobs missing on the remote slot travel over the multiplexed SSH ControlMaster channel.
Reads .git/index SHA-1 blob IDs and hashes modified files into a manifest.
Acquires a slot lock and streams only missing blobs (0 bytes on repeat runs).
Hydrates node_modules / .venv via CoW reflink or S3, then runs the command.
Applies formatter and snapshot updates atomically once baseline SHA-1 matches.
Delta sync, CoW reflinks, and baked AMIs
Instead of rsync or full container
rebuilds, spotexec caches at three
independent layers:
Strict isolation between untrusted repos, VMs, and your laptop
Every path, credential, and configuration key enforces a hard boundary:
Spot instances launch with no IAM instance profile and enforce IMDSv2. S3 cache archives and ECR layers are accessed solely via short-lived presigned URLs generated on your workstation.
.spotexec.toml files cannot alter connectionsSetting hosts, ssh_options, identity_file, profile, region, subnet_id, or cache_bucket inside a repo config is rejected as an
error.
.gitEvery returned path rejects symlinks, .. traversal,
and any case-spelling of .git. Runners can only
modify files that were in the synced manifest.
spotexec setup creates a dedicated spotexec-<hostname> IAM user per laptop so a
retired machine can be revoked cleanly without disrupting teammates.
Up and running in three commands
aws login
spotexec setupWrites config.toml, provisions a scoped IAM key, and
checks VPC & Spot vCPU quota.
cd ~/code/my-app
spotexec init && spotexec doctorDetects lockfiles, [deps] caches, and test tasks;
verifies end-to-end SSH & helper health.
sx or
hook agentssx pnpm test
spotexec hook install --claudeRun directly from any worktree or let parallel coding agents offload heavy suites automatically.