RCH — Remote Compilation Helper

Transparently offloads cargo build, bun test, gcc to remote workers. Same commands, faster builds.

Diagnosis Loop

rch doctor              # What's broken?
rch doctor --fix        # Auto-fix common issues
rch doctor --verbose    # All checks passed? Ready to use

If --fix can't solve it → see Quick Fixes or references.

Quick Fixes (Copy-Paste)

Symptom	Command
SSH auth fails	`eval $(ssh-agent) && ssh-add ~/.ssh/your_key`
Daemon not running	`rm -f /tmp/rch.sock && rchd &`
Hook not installed	`rch hook install --force`
No workers available	`vim ~/.config/rch/workers.toml` (add workers)
Socket permission	`rm /tmp/rch.sock && rchd`
Stale socket	`lsof /tmp/rch.sock` → kill stale process

Worker Config (`~/.config/rch/workers.toml`)

[[workers]]
id = "builder"
host = "192.168.1.100"        # IP or hostname
user = "ubuntu"
identity_file = "~/.ssh/id_ed25519"
total_slots = 8               # ≈ CPU cores - 2
priority = 100                # Higher = preferred
tags = ["rust", "bun"]        # Optional capabilities

Auto-Discover from SSH Config

rch workers discover --from-ssh-config --dry-run  # Preview
rch workers discover --from-ssh-config            # Add to config

Verify Workers

rch workers probe --all         # Test all workers
rch workers probe worker1 -v    # Test single, verbose
rch workers list                # Show status

Fresh Install Checklist

Prerequisites: which rsync zstd ssh (install missing)
Config: Create ~/.config/rch/workers.toml (see above)
Daemon: rchd & or systemctl --user start rchd
Hook: rch hook install
Validate: rch doctor → all green

Supported Commands (Auto-Offloaded)

Category	Commands
Rust	`cargo build`, `cargo test`, `cargo check`, `rustc`
Bun	`bun test`, `bun typecheck`
C/C++	`gcc`, `g++`, `clang`, `make`, `cmake`, `ninja`

Never offloaded: bun install, cargo fmt, piped/background commands.

Debug

RCH_LOG=debug cargo build    # Show hook decisions
RCH_DRY_RUN=1 cargo check    # Test without remote execution
rch doctor --json > diag.json  # Export diagnostics

Fleet Operations

rch fleet status             # Show all workers
rch fleet preflight --all    # Verify workers ready
rch fleet deploy --all       # Deploy rch-wkr to workers
rch self-test                # Full end-to-end verification

Anti-Patterns

Don't	Why	Do Instead
Run daemon as root	Security risk	`systemctl --user start rchd`
Skip `rch doctor`	Miss config issues	Always verify first
Use `--force` blindly	May break hook	Check `rch hook status` first
Ignore transfer errors	Indicates network/disk issues	Check worker disk space, network

References

Topic	File
Worker schema, selection algorithm, SSH discovery	WORKERS.md
Error messages, symptom→fix table	TROUBLESHOOTING.md
Hook protocol, 5-tier classification, security	HOOKS.md
Command reference	COMMANDS.md

rch