Farhand (fh)

Zero-dependency remote build and test offloader.

Farhand or fh (pronounced FAAAAAAAH)

---

What is Farhand?

Modern software projects have heavy compilation, bundling, and testing pipelines. Running tsc -p ., cargo build --release, vitest run, or docker build on a thin laptop or MacBook Air drains battery, spins loud fans, and throttles your system.

Farhand (fh + fhd) allows you to keep editing code locally in your favorite editor (VS Code, Neovim, Zed) while offloading heavy compilation to a powerful remote machine (such as an Apple Silicon Mac Mini, a Linux workstation, or an internal build server).

Logs stream directly into your terminal in real time, and build artifacts (like ./dist or ./target/release) are automatically synced back to your local project directory.

---

Why Farhand?

Feature	Farhand (fh)	ssh + rsync scripts	Remote Desktop / SSH VSCode
Zero Runtime Dependencies	Yes (pure static Rust)	No (requires rsync, ssh, tar)	No (heavy daemon)
Persistent Dependency Cache	Yes (node_modules stays remote)	Often wipes or conflicts	Local to remote box
Multi-Branch APFS CoW Forking	Yes (< 100ms, 0-byte duplicate)	No (duplicates entire folder)	No
Delta Source Sync	Yes (SHA-256 manifests over TCP)	Yes (rsync delta)	N/A (entire edit remote)
Clean Process Cancellation	Yes (kills remote process tree)	No (orphans compiler processes)	Yes
Offline Multi-Agent Failover	Yes (automatic load-balancing)	No	No
Works with Any Local Editor	Yes (pure CLI wrapper)	Yes	No

---

Core Features

• ⚡ Zero External Dependencies: Pure Rust binaries. Does not invoke or depend on system ssh, rsync, tar, or gzip.
• 📁 Persistent Workspace Cache: Remote dependencies (node_modules/, target/, .venv/) remain on the agent host across runs. Only changed source files are transferred.
• 🍏 Instant APFS Copy-on-Write (CoW) Forking: When working across different branches on shared hosts, new branch workspaces are cloned from canonical seeds (main/master) in < 100ms using 0 additional disk blocks.
• 🧹 Automated Two-Tier LRU Garbage Collection: Daemon automatically soft-prunes intermediate caches and evicts stale branch workspaces according to disk quotas (--max-disk-gb) and inactivity TTL (--workspace-ttl-days).
• 🔀 Branch-Aware Project Addressing: Automatically detects git branches and scopes workspaces as <repo>__<branch> so multiple developers never collide.
• 🛡️ Section 5.1 Deletion Safety: Strictly protects remote dependencies and build outputs from being deleted during manifest synchronization.
• 🛑 Process Group Isolation: Spawns compilation inside isolated process groups (setpgid). If you Ctrl+C locally, the entire remote compiler hierarchy is gracefully terminated.
• 🌐 Multi-Agent Pool & Tag Routing: Automatically discovers, health-checks, and load-balances jobs across a cluster of build agents.
• 📊 Run Observability: Query execution history, exit codes, synced bytes, and duration using fh history.

---

The Two Binaries

1. fh (Client): Scans the local project directory, hashes files, uploads deltas, requests remote command execution, streams live logs, and retrieves generated artifacts.
2. fhd (Daemon): Listens on TCP (port 9876), authenticates connections via token, maintains per-project workspaces, unpacks deltas, runs commands in process groups, streams stdout/stderr, and returns artifacts.

---

Quickstart

1. Installation

⚡ One-Liner Install

Linux & macOS (Terminal):

curl -fsSL https://raw.githubusercontent.com/Rayrsn/farhand/main/scripts/install.sh | bash

Windows (PowerShell — works whether MSVC / Visual Studio is installed or not):

irm https://raw.githubusercontent.com/Rayrsn/farhand/main/scripts/install.ps1 | iex

Windows (Command Prompt / cmd.exe):

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/Rayrsn/farhand/main/scripts/install.ps1 | iex"

Note for Windows Users: Windows binaries are compiled with static C-runtime linking (+crt-static). They are 100% self-contained and run on any clean Windows machine out of the box without requiring Visual Studio, MSVC build tools, or the Microsoft Visual C++ Redistributable.

---

📦 Pre-Built Release Packages (v1.1.0)

Pre-compiled static release packages and checksums are available on the Farhand v1.1.0 Release:

Platform	Architecture	Package Archive
Linux	x86_64 (64-bit)	farhand-v1.1.0-x86_64-unknown-linux-musl.tar.gz
Linux	aarch64 (ARM64)	farhand-v1.1.0-aarch64-unknown-linux-musl.tar.gz
macOS	Apple Silicon (M1/M2/M3/M4)	farhand-v1.1.0-aarch64-apple-darwin.tar.gz
macOS	Intel x86_64	farhand-v1.1.0-x86_64-apple-darwin.tar.gz
Windows	x86_64 (Standalone Static)	farhand-v1.1.0-x86_64-pc-windows-msvc.zip

---

🍺 Via Homebrew (macOS)

brew tap Rayrsn/farhand https://github.com/Rayrsn/farhand.git
brew install farhand

🦀 Via Cargo (From Source)

cargo install --git https://github.com/Rayrsn/farhand.git fh fhd

---

2. Start the Daemon (fhd)

On your remote build machine or Mac Mini:

# Generate a secret token
export FARHAND_TOKEN="super-secret-token"

# Run the daemon
fhd --listen 0.0.0.0:9876 --token "${FARHAND_TOKEN}" --workdir /var/farhand/workspaces

(For production background services on macOS or Linux, see the Apple Silicon Mac Mini Setup Guide or systemd service units).

---

3. Run Builds Remotely (fh)

In your local project directory, configure .farhand.yaml:

# .farhand.yaml
host: "192.168.254.68:9876"  # Remote agent address or Tailscale name
token: "${FARHAND_TOKEN}"

# Unpack artifacts directly into the project directory (e.g. ./dist)
outDir: "."

# Outputs to pull back from the agent upon success
outputs:
  - "dist"

Now execute any command remotely by prefixing it with fh:

# Offload TypeScript compilation
fh npm run build

# Run unit tests on the remote machine
fh npm test

# Compile Rust binaries
fh cargo build --release

# Run with secrets from Infisical (env vars forwarded automatically)
infisical run -- fh npm run build

# Or disable ambient env forwarding / pass explicit variables
fh --no-env -e DATABASE_URL=postgres://remote/app -- npm run build

# Inspect execution history
fh history

# Free remote disk space for the current branch
fh clean

---

Daily Developer Workflow

# 1. Start working on a new feature branch locally
git checkout -b feat/payments

# 2. Trigger build remotely
# Farhand automatically APFS-clones the seed workspace from main in < 100ms (0 bytes duplicate storage)
fh npm run build

# 3. Modify source code locally
nano src/index.ts

# 4. Re-run build
# Farhand only uploads the single changed file (0-byte delta sync for everything else)
fh npm run build

# 5. Finished with the branch? Free remote workspace space
fh clean

---

Detailed Documentation

Deep-dive guides covering architecture, server setup, and configuration:

• 📖 Internal Architecture & Wire Protocol — Binary framing specs, frame layouts, state machines, and Section 5.1 deletion safety.
• 🍏 Apple Silicon Mac Mini Setup Guide — Production step-by-step guide for turning a Mac Mini into a multi-developer build server (launchd, firewalls, network access).
• 💾 Storage Optimization & Caching Guide — Deep dive into APFS Copy-on-Write cloning, LRU garbage collection, and shared toolchain caches (sccache).
• ⚙️ Configuration Guide (.farhand.yaml) — Complete reference for config discovery, field definitions, and environment variable interpolation.
• 🌐 Multi-Agent Pool & Dynamic Load Balancing — Setup guide for multi-agent clusters, health probing, and hardware tag routing (--agent-tag).
• ☁️ Remote Access via Cloudflare Tunnel — Connect securely over the internet with cloudflared access tcp without opening inbound router ports.

---

License

Dual-licensed under either:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option.