remote-compilation-helper-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 |