AgentReach

Point your coding agent at any box you can SSH into. The server never gets your agent.

Why this exists

Think about the last time you SSHed somewhere to fix something. A build box, a client's staging VM, a container you spun up this morning and will throw away tonight. You'd get through it faster with an agent riding along.

So you install one there. That's a 300 MB Node binary on a machine that isn't yours, plus an API key pasted in so the thing can actually do anything. Now your key lives on a box where other people have root, in a shell history you won't clear, in an env file you'll forget about by Friday. If that server gets popped next month, your key goes with it.

Dev containers are the same story on repeat. New branch, new container, and each one wants its own copy of the agent. Baking it into the Dockerfile bloats an image that should have stayed small. Mounting it in from the host works right up until the morning it doesn't.

What reach actually does

The agent stays where it is. What moves is the work it hands off. An agent only touches a machine two ways — it runs shell commands, and it reads or writes files — and reach gets in the middle of both, on your side, before either one reaches your disk.

Commands. reach takes over whatever the harness spawns as a shell, unwraps the command, runs it over ssh on the target, and hands back stdout and an exit code. As far as the model can tell, it called Bash. Every harness offers some door in — a seam, a place where behaviour can be changed without editing the binary:

• Claude Code — CLAUDE_CODE_SHELL_PREFIX
• Goose — GOOSE_SHELL
• Codex — its remote-environment protocol
• opencode — a custom tool shadowing the built-in one
• anything else — reach's own bash, earlier on PATH, winning the lookup

Files. Depends on the mode:

• exec mode — the agent's own Read, Write and Edit are switched off. They call the local filesystem directly and there is no seam to redirect them through, so the agent falls back to its shell, which is already remote.
• mirror mode — reach answers those calls itself, pulling the file over the same ssh connection when a tool opens it and pushing it back when it changes. Wired up for Claude Code today.

What this isn't. No syscall tracing. No filesystem in any of it: no SSHFS, no FUSE, no mount, no file synchronisation between the two machines. reach sits at the seam where the agent hands work to the operating system, one request and one response at a time.

HOW-IT-WORKS.md walks a single tool call through the whole path, in figures.

What it looks like

$ reach build-box claude
probing ssh://build-box ...
session "build-box" -> ssh://build-box/home/you
  target   Linux x86_64
  fileops  pipe (negotiated; nothing written to the target)
  search   ripgrep (fast, structured)
  connect  multiplexed (one authenticated connection, reused)
reach: Claude Code -> ssh://build-box/home/you (bash runs on the target)

> what's eating disk on this box?

Claude Code is running locally. The df and du and grep it decides to run happen on build-box. Files it reads come from build-box. If it rewrites a config, the new bytes land on build-box. Your own filesystem is untouched unless you specifically ask for something local.

Everything it did is on the record:

$ reach log
WHEN      ACTION  STATUS  DETAIL
14:02:11  exec    ok      df -h /
14:02:19  exec    ok      du -sh /var/log/*
14:02:30  write   ok      /srv/app/logrotate.conf
14:02:31  exec    exit 1  systemctl reload rsyslog

Install

go install github.com/bojieli/agentreach/cmd/reach@latest

Pre-built binaries are on the releases page. From source:

git clone https://github.com/bojieli/agentreach
cd agentreach
make install

There is also a container image on GitHub Packages, for when the machine you drive agents from is itself disposable — a CI job, a devcontainer, a jump box:

docker run --rm -v "$HOME/.ssh:/root/.ssh:ro" ghcr.io/bojieli/agentreach version

It carries an ssh client and the helper binaries for every target platform. Your keys and known_hosts have to be mounted in; there is nothing useful to bake into an image, and reach will not invent credentials it was not given.

The only thing reach needs is the ssh binary you already have. It shells out to that rather than speaking SSH itself, so ProxyJump, IdentityFile, Match blocks, hardware tokens and 2FA all keep working the way you've configured them.

You can sit in front of Linux, macOS or Windows. Targets can be anything POSIX you can reach over ssh://, docker://, podman://, or the usual user@host:/path shorthand.

Quick start

Name a machine, then name an agent:

reach build-box claude                        # an ssh_config alias; work where a login lands
reach ssh://build-box/srv/app claude          # ... or in a directory you name
reach client-box:/srv/app codex               # somebody else's server

reach opens one multiplexed SSH connection, asks the host what it can do, and launches the agent locally with its shell quietly redirected there. You talk to it like you always do. Nothing is written to that host unless you ask for the helper tier by name, and reach doctor tells you exactly what was found, which tier got picked, and whether anything is sitting on the target.

Any command takes a target, not just the agents:

reach build-box exec -- go test ./...
reach build-box doctor

Each target gets its own session, named after it, so several machines can be open at once — one terminal per box, and no bookkeeping to keep them apart:

$ reach status
NAME            TARGET                    MODE  FILEOPS  CWD
build-box-app   ssh://build-box/srv/app   exec  pipe     /srv/app
client-box-app  ssh://client-box/srv/app  exec  posix    /srv/app

A second command against a target reuses that session instead of probing again, so running one costs no more than typing it.

When you're finished:

reach down build-box-app

That closes the connection and leaves nothing behind.

For a session meant to outlive one agent — several commands, several days, a name you chose — bind it up front and address it by name:

reach up ssh://build-box/srv/app --name build
reach claude --session build
reach down build

Agents that work today

Those fall into three groups, plus one exception, and the group decides how much of the agent survives the trip.

Codex and opencode are the clean ones. Both document a way to change the machine their tools act on, so reach answers at the other end and the model keeps every tool it started with. Codex is the best fit reach has, because it has no file tools at all: apply_patch and the rest run as commands inside exec_command, so intercepting that one protocol leaves nothing behind to deny.

Claude Code, Goose and Kimi hand over the shell and only the shell. Their file tools call straight into Node's fs or Rust's std::fs, so reach denies them and the agent works through its shell instead, or in Claude Code's case mirrors them if you ask for mirror mode.

Gemini gives you no hook at all, so reach wins the PATH lookup for bash and hides the rest of the built-ins through excludeTools in a managed settings.json.

Crush is the exception to the nothing-installed rule. Its server mode is exactly the seam reach wants, and reach crush starts crush server on the target and tunnels the client to it, which means crush itself has to already be there.

Whichever group you land in, nobody logs in again. Subscription logins, OAuth tokens and API keys keep working exactly as they do now, because reach never touches them.

Commands

reach <target> <cmd>    bind a session to the target