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

Developer dlhck released Ferry, an open-source tool that syncs coding agent setups — skills, instructions, MCP servers and supported settings — from a local machine to remote Linux boxes via a private git snapshot repository. Ferry installs and updates the claude, codex, pi and cursor-agent CLIs on each box, starts logins there without copying tokens, and offers ferry watch, ferry tunnel --follow, ferry move and ferry auth commands, installable via curl or npm i -g @dlhck/ferry on macOS or Linux, arm64 or x64.

Your agent setup. 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 cmd-watch - 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 cmd-tunnel - 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 cmd-move - Logins stay where they are.Ferry starts logins on the box and never copies a token. ferry auth cmd-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. 1. 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. 2. Private snapshot repoAn empty private git repository you create. Ferry publishes the carried files to it. 3. 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 and apiKeyHelper stay on your machine. - Login - ferry auth claude , finished in a browser here. MCP logins with ferry auth claude --mcp <server . - Codex codex - Carries - ~/.codex/AGENTS.md and the remote and stdio MCP servers in mcp 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 https://github.com/michaelbromley/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 https://github.com/dlhck/ferry/issues . 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 a waybar module https://github.com/dlhck/ferry/blob/main/docs/linux-status-bar.md on Linux. After setup, you keep working here The commands you use after setup, with the details. 1. ferry watch installSyncs each change after one second. It runs as a launchd or systemd user service. 2. 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. 3. 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. 4. 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. 5. ferry box add <name Adds another box. sync , status and update act on all boxes, or on one with --box . 6. ~/.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 run ferry 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. 7. 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. 8. 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. Run ferry expose on the box and ferry tunnel --follow here, and each dev server port opens on its own. 9. 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 and codex 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. 10. 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. 11. ferry skills addInstalls skills with npx skills add as a global copy, so Ferry carries them. 12. ~/.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. 13. tools.<id Each tool in the config has a version policy: "operator" , "latest" or an exact version. The menu bar and ferry 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 With curl or wget . Debian and Ubuntu are tested. - A way to reach it Tailscale on both machines, or an OpenSSH destination like user@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.