# 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 --`):

```console
$ 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:

| Workload (4 Parallel Worktrees) | Typical Peak RAM | Local Impact |
| --- | --- | --- |
| `vitest` / `jest` worker pools | `8 – 16 GB` | Node V8 heaps multiply per worktree |
| `playwright test` / Cypress E2E | `10 – 24 GB` | Multiple headless Chromium / WebKit instances |
| `tsc --noEmit` + `eslint` | `6 – 12 GB` | Full AST & type-graph resident in each process |
| `cargo test` / `go test -race` | `8 – 20 GB` | Parallel `rustc` / linker spikes + disk I/O |

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](/docs/environments#project-containers) (installed automatically on AWS Spot runners).

## Installation

### macOS via Homebrew (Recommended)

```sh
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](https://github.com/daintreehq/spotexec/releases/latest):

```sh
# 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+):

```sh
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
```

> [!NOTE]
> Plain `go install` is not supported because `make build` cross-compiles the remote `spotexec-helper` for `linux/amd64`, `linux/arm64`, `darwin/amd64`, and `darwin/arm64` before embedding them into the single `spotexec` binary.

## Quickstart

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

```sh
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:

```sh
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](/docs/setup#choosing-runners).

### 2. Initialize your repository (once per repo)

```sh
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`

```sh
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
```

> [!TIP]
> The very first AWS Spot run boots a fresh VM (~60s plus your bootstrap script). Subsequent runs reuse the warm VM instantly until it has been idle for `idle_timeout` (default `10m`). Run `spotexec image bake` to snapshot your bootstrap into a private AMI so future cold boots finish in bare EC2 boot time.