farhand-agent 1.9.0

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?

Core Features

• ⚡ No External System Binaries: Pure static Rust binaries. Never invokes or depends on system ssh, rsync, tar, or gzip (templates are compiled in — nothing is read from disk or executed).
• 🚀 High-Speed Zstandard (zstd) Wire Compression: Automatic handshake negotiation chooses zstd (level 3) for delta and artifact transfers, delivering 3–5× faster compression throughput than gzip with minimal CPU overhead.
• 🗄️ Global Content-Addressable Storage (CAS): Files with matching SHA-256 hashes are deduplicated globally on the agent host across all branches and projects, hydrated instantly via zero-copy CoW reflinks (clonefile on macOS / FICLONE ioctl on Linux). Zero-byte uploads for known files!
• 📁 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 & Emergency GC: Daemon automatically soft-prunes intermediate caches, performs pre-flight emergency GC when disk space is tight (--min-disk-gb), and evicts stale branch workspaces.
• 👁️ Continuous Watch Mode (fh watch): Automatically debounces local file changes, syncs source deltas, and re-triggers remote builds with zero manual intervention.
• 🖥️ Interactive Shell & Ad-Hoc Exec (fh shell, fh exec): Drop into an interactive remote PTY shell inside your project workspace or run diagnostic commands without triggering hooks.
• 🔀 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.
• 🔒 Native Zero-Config TLS & Mutual TLS (mTLS): Pure-Rust, memory-safe TLS via rustls (zero OpenSSL / C library dependencies). Supports automatic self-signed cert generation (fhd --tls-auto), SHA-256 fingerprint verification (fh --tls-fingerprint <sha256>), CA verification (--tls-ca), and mutual TLS client certificates (--tls-cert, --tls-key).
• 🛠️ Declarative Toolchain Manager Hooks: Declare language versions per project in .farhand.yaml or via CLI (-T rust=nightly). Farhand automatically configures RUSTUP_TOOLCHAIN, PYENV_VERSION, NODE_VERSION, and wraps remote invocations with nvm, fnm, pyenv, or goenv.
• 📊 Run Observability: Query execution history, exit codes, synced bytes, and duration using fh history and host status via fh status.
• 🔍 Transfer Transparency (fh sync, fh why): See exactly what a build would upload — file count, bytes, and the share of the project that would cross the network — with fh sync --dry-run; ask about any single path with fh why, which names the ignore rule that excluded it or reports the content-addressed hit that skipped it.
• 🩺 fh doctor: One read-only pass over everything that commonly breaks a remote build — where it is pointed, whether the token is present and stored safely, whether the transport is encrypted, declared toolchains, and the agent's connectivity, disk, queue, and load. It distinguishes "cannot reach the agent" from "reached it and it rejected your token", and exits 125 when something is actually broken.

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.7.0)

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

🍺 Via Homebrew (macOS)

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

🦀 Via Cargo

# The two binaries come from two crates, because the agent is published
# separately: a client-only user should not have to build a daemon.
cargo install farhand-cli      # provides `fh`
cargo install farhand-agent    # provides `fhd`

Or straight from the repository, if you want unreleased changes:

cargo install --git https://github.com/Rayrsn/farhand.git farhand-cli farhand-agent

The crate names are farhand-cli and farhand-agent, not fh and fhd. The binaries are fh and fhd; cargo install takes crate names. (farhand itself is unavailable on crates.io — an unrelated project already owns it.)

☁️ Automated Remote Setup (SSH Over Cloudflare Tunnel)

To automatically install all prerequisites (cloudflared, OpenSSH, and fh) on your local client machine and configure seamless SSH port forwarding:

• Linux & macOS:

  curl -fsSL https://raw.githubusercontent.com/Rayrsn/farhand/main/scripts/setup_remote_ssh.sh | bash
  # Or run locally from repository:
  ./scripts/setup_remote_ssh.sh --hostname mac.yourdomain.com --alias mac-mini --user builder
  

• Windows (PowerShell):

  & { irm https://raw.githubusercontent.com/Rayrsn/farhand/main/scripts/setup_remote_ssh.ps1 } -Hostname mac.yourdomain.com -HostAlias mac-mini -RemoteUser builder
  # Or run locally from repository:
  .\scripts\setup_remote_ssh.ps1
  

(See the complete Remote Access via Cloudflare Tunnel Guide for full architecture details).

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 (token required — fhd refuses to start unauthenticated by default)
fhd --listen 0.0.0.0:9876 --token "${FARHAND_TOKEN}" --workdir /var/farhand/workspaces

# Development only: allow unauthenticated local clients explicitly
fhd --listen 127.0.0.1:9876 --allow-unauthenticated --workdir /tmp/farhand-dev

fhd warns on non-loopback binds: without --tls, tokens travel in cleartext — use --tls / --tls-auto or a tunnel on untrusted networks. Concurrent connections are capped via --max-connections (default 32).

(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, initialize Farhand configuration automatically:

# Auto-detect project type and generate .farhand.yaml
fh init

# Or optionally generate customizable template definitions (.farhand/templates/<name>.yaml)
fh init --with-template

This generates a .farhand.yaml tailored to your project:

# .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

# Continuous watch mode: sync and rebuild on local file saves
fh watch cargo check

# Interactive remote workspace shell (allocated PTY inside remote repo)
fh shell

# Ad-hoc command execution (bypasses dependency hooks and artifact downloads)
fh exec -- git status

# Override or suppress artifact downloads on the fly
fh -o target/release/my-bin -- cargo build --release
fh --no-output -- cargo test

# 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

# Zero-config TLS with SHA-256 fingerprint verification
fh --tls --tls-fingerprint "7f9a8b1c2d3e4f50..." -- cargo check

# Select language toolchain version on the fly
fh -T rust=nightly -T node=22 -- npm run build

# Inspect execution history and agent status (including available remote disk space)
fh history

# See exactly what a build would transfer — nothing leaves your machine
fh sync --dry-run
fh sync --list           # ...and name every file in the transfer set
fh sync                  # actually sync, without running a build

# Ask why any single path is (or is not) on the agent
fh why src/main.rs       # uploaded, or a content-addressed hit?
fh why node_modules/x.js # excluded — and by which rule

# One-shot diagnosis: config, token handling, transport, connectivity, and agent capacity
fh doctor

# Watch mode honours each template's ignoreExtra, and the debounce is tunable
fh --watch --watch-debounce 400 -- npm run build

# Nix (flake or plain nix-build)
nix build .#fh && ./result/bin/fh --help
nix build .#fhd
nix develop          # dev shell with rust-analyzer, cargo-audit, cargo-deny

# Shell completions and man pages, generated from the binary's own CLI definition
fh completions bash > /etc/bash_completion.d/fh
fh man --dir /usr/share/man/man1

# Prometheus metrics for Grafana/Prometheus (opt-in on the agent)
fhd --listen 0.0.0.0:9876 --token "$FARHAND_TOKEN" --metrics-port 9100

# Live terminal resource dashboard & host telemetry
fh top                  # Interactive live TUI (CPU, RAM, Disk, Active Builds)
fh top --once           # Print snapshot and exit
fh agent info           # Formatted host specs, cores, load averages, memory
fh agent info --json    # Machine-readable JSON telemetry

# Remote Language Server Protocol (LSP) offloading (rust-analyzer, pyright, gopls, etc.)
fh lsp -- rust-analyzer

# 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

Performance

Measured with criterion (cargo bench -p fileset -p workspace, release profile) on an Intel Core Ultra 7 256V, /tmp on tmpfs — full methodology and reproduction steps in BENCHMARKS.md:

Reproduce: scripts/run_benchmarks.sh regenerates BENCHMARKS.md from criterion's saved estimates.

Detailed Documentation

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

• 📈 Observability — live fh top, plus an opt-in Prometheus endpoint (fhd --metrics-port) with an importable Grafana dashboard.
• 📖 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).
• ⚡ Language Server Protocol (LSP) Offloading Guide — Offload rust-analyzer, pyright, gopls, and clangd to remote agent with VS Code, Neovim, Helix, and Zed.
• ☁️ Remote Access via Cloudflare Tunnel — Connect securely over the internet with cloudflared access tcp without opening inbound router ports.
• 📏 Benchmarks — Reproducible criterion numbers behind the performance claims above.

Project & Community

• 📜 Changelog — Notable changes per release.
• 🤝 Contributing Guide — Dev setup, code style, commit conventions, testing expectations.
• 🔐 Security Policy — Supported versions, private vulnerability reporting, and the fhd threat model.

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.