farhand

FarHand

Gives a coding agent hands on a remote machine and keeps its hands off the local one. https://farhand.cogflux.io

FarHand is an MCP server. Point OpenCode, Claude Code or Codex at it, and every command the model runs and every file it reads or writes happens on a remote host over your existing SSH setup. The local machine stays closed, with one exception you control: a list of local folders the model may look into and upload from. Nothing that looks like a credential is ever sent to the remote, and everything that happens is written to a local audit log.

┌─ OpenCode ─┐   ┌─ Claude Code ─┐   ┌─ CogFlux (later) ─┐
│ thin plugin │   │ .mcp.json     │   │ --mcp-config      │
└──────┬──────┘   └──────┬────────┘   └─────────┬─────────┘
       └─────────────────┴── MCP over stdio ────┘
                       farhand (one binary)
        ┌──────────────────┼───────────────────┐
   remote tools       local tools          audit log
   remote_shell        local_ls / local_read     one JSON line per action
   remote_read/write  upload / download
   remote_edit/ls     (allowlisted folders only)
   remote_glob/grep
   remote_spawn/jobs/kill
        │
   your OpenSSH: ~/.ssh/config, keys, agent, jump hosts — one multiplexed session

Why not opencode serve on the remote?

That works, but the agent's provider keys and configuration have to live on the remote, and every agent needs its own way of doing it. FarHand keeps the agent — and its credentials — local, and gives every MCP-capable agent the same remote hands.

Install

Local: macOS or Linux with OpenSSH. Remote: Linux with bash, timeout (coreutils), base64, an SFTP subsystem (default in sshd), and ideally ripgrep for remote_glob / remote_grep (both fall back to find / grep). Windows is not supported: FarHand relies on OpenSSH connection multiplexing over a Unix socket.

Prebuilt binary (no Rust needed) — one file into ~/.local/bin, checksum verified:

curl -fsSL https://raw.githubusercontent.com/CogFlux/farhand/main/install.sh | sh

Or download farhand-<version>-<target>.tar.gz from the releases page yourself, or cargo binstall farhand.

npm (Node 18+) — a dependency-free wrapper that fetches the same release binary on first run, checksum verified:

npm i -g farhand

farhand install then writes the wrapper's entry, not the binary, into the agent's config, so npm i -g farhand@latest upgrades the agents too (the first run after an upgrade downloads the new binary); the agent needs node on its PATH. npx farhand init and npx farhand check are fine for a try, but farhand install refuses to run from npx's cache (or pnpm dlx, bunx), which is cleared behind the agent's back.

From source (Rust stable): cargo install --path crates/farhand puts farhand in ~/.cargo/bin; or cargo build --release and point FARHAND_BIN at target/release/farhand.

Then, either way:

farhand install opencode                  # and/or claude-code, codex — once per machine
cd ~/my-project
farhand init > .farhand.toml              # edit host, workdir, allowed_dirs
farhand check                             # connects once and reports

That is all: a project is remote exactly when it has a .farhand.toml. There is no global configuration to write unless you want one (see Configure).

See docs/USAGE.md for the step-by-step guide and per-agent configuration.

Update

farhand --version says which version you have. Update the way you installed:

Installed with	Update with
the install script	the same curl … | sh again
npm	npm i -g farhand@latest
cargo binstall	cargo binstall farhand
cargo install	cargo install farhand
a checkout	git pull && cargo install --path crates/farhand

Then run farhand install <agent> once more for each agent you use (it changes nothing if nothing changed: the OpenCode plugin and Codex's approval settings are written from the binary at install time), and restart the agent, whose running server is still the old one.

Configure

farhand init prints a commented template. The essentials:

[remote]
host = "devbox"            # an alias from ~/.ssh/config, or user@host
workdir = "~/proj"         # commands start here; relative paths resolve here; created if missing

[local]
allowed_dirs = ["."]       # the only local folders the model may see; "." = this folder

With "." the folder holding .farhand.toml is the project's local pocket: drop a file in it and the model can upload it, and download lands there. Nothing else lives in that folder — the code is on the remote — so this is the natural default. Absolute paths and ~/... work too; relative entries are only accepted in a project .farhand.toml, never .., / or ~.

The remote may be Linux, macOS, BSD — or Windows with OpenSSH Server, where commands run in PowerShell (os = "windows" under [remote] tells the model so up front; the platform is detected on connect regardless). Directory creation and tree walking go over SFTP, so uploads, downloads, remote_write and remote_edit behave the same everywhere. Transfers are streamed with many requests in flight, so a large file moves at link speed and memory stays flat whatever its size; the default cap of 1 GiB per transfer is max_transfer_bytes under [limits].

Config is found in this order: --config PATH, $FARHAND_CONFIG, ./.farhand.toml, ~/.config/farhand/config.toml. The per-project .farhand.toml is the normal one: it is what makes a directory remote. The global file is optional and serves two purposes: activation = "always" turns every directory on the machine remote using its [remote], and it is a convenient target for --config. Without any config at all, FarHand is simply inactive: the agent keeps its local tools and the server offers none.

Agents

farhand install <agent> does the wiring for opencode, claude-code and codex (--scope user|project); farhand uninstall reverses it and farhand status reports it. By default only directories that carry a .farhand.toml go remote (activation = "project"); everywhere else the agent keeps its local tools. activation = "always" in the global config makes every session remote. What each agent gets is in docs/USAGE.md.

OpenCode

farhand install opencode writes plugins/opencode/farhand.ts into ~/.config/opencode/plugins/ (or symlink it there yourself for development). The one file carries both plugin APIs, so it works with OpenCode 1.18.29+ and OpenCode 2 alike and survives an upgrade between them. The plugin registers the MCP server, removes OpenCode's local tools (bash/shell, read, write, edit, patch, glob, grep, list, the LSP tools, and in OpenCode 2 the browser_* tools and Code Mode's execute, since a local browser and execute's fetch can both open file:// URLs), refuses them again at call time as a second fence, and tells the model in the system prompt that it is working remotely.

Approval is FarHand's knob, not the agent's: [approval] mode = "ask" (default) makes the agent prompt before remote_shell, remote_write, remote_edit, remote_spawn, remote_kill, upload and download and lets read-only tools run; "auto" prompts for nothing, with the audit log as the record; "strict" prompts for everything, reads included; tools = { remote_write = "auto" } overrides per tool. A project .farhand.toml can make this stricter but not looser than the global config; auto belongs in the global file. The plugin translates this into OpenCode's permission system at startup.

Without the plugin, the same effect comes from opencode.jsonc (OpenCode 1 format shown; OpenCode 2 reads it too, but cannot remove browser_* from config alone — use the plugin there):

{
  "mcp": {
    "farhand": { "type": "local", "command": ["farhand", "serve"], "enabled": true, "timeout": 60000 }
  },
  "tools": { "bash": false, "read": false, "write": false, "edit": false,
             "glob": false, "grep": false, "list": false, "patch": false },
  "permission": { "farhand_remote_shell": "ask", "farhand_remote_write": "ask",
                  "farhand_remote_edit": "ask", "farhand_upload": "ask", "farhand_download": "ask" }
}

The tools then appear as farhand_remote_shell, farhand_upload, and so on.

Tools

Tool	What it does
remote_shell	Run a command on the remote in its own shell — POSIX shell, or PowerShell on Windows (bounded output, remote timeout, local watchdog).
remote_read	Read a remote file with line numbers; offset/limit page through it.
remote_write	Create or overwrite a remote file; parents are created.
remote_edit	Replace an exact, unique string in a remote file (replace_all optional; CRLF files are matched with LF strings and kept CRLF).
remote_ls / remote_glob / remote_grep	ls -la, rg --files -g, rg -n on the remote.
remote_spawn	Start a long-running command (dev server, watcher) in the background, detached from the session so it outlives the call; output goes to a log under ~/.farhand/jobs/ on the remote.
remote_jobs / remote_kill	List those jobs (running, or exited with their status), and stop one with the processes it started.
local_ls / local_read	Look inside the allowlisted local folders.
upload	Copy a local file or folder (allowlist only, guard-checked) to the remote.
download	Copy a remote file or folder into an allowlisted local folder (never credential-shaped names or files a local tool would execute).
remote_info	Host, workdir, connection state, allowed folders, audit location.

A command run by remote_shell lives as long as its SSH channel: Windows OpenSSH kills every process the session started when the command ends, and on POSIX a background child that keeps the output open holds the command until its timeout kills it. remote_spawn starts the job outside the session instead — in a session of its own (setsid, or perl where there is none) on POSIX, through WMI (Win32_Process.Create) on Windows — and records it on the remote, so a later FarHand session still lists and stops it.

What never leaves this machine

Every byte headed for the remote — command text, file content, edits, uploads, and every other argument (paths, cwd, search patterns and globs) — passes the secret guard first:

• by path (case-insensitively): .env*, *.pem, *.key, id_*, .netrc, .npmrc, credentials*, *service-account*.json, *.tfstate, agent configs (opencode.json*, .mcp.json, claude_desktop_config.json, ...), and anything under .ssh, .aws, .gnupg, .kube, .docker, .config, .claude, .opencode, .codex, ...;
• by content: private-key blocks, sk-…, ghp_… / github_pat_…, AKIA…, AIza…, xox…, Stripe, JWTs, Authorization: Bearer …, URLs with embedded passwords, and api_key = "<24+ random chars>" style assignments.

Add your own with [guard] deny_globs / deny_content. A refusal comes back to the model as a tool error naming the rule, never the matched text, and is audited the same way. There is no override flag.

The local environment is never forwarded to the remote. Commands run in the remote user's own login shell.

Threat model

FarHand is built so that the model can be wrong or hostile and the damage stays on the remote. What holds regardless of which model is driving:

• No local execution. The only process FarHand ever starts locally is ssh to the configured host (plus ssh -G to print its address). No model-supplied string reaches a local command line.
• Local reads are the allowlist, minus credentials. local_ls, local_read and upload resolve paths through the allowlist with symlinks followed first, so a link out of the folder is refused. The file is then opened from a handle on its allowed folder one component at a time without following a symlink, so a link swapped in after the check (by a sync tool, an editor, another process) is refused too. Files the guard would refuse to upload are hidden from local_ls and refused by local_read: what the model cannot see it cannot re-encode. An upload is scanned again as it streams, and no byte leaves before the guard has seen it, so a file that changes after its first scan cannot slip through. /, the home directory and any folder above it are not accepted as allowed folders.
• Downloads cannot plant anything. Every file a download would create is resolved through the allowlist again and checked by name (case-insensitively): nothing credential-shaped, and nothing an editor or agent executes or trusts on opening a folder (.vscode, .idea, .git, .husky, .envrc, .claude, .farhand.toml, CLAUDE.md, ...). A refused name aborts the whole download before the first byte is written. Folders on the way are opened and created without following symlinks, the data goes to a randomly named temporary file created exclusively in its folder, and is renamed into place within that same folder, so a link planted in the folder is replaced rather than written through. The size limit is enforced on the bytes actually read.
• Only hosts you have already met. SSH host keys are checked strictly: a .farhand.toml that arrives inside a cloned repository cannot point the agent at a machine you never connected to. Connect once by hand first.
• No way back over SSH. FarHand reads your ssh config through a wrapper that clears every port forwarding (RemoteForward, LocalForward, DynamicForward) and turns off agent, X11 and GSSAPI credential forwarding for its connection, whatever ~/.ssh/config says for the host. Keys, jump hosts and everything else still come from your config.
• A project file can only tighten. A .farhand.toml may arrive with a cloned repository, so it cannot loosen [approval] below the global config (or the default ask), allow local folders outside its own directory, or move the audit log. A relative folder must still be inside the project once symlinks are resolved, so an assets link to elsewhere is not a way out. Such settings are ignored, and farhand check and farhand validate say which. Put them in the global config instead. A global config that exists but does not load stops FarHand rather than being skipped.
• Everything is on record. Every call, including refusals, is one line in the audit log. A log directory that cannot be written stops FarHand at startup, and a record that cannot be written later makes FarHand refuse every further call until it is restarted.

What FarHand does not do: it cannot stop a model that has legitimately read a non-secret file in the allowlist from sending it to the remote (that is the point of the allowlist), it does not restrict the remote itself (treat the remote account as the model's sandbox and give it only what that account should have), and it does not disable other MCP servers or tools your agent has that reach the local machine. The agent integrations take the agent's own local tools away (Codex only at project scope), but that is the agent's setting, not a wall. Keep secrets out of allowed_dirs; the guard is a tripwire for accidents, not a substitute for that: a password, an archive or an encoded token can pass it. If the model must not reach the local machine even through a misconfigured agent, run the agent itself in a container or VM that mounts only the folder you allow.

There is deliberately no local curl/fetch tool: curl reads local files (-d @file, file://) and reaches local-only services (Docker sockets, IDE and browser debug ports, localhost dashboards), and an approval prompt is not a defence against a request that looks harmless. Fetch from the remote with remote_shell instead; the remote has curl too.

Audit log

~/.local/share/farhand/audit/YYYY-MM-DD.jsonl, one object per action: timestamp, session, host, tool, command or path, byte count, outcome (ok / denied / error / timeout), exit code, duration. File contents are never logged, and a command the guard refused is logged as redacted.

Layout

crates/farhand-core   config, guard, local allowlist, remote (ssh + sftp), transfer, audit
crates/farhand    the `farhand` binary: MCP tools over stdio
crates/farhand/plugins/opencode   the OpenCode entry point (embedded in the binary)
packages/npm/farhand  the npm wrapper (`npx farhand`), fetches the release binary

Claude Code

farhand install claude-code registers the server and adds a PreToolUse hook (farhand hook claude-code) that refuses local tools wherever FarHand is active and answers mcp__farhand__* calls from [approval] on every call; project scope also writes a static permissions.deny. Tested at project scope.

Codex

farhand install codex --scope project registers the server, turns Codex's shell tool off, sets the sandbox read-only and translates [approval] into per-tool approval_mode. User scope registers the server only.

Roadmap

• CogFlux integration: launched via --mcp-config, audit log as an ingest source.
• Several remotes per config with a host argument on the tools.