Introduction & Quickstart

spotexec (sx) runs your tests, typechecks, linters, E2E browsers, formatters, and builds on remote hardware—straight from a local Git worktree. You can point it at a Linux box or spare Mac over SSH, an elastic fleet of AWS Spot instances that boot on demand and terminate themselves when idle, or both at once.

Prefix any command with sx (shorthand for spotexec run --):

$ sx pnpm vitest run -u src/auth.test.ts
 ✓ src/auth.test.ts (12 tests) 340ms
● 4.1s on aws#3 · synced 4 files (18 KB) · pulled 2 modified files

Files modified by the remote command (prettier --write, eslint --fix, vitest -u, codegen) come back to your local worktree through a 3-way content-ID check, so concurrent local edits are never overwritten.

Why It Matters for Parallel Coding Agents#

AI coding agents (such as Claude Code and Codex) have changed the bottleneck on developer machines. Editing files across four or six Git worktrees in parallel uses practically zero CPU or memory—but every agent verifies its own work by invoking test runners, headless E2E browsers, typecheckers, linters, and compilers simultaneously:

On a laptop, those concurrent verification loops trigger swap thrashing, thermal throttling, sluggish editors, and out-of-memory kills.

spotexec is designed specifically for this workload:

• Shared remote slots. Many local worktrees share a pool of remote runners through isolated slots, a fair local queue, and a lockfile-keyed dependency cache.
• Transparent agent hooks. spotexec hook install --claude rewrites heavy test, build, and lint commands to spotexec run -- '<cmd>' automatically (optionally only when laptop load exceeds when_load_above = 0.6), while keeping git, rg, and localhost dev servers local.
• Zero cloud control plane. Nothing runs in your cloud account except the ephemeral VMs themselves. Coordination uses local flock state and EC2 tags, and each VM terminates itself via a cloud-init systemd timer even if you close your laptop lid.

Requirements#

On your local machine:

• git and OpenSSH (ssh, used with ControlMaster connection multiplexing) on PATH.
• AWS CLI v2 is optional: spotexec signs AWS API requests directly with no AWS SDK in the binary. Install aws only if you sign in via SSO, aws login, assume-role, or want spotexec setup to provision IAM users automatically.

On a remote runner:

• An SSH server, bash, and gzip on Linux or macOS (amd64 or arm64).
• Nothing of spotexec needs to be preinstalled: the spotexec binary embeds cross-compiled spotexec-helper binaries for all four OS/architecture targets and uploads the matching helper to ~/.cache/spotexec/bin/ on first contact.
• Docker is required only if you opt into project containers (installed automatically on AWS Spot runners).

Installation#

macOS via Homebrew (Recommended)#

brew install daintreehq/tap/spotexec     # installs spotexec, the sx alias, and shell completions
spotexec version

Homebrew is the recommended way to install and upgrade spotexec on macOS (Apple Silicon and Intel), and also works with Homebrew on Linux.

Linux Packages (.deb, .rpm, .apk)#

Download the package for your architecture (amd64 or arm64) from the latest GitHub release:

# Debian / Ubuntu
sudo apt install ./spotexec_*_linux_amd64.deb

# Fedora / RHEL
sudo dnf install ./spotexec_*_linux_amd64.rpm

# Alpine
sudo apk add --allow-untrusted ./spotexec_*_linux_amd64.apk

Standalone Archive or Source Build#

Plain .tar.gz archives for macOS and Linux (amd64 and arm64) are attached to every release—place spotexec on your PATH and symlink sx to it.

To build from source (requires Go 1.26+):

git clone https://github.com/daintreehq/spotexec.git && cd spotexec
mkdir -p "$(go env GOPATH)/bin"
make install        # cross-compiles helpers, builds bin/spotexec + bin/sx, installs to GOPATH/bin

Quickstart#

1. Set up your machine (once per machine)#

aws login                  # or aws sso login / aws configure, with IAM admin rights
spotexec setup             # writes ~/.config/spotexec/config.toml and creates a scoped IAM key

spotexec setup writes ~/.config/spotexec/config.toml, creates a dedicated least-privilege IAM user (spotexec-<hostname>) and non-expiring access key under profile spotexec, verifies VPC and Spot vCPU quotas, and optionally sets up additional machines on your LAN over SSH:

spotexec setup studio-01.local studio-02.local

Using a homelab Linux server or spare Mac instead of AWS? Configure it as an ssh runner in ~/.config/spotexec/config.toml—see Setting Up Machines.

2. Initialize your repository (once per repo)#

cd ~/code/my-app
spotexec init               # detects lockfiles, package manager, and common test/lint tasks
spotexec container init     # optional: scaffold .spotexec/Dockerfile for reproducible toolchains
spotexec doctor             # verify config, SSH ControlMaster, helper, AWS credentials, and quota

3. Run commands with sx#

sx pnpm test                     # delta sync → run in remote slot → write back mutations
sx pnpm prettier --write .       # formatted files land safely back in your worktree
sx test --reporter=dot           # run a named task from .spotexec.toml with extra args
sx verify                        # fan out parallel tasks (e.g. typecheck + test) across slots
spotexec status                  # inspect active slots, runners, and idle timers
spotexec monitor                 # live TUI dashboard of slot load and Spot $/hr burn rate