farhand-workspace 1.10.2

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?

	Farhand	VS Code Remote SSH	Bazel remote exec	mosh + tmux	`ssh` + `rsync`
Scope	Run one command on a build box	Full remote dev environment	Hermetic reproducible builds	Resilient shell over lossy links	Ad-hoc file + command copy
Zstd wire compression	Yes, negotiated	No	Bazel-specific	No	gzip or none
Cross-project content dedup (CAS)	Yes	No	Content-addressable store	No	No
Dependency cache survives between runs	Yes, per branch	Yes	Yes (natively)	n/a	Often wiped or conflicts
Bring a dev server back to `localhost`	Yes, `-L`	Yes	No	No	Needs a separate `ssh -L`
Cancel kills the whole remote process tree	Yes	Yes	Yes	n/a	Often orphans it
Language-server offload	Yes	Yes	No	No	No
Multi-agent failover	Yes	No	Yes	No	No
External binaries required	None	VS Code, extension host	Bazel, RBE	mosh, tmux	ssh, rsync, tar
Local CPU still used for build	Never	Configurable	Never	Yes, always	Yes, always
Windows agent host	Yes	No	Rarely	No	No
Hermetic/reproducible by construction	No — it runs your build	No	Yes	No	No
Works without a project system (no Bazel setup)	Yes	Yes	No	Yes	Yes

Where Farhand loses, plainly. It is not a hermetic build system: Bazel reproduces a result from a content-addressed graph, while Farhand runs whatever your project's own tooling runs and inherits its determinism. It cannot replace Bazel for that reason. It has no Windows agent story beyond the basics, it cannot make your local machine faster by moving only part of a build, and because the remote box keeps its own node_modules/target, a mismatch between local and remote toolchain versions is your problem to manage. VS Code Remote gives you a whole remote environment, not just a command runner.

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.
⚡ Stat-Gated Warm Sync: the agent keeps a digest index (.farhand-hashindex.json) in each workspace, so an unchanged build re-stats the tree instead of re-reading it. A warm no-op sync costs ~1.1 ms on a 320-file tree rather than a full re-hash. Cold scans hash in parallel across all cores.
🍏 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.
🔌 Reverse Port Forwarding (-L): run the dev server on the build box and open it on your laptop as if it were local — fh -L 3000:3000 -- npm run dev, then browse http://localhost:3000. Repeatable, loopback-only, and multiplexed over the existing build connection, so there is no second tunnel to keep alive and no extra inbound port on the agent. See the guide.
🌐 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.

How It Works

   your machine                              the build box
┌────────────────────────┐              ┌──────────────────────────┐
│  you edit files        │              │  fhd                     │
│        │               │              │    ├── auth + TLS        │
│        ▼               │   one TCP    │    ├── workspace per     │
│  fh                    │  connection  │    │   project + branch    │
│    ├── scan + SHA-256  ├─────────────►│    │     (CoW-cloned)       │
│    ├── diff vs agent   │   frames:     │    ├── CAS: content       │
│    ├── delta tar ──────┼─────────────►│    │   addressed, shared   │
│    │                   │              │    ├── run in its own     │
│    ◄── live stdout ────┼──────────────┤    │   process group       │
│    ◄── stderr ─────────┼──────────────┤    └── send artifacts      │
│    ◄── artifacts ──────┼──────────────┤                          │
│    │                   │              │  ~/.farhand/workspaces/  │
│    └── -L 3000:3000 ───┼─────────────►│      my-app__main        │
└────────────────────────┘              │      my-app__feat-x     │
                                        │      cas/objects/…       │
                                        └──────────────────────────┘

Logs, file deltas, artifact transfer, and port forwards all ride the same multiplexed connection — there is no second tunnel to open and no extra port on the agent. -L reopens a port on your loopback that the agent relays to its own, so a dev server on the build box appears at localhost locally. Full protocol detail in the architecture guide.

The Two Binaries

fh (Client): Scans the local project directory, hashes files, uploads deltas, requests remote command execution, streams live logs, and retrieves generated artifacts.
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

Using cargo? The crate is farhand-cli / farhand-agent, not farhand — that name belongs to an unrelated project on crates.io. See the "Via Cargo" section below for the exact commands.

⚡ 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

Pre-compiled static release packages, each published with a .sha256 alongside it. These latest links always resolve to the newest release, so this table cannot go stale:

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

🍺 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 is not called farhand. cargo install farhand installs someone else's project — an unrelated tool already owns that name on crates.io. The crates here are farhand-cli (the fh client) and farhand-agent (the fhd daemon). Note the split: cargo install takes crate names, while the binaries you run are fh and fhd. The Homebrew formula, by contrast, really is farhand — so brew install farhand is correct and cargo install farhand is not.

☁️ 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

# Run the dev server on the build box, browse it at localhost:3000
fh -L 3000:3000 -- npm run dev

# Or declare it once in .farhand.yaml, then just run the build:
#   forward:
#     - "3000:3000"

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

Metric	Result
Delta tar pack, zstd-3 vs gzip (2.4 MiB payload)	74 ms vs 312 ms → 4.2× faster
Delta tar unpack, zstd vs gzip	18 ms vs 57 ms → 3.1× faster
Scan + SHA-256 hash, 320 files (~2.4 MiB)	3.1 ms (parallel across cores)
Warm sync of an unchanged workspace	1.1 ms — stats only, reads no file content
CAS hydration (CoW reflink), 256 KiB file	~24 µs (flat vs payload size)
Workspace branch clone (CoW, 100-file tree)	~4 ms

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

End to end, on a real project

The microbenchmarks above measure the parts. This is the whole command, fh <anything>, against a live agent over loopback, on a 304-file Rust project (~1.2 MiB of source):

Run	Wall clock	Agent scan
First build (cold workspace)	255 ms	305 files hashed
Second build	168 ms	305 files re-hashed — see below
Third and every run after	~150 ms	304 digests reused, 0 re-hashed

Two honest notes. The second run deliberately re-hashes everything: a file whose mtime is not strictly older than the digest index's own write is treated as unsafe rather than trusted, and everything synced a moment earlier falls inside that window. The gate engages from the third run on, and costs one re-hash in exchange for never trusting a file that changed in the same tick it was recorded.

And the 150 ms floor is process start, handshake, and round trips — at 304 small files the fixed costs dominate, so the end-to-end win here is roughly 40%. The win is in the scan itself (3.11 ms → 1.13 ms on this fixture), and that is the term that grows with your tree; on a project ten times this size the fixed costs are the same and the scan is the part that hurts.

Detailed Documentation

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

🖥️ CLI Reference — Every command, subcommand, and flag, plus the exit-code contract.
📦 Templates — How build templates detect projects and drive dependency installs, and how to override them.
🖧 The Agent (fhd) — Every daemon flag, the security posture, resource limits, GC and CAS tuning, and running it as a service.
🙈 Ignore Rules — What gets synced and what does not: built-in defaults, .gitignore, .farhand-ignore, and template rules.
📈 Observability — live fh top, plus an opt-in Prometheus endpoint (fhd --metrics-port) with an importable Grafana dashboard.
🍏 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.
🔌 Reverse Port Forwarding Guide — Run a dev server, database, or any port on the build box and reach it at localhost with -L, multiplexed over the existing build connection.
☁️ 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.

Recipes

🍳 Migrate from rsync + ssh — what the script did, what replaces each part, and how to check a path is actually being sent.
⚙️ Run in GitHub Actions — using a cheap hosted runner for orchestration while the build happens on a machine you control.

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.