Show HN: Ferry – Sync your coding agent setup to remote Linux boxes

wpnews.pro

Wherever you run.

Run agents on your laptop or a remote Linux box with the skills, instructions, MCP servers and supported settings you already use. Ferry keeps them in sync as you work, so every box gets your setup without you rebuilding it by hand.

Change a skill locally. Your remote agents get it too.

curl -fsSL https://raw.githubusercontent.com/dlhck/ferry/main/install.sh | sh npm i -g @dlhck/ferry macOS or Linux, arm64 or x64. With npm, do not pass --omit=optional. Update later with ferry self-update.

Stop setting up the same workflow on every machine. #

You've taught your agents how you work. Moving to a remote box should carry that work with you.

Configure once. Keep every box in sync.Update your skills and instructions on your machine. Ferry's watcher sends those changes to your boxes automatically. `ferry watch install`

Open remote previews in your local browser.Forward remote dev server ports to localhost, with automatic forwarding for servers announced through Ferry. `ferry tunnel --follow`

Continue your project on another machine.Move a Git project to a box and back, with its untracked files and its Claude and Codex sessions, so you can resume the conversation there. `ferry move`

Logins stay where they are.Ferry starts logins on the box and never copies a token. `ferry auth`

Your machine publishes. Each box pulls. #

Your machine is the source of truth. The boxes follow it through a private git repository that Ferry calls the snapshot.

Your machineYour skills, `~/AGENTS.md` , Claude subagents, commands and hook scripts, some Claude, Codex, Pi and Cursor Agent settings, and remote and stdio MCP servers.

Private snapshot repoAn empty private git repository you create. Ferry publishes the carried files to it.

box a, box b, ...Each box clones the snapshot and links its harness directories to it.

It also sets up the box

Ferry installs and updates the agent CLIs on each box (claude, codex, pi, cursor-agent), plus gh, jq and the tools you list. It starts logins there. It never copies one.

See the plan first

--dry-run on init, sync, update, move, revert and box remove shows what Ferry will do. --json on any command gives output for scripts and agents.

Four agents, ready on every box #

For each agent, Ferry installs and updates the CLI on the box and starts its login there. Codex, Pi and Cursor Agent read the shared skills in ~/.agents/skills, and Claude Code reads its own in ~/.claude/skills. The instruction files of Claude Code, Codex and Pi link to your ~/AGENTS.md. On a box, a header that names the box and your instructions for that box come first.

Claude Code`claude`

Carries
Skills in ~/.claude/skills ,~/.claude/CLAUDE.md , subagents, custom commands, hook scripts in~/.claude/hooks , and the remote and stdio MCP servers in~/.claude.json .
Settings
enabledPlugins ,extraKnownMarketplaces ,permissions ,hooks ,attribution ,includeCoAuthoredBy ,model ,alwaysThinkingEnabled . The box installs the plugins.env andapiKeyHelper stay on your machine.
Login
ferry auth claude , finished in a browser here. MCP logins withferry auth claude --mcp <server> .

Codex`codex`

Carries
~/.codex/AGENTS.md and the remote and stdio MCP servers inmcp_servers . Skills come from~/.agents/skills .
Settings
model ,model_reasoning_effort ,model_reasoning_summary ,model_verbosity ,features ,web_search . Providers, profiles,notify and project trust stay on your machine.
Login
ferry auth codex with a device code.

Pi`pi`

Carries
~/.pi/agent/AGENTS.md . Skills come from~/.agents/skills .
Settings
defaultProvider ,defaultModel ,defaultThinkingLevel ,enabledModels ,thinkingBudgets ,enableSkillCommands in~/.pi/agent/settings.json . Packages, resource paths, the shell path, and the npm and shell commands stay on your machine.
Install
Ferry installs and updates Pi. It installs Node and npm first if the box has none, or a Node that is too old.
Login
By hand. Ferry cannot drive the Pi login. SSH to the box, run pi , then use/login .

Cursor Agent`cursor-agent`

Carries
Remote and stdio MCP servers, merged into ~/.cursor/mcp.json . Skills come from~/.agents/skills .
Settings
model ,maxMode ,hasChangedDefaultModel ,attribution in~/.cursor/cli-config.json . Permissions, the status line and the login state stay on your machine.
Login
ferry auth cursor .

GitHub CLI and jq

Ferry installs gh and jq on every box. ferry auth gh logs gh in on the box and sets up the box SSH key for GitHub. The box uses jq to merge the carried settings keys and MCP servers into its own files. It sends back only a status, never the file.

Your own tools

Add any other tool in a [tools.<id>] table with a version policy: "operator", "latest" or an exact version. With auth_status, auth_login and auth_hosts, ferry auth <id> logs it in.

Integrations

Paseo

ferry integrations enable paseo Runs the Paseo daemon on a box. Ferry carries your agent profiles, managed Git plugins at their installed commit, npm plugins at their installed version, the portable fields of provider definitions, metadata model preferences, shared system instructions, and portable terminal profiles. These go to the box directly, not through the snapshot.

With paseo_auto_archive = true, Ferry also carries the auto-archive-after-merge switch. When ferry move puts a project on a box with Paseo, Ferry registers the project and imports each carried session as a Paseo agent. A move back does the same in the Paseo on your machine.

Plugin settings, provider env blocks and commands, terminal env blocks and paths, and credentials stay on each host. When one agent process runs out of memory, the daemon and the other agents keep running. Set paseo_relay = true for relay pairing.

Sherlock

ferry integrations enable sherlock With Sherlock on your machine, Ferry adds ferry sherlock add <name> --box <box> --target <host:port> --type <type>. It registers a Sherlock connection that tunnels through the box on the first query, so Sherlock can query a database on the box, or one that only the box can reach.

Sherlock keeps the password in the keychain of your machine. Ferry never stores it and never edits the Sherlock config. ferry status checks that each box can reach its target.

ferry integrations lists the part of each integration: box for a service on the box, operator for commands and checks on your machine. More agents and integrations are planned. Request one on GitHub.

Works with

Tailscale or plain OpenSSH The link to each box.
Any private git host Holds the snapshot. An SSH URL needs an SSH agent with a key that can push.
npx skills add Through ferry skills add , as a global copy that Ferry carries.
launchd and systemd User services for watch and tunnel, on macOS and Linux.
The macOS menu bar and waybar The Ferry menu bar app on macOS, and awaybar module on Linux.

After setup, you keep working here #

The commands you use after setup, with the details.

ferry watch installSyncs each change after one second. It runs as a launchd or systemd user service.
ferry status --briefShows only what needs action: offline boxes, low disk or memory on a box, logins, MCP logins, stdio MCP servers that lack something on the box, tool drift, and hooks that run a home file Ferry does not carry. Plain ferry status checks the link, the snapshot, the logins and the tools.
ferry doctorChecks the SSH agent, push access to the snapshot, SSH and Tailscale to each box, the box deploy key, linger and the installed services. It changes nothing and prints a fix for each failed check.
ferry revert <commit>Undoes one snapshot commit on your machine, including the carried settings keys, then syncs all boxes. ferry history lists the last 20 commits and the paths each one changed.--no-sync skips the sync.
ferry box add <name>Adds another box. sync ,status andupdate act on all boxes, or on one with--box .
~/.ferry/boxes/<name>/AGENTS.mdInstructions for one box, for example "this box runs the staging database". On a box, each instruction file is a Ferry header that names the box, then this file, then your ~/AGENTS.md . Agents runferry whoami to check where they are. The file never goes into the snapshot.ferry box add creates it empty. For your first box, create it by hand.
ferry box remove <name> --uninstallRemoves Ferry from a box, then the box from your config. Ferry prints the plan and asks you to type the box name. Its services, links, checkout and binary go. Logins, SSH keys, projects and installed tools stay on the box.
ferry tunnel 3000Opens a box port on 127.0.0.1 on your machine. ferry tunnel db.example:5432:15432 opens port 5432 of a host that the box can reach, such as a database that only accepts connections from the box network, on local port 15432. Ferry checks first that the box can connect to it. Runferry expose on the box andferry tunnel --follow here, and each dev server port opens on its own.
ferry move <path> --to-box <name>Carries a git project to a box, untracked files included, with the Claude and Codex sessions of the project and the Claude project memory, so claude --resume andcodex resume find them there.--from-box brings the project back. A session that fails the deny rules stays on the source. The scan cannot find a password that you typed in free prose, so use--no-sessions when a session can hold one.
ferry adopt --from-box <name> <skill>Copies a skill that an agent wrote on a box to your machine. The Ferry on the box runs the deny rules first, and you see the diff or the file list before Ferry asks. Then ferry sync publishes it to every box.ferry status lists the box-only skills.
ferry skills addInstalls skills with npx skills add as a global copy, so Ferry carries them.
~/.agents/skills/ferryThe Ferry skill. It tells your agents how to work with Ferry on both machines, for example not to edit a Ferry-managed file on the box. ferry init writes it here and the snapshot carries it to the boxes.ferry self-update refreshes it.ferry init --no-skill leaves it out.
[tools.<id>]Each tool in the config has a version policy: "operator" ,"latest" or an exact version. The menu bar andferry status report drift.

What boards, and what stays ashore #

Ferry carries configuration. It does not carry anything that proves who you are.

Boards the ferry

Skills
Agent instructions in ~/AGENTS.md , and your instructions for one box
Subagents
Custom commands
Hook scripts
Agent CLI settings, without the keys that can hold secrets
Remote and stdio MCP servers, without env values
ADE setup, such as agent profiles, plugins and providers, through an integration

Stays ashore

Logins
Credential files
Tokens and API keys
.env files
Env values of MCP servers
A credential in the origin URL of a project
Whole settings files

These never leave the machine that has them.

Checked before each publish

Deny rules catch secret files, private keys, tokens, secret config keys and executable binaries. Scripts, such as hook scripts, pass and keep their executable bit. A match stops the sync. The error names the file, never the value.

Stdio MCP servers carry no values

Ferry carries the command, the arguments and the names of the env keys. You set the values on the box, and Ferry keeps them. A token, a secret flag with a value, or a URL with a credential in the command or the arguments stops the sync. Ferry skips a server that runs an inline script, such as sh -c or node -e, because it cannot check the script, and a server that refers to a path in your home. It never installs a command.

What leaves a box is checked on that box

For ferry move --from-box and ferry adopt --from-box, the Ferry on the box runs the deny rules. It reads each file once and sends exactly the bytes that pass. A refused file sends no content and no hash, and a name that looks like a token arrives as [token]. Your machine then applies its own rules to the bytes that arrive.

Boxes do not trust each other

Ferry connects to each box from your machine. ferry move from one box to another goes through your machine too, and the same deny rules apply.

No new doors

Ferry opens no public port and never turns off SSH host-key checks. It forwards your SSH agent only for snapshot checks, updates and Claude plugin installs. A box with git_auth = "box" gets no agent and reads the snapshot with its own read-only deploy key.

The rule needs an honest box

No credential leaves the machine that has it. That holds for a box that runs an unchanged Ferry. The check on the box protects against mistakes and against files that change. It does not protect against a box account that an attacker controls, because that Ferry can give any answer and any bytes. Ferry runs commands as your SSH user, so use a box and a user that you trust with the agents that run there.

ferry auth claude Starts a login on the box. You finish it in a browser on your machine. The token stays on the box.

Six commands to a synced box #

Run them on your machine. Ferry reaches the box over SSH or Tailscale.

You need

A Linux box you can reach with SSH Withcurl orwget . Debian and Ubuntu are tested.
A way to reach it Tailscale on both machines, or an OpenSSH destination likeuser@box.example .
An empty private git repository This becomes the snapshot. For an SSH URL, you also need an SSH agent with a key that can push to it.

ferry init --ssh-destination user@box.example \
  --snapshot-url git@github.com:you/ferry-snapshot.git
ferry install        # gh, jq, the agent CLIs, your tools, and Ferry on the box
ferry sync           # publish the snapshot and apply it on the box
ferry auth claude    # start a login on the box, finish it in a browser here
ferry watch install  # sync each change automatically, as a user service
ferry status         # check the link, the snapshot, the logins, and the tools

Add --dry-run to init or sync to see the plan before anything changes.

source & further reading

dlhck.github.io — original article