RCH Setup

Offloads cargo build, bun test, gcc to remote workers. Transparent—same commands, faster builds.

Workflow

1. rch doctor           # What's broken?
2. rch doctor --fix     # Auto-fix common issues
3. rch doctor           # All green? Done.

If --fix can't solve it, continue below.

Setup Checklist

• Prerequisites: which rustup rsync zstd (install missing)
• Install: cargo install --path rch (or --path . from repo root)
• Configure: Create ~/.config/rch/workers.toml (see below)
• Hook: rch hook install
• Daemon: rch daemon start (or systemctl --user start rchd)
• Validate: rch doctor → all checks pass, then rch self-test

Worker Config

# ~/.config/rch/workers.toml
[[workers]]
id = "worker1"
host = "192.168.1.100"
user = "ubuntu"
identity_file = "~/.ssh/id_ed25519"
total_slots = 8    # ≈ CPU cores - 2
priority = 100     # Higher = preferred
tags = ["rust"]    # Optional capability tags

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 worker1 --verbose  # Test single
rch workers probe --all              # Test all
rch workers capabilities             # Show detected toolchains/targets

Quick Fixes

Symptom	Fix
SSH fails	eval $(ssh-agent) && ssh-add ~/.ssh/your_key
Daemon down / stale socket	rch daemon restart — never rm the socket by hand
Hook missing	rch hook install (--force only after rch hook status)
No workers	rch status --fleet + rch admit "cargo build" — find the real cause; do not edit workers.toml for transient illness

Test the hook:

rch hook test

Validation

rch doctor --verbose   # Full diagnostics
rch doctor --json      # Machine-readable
rch diagnose "cargo check" --dry-run  # Show the decision without remote execution

⚠️ All rch doctor checks must pass before use.

References

Topic	Reference
Worker schema, selection algorithm, tags	WORKERS.md
All error messages & detailed fixes	TROUBLESHOOTING.md
Hook protocol, 5-tier classification	HOOKS.md