Commands
This page has the --help text of each Ferry command and subcommand, from the Ferry source. Run ferry <command> --help to get the text of your version.
The ferry sherlock commands exist only when the Sherlock integration is on and sherlock is on the PATH.
ferryferry initferry installferry updateferry uninstallferry authferry syncferry historyferry revertferry moveferry cpferry secretsferry adoptferry tunnelferry exposeferry notifyferry statusferry doctorferry integrationsferry sherlockferry toolsferry psferry usageferry watchferry menubarferry self-updateferry whoamiferry relayferry messagingferry messaging enrollferry messaging setupferry messaging teardownferry messaging statusferry messaging conversationsferry messaging showferry messaging requestsferry messaging peersferry messaging devicesferry messaging revokeferry messaging leaveferry messaging remoteferry messaging relay-url
ferry configferry boxferry skills
ferry
Usage: ferry [options] [command]
Ferry keeps a remote Linux agent box in the same shape as this machine.
Use ferry init to record a Tailscale host or OpenSSH destination and seed the
private snapshot.
Ferry never copies logins. Vendor sessions stay on the machine that created
them. Ferry starts a login on the box and you finish it in a browser here.
Options:
-V, --version output the version number
--box <name> select a box of the config; repeat it to
select more boxes
--json print JSON on stdout: one result
envelope, or one event for each line for
watch, tunnel, and expose. Progress goes
to stderr
-h, --help display help for command
Commands:
init [options] Record a Tailscale host or SSH
destination, seed the snapshot, and
convert this machine
install [options] Install the supported agent tools on the
configured box
update [options] Update the agent tools on the configured
box and on this machine
uninstall [options] Remove Ferry's local state and restore
paths changed by init
auth [options] [provider] Start a login on the configured box
without copying credentials
sync [options] Publish the snapshot and apply it to the
selected boxes, or to all boxes
history [options] List the recent snapshot commits and the
paths each one changed
revert [options] <commit> Undo one snapshot commit on this machine
and on all boxes
move [options] <path> Continue a project on a box, on this
machine with --from-box, or on another
box with both
cp [options] <source> <destination> Copy one checked file between this
machine and a box
secrets Provision selected environment variables
on one box outside the snapshot
adopt [options] <skill> Copy a skill that an agent wrote on a box
to this machine
tunnel [options] [ports...] Open box ports on this machine until
Ctrl-C, list the ports that listen on the
box, or follow the ports of ferry expose
expose [options] <command...> Run a command on the box and announce its
port to ferry tunnel --follow
notify <harness> <kind> Record an agent event on the box for the
menu bar app of the operator machine
status [options] Inspect link, snapshot, managed paths,
and box logins without writing
doctor Check SSH, Tailscale, snapshot access,
linger, and services, and print a fix for
each failure
integrations List the integrations of each box,
whether each one is enabled, its parts,
and the local app versions
sherlock Add Sherlock database connections that
tunnel through a box
tools List the tools, the version policy of
each one and of each box, and the
versions on this machine
ps List the agent processes on each box,
with their memory and CPU
usage [options] Show the tokens of the agents on each
box, for each harness and project
watch Watch the portable set and sync accepted
changes
menubar Install or remove the macOS menu bar app
that shows what needs action on the boxes
self-update Update Ferry on this machine to the
latest release.
Ferry updates in the same way as it was
installed: with npm, or with the
release installer in the directory of
this binary. It restarts installed
watch and tunnel services that point at
this Ferry. On macOS, it also updates
an installed release menu bar app. It
writes the Ferry agent skill of the new
version to ~/.agents/skills/ferry, unless
ferry init --no-skill turned it off
or the skill folder has local changes.
Then run ferry update to put the new
version on the boxes.
A release is visible before its build
attaches the files. When the latest
release does not have its files yet,
Ferry says that the release is not ready
and does not start the update. This is
not an error. Run the command again
some minutes later.
On a terminal, each command also asks to
update when a newer release is
there. Ferry reads the latest release at
most once a day. It does not ask
with --json, with CI set, or with
FERRY_NO_UPDATE_CHECK=1, and it does not
ask for a release that does not have its
files yet.
whoami Print the role of this machine: the
operator machine or a Ferry box.
On a box, Ferry also prints the box name
from the last ferry sync, and the
parts of the generated instruction file
~/.ferry/box/AGENTS.md in their
order: the Ferry header, the per-box
instructions from
~/.ferry/boxes/<name>/AGENTS.md on the
operator machine when the box has
them, and the shared ~/AGENTS.md. The
operator machine is the source of
truth. On a box, change a Ferry-managed
file on the operator machine, not
on the box. This command runs on the
operator machine and on a box install.
The managed paths of a box are the paths
that the last ferry sync linked
there: the instruction files, the skill
roots, and the other roots of the
harnesses that are on for the box, with
the custom harnesses of the config.
A box that an earlier Ferry synced has no
such record until the next sync.
Until then, Ferry lists the paths of the
built-in harnesses that are links
of Ferry on the box.
relay Run the team relay of agent messaging on
this machine
messaging Let Claude Code and Codex sessions of a
team send messages to each other
config Read and change some keys of
~/.ferry/config.toml
box List, add, and remove the boxes of the
config
skills Install skills into the global harness
roots that Ferry manages
JSON output (--json):
stdout has only JSON. Progress and the text lines go to stderr. Ferry
shows no prompt: a confirmation fails with confirmation-required unless
you give --yes. The SSH host keys of init and box add need
--accept-host-keys: --yes does not trust them, and error.details.hostKeys
lists them. A command that runs and exits prints one envelope:
{"schemaVersion":1,"command","ok","result","warnings","error"}
error is null, or {"code","message","hint"}. On failure, ok is false and
the exit code is not 0. A sync-busy error names the box and the command
that holds its lock, also in error.details.box and error.details.owner
({"pid","command","earlierVersion","otherProgram"}). A failed update, or a failed sync of more than
one box, keeps the outcome of each box in result. watch, tunnel,
tunnel --follow, and expose print one event for each line. Each event
has "type". An error event also has "code", "message", and "hint".
Error codes: usage, config-missing, config-invalid, unknown-box,
box-required, box-offline, box-command-failed, forward-failed,
confirmation-required, missing-values, deny-rule-match, refused,
sync-busy, sync-failed, update-failed, login-failed, command-failed,
failed.
Event types: watch-started, synced, sync-failed, sync-refused,
content-refused, config-error, update-started, update-failed,
status-failed, watch-stopped, following, forward-opened, forward-closed,
forward-failed, connection-lost, tunnel-closed, exposed, exited, login,
error.
The help of each command gives its result. The ferry agent skill
describes the full contract.
ferry init
Usage: ferry init [options]
Record a Tailscale host or SSH destination, seed the snapshot, and convert this
machine.
The snapshot URL is an empty private git repository. Ferry does not create it.
For an SSH snapshot URL, load a key that can push to it into your SSH agent.
Ferry forwards the agent to the box to test read access, and asks before it
trusts the Git host key on the box. Ferry never falls back from Tailscale to
direct SSH.
With box tables, init runs again for the box of --box, else default_box, else
the only box. Use ferry box add to add a box.
Init writes the Ferry agent skill of this version to ~/.agents/skills/ferry,
so the snapshot carries it to the boxes. ferry self-update writes the skill
of the new version. Ferry does not change a skill folder with local changes.
Add a custom harness in ~/.ferry/config.toml. A repeat init keeps it:
[[harness]]
id = "opencode"
name = "OpenCode"
skill_root = ".config/opencode/skills"
instruction_file = ".config/opencode/AGENTS.md"
Options:
--host <host> Tailscale host name or IP address
--ssh-user <user> SSH user on the host
--ssh-destination <destination> explicit OpenSSH destination
--snapshot-url <url> private snapshot git URL
--dry-run print the init plan without writing or
connecting
--accept-host-keys trust the SSH host keys of the snapshot host
on the box without a confirmation prompt
--no-skill do not install the Ferry agent skill. Ferry
records the choice, and self-update then
skips the skill too
-h, --help display help for command
With --json: { dryRun, leftovers, published, skill: { action, path, message } }, or with --dry-run { dryRun, leftovers, plan }.
ferry install
Usage: ferry install [options]
Install gh, jq, the agent CLIs, the tools of the config, and Ferry on the box.
Ferry prints the plan for each tool and asks before it runs a command on the
box. gh and jq come from apt, so Debian or Ubuntu is the tested target. Ferry on
the
box is the version of this machine. It is a box install that runs only
ferry expose, ferry notify, and ferry whoami. Run ferry tools --help for the
tool config.
Options:
--yes run without a confirmation prompt
-h, --help display help for command
With --json: { plan: [{ tool, policy, version, action, command, dependsOn }], gitIdentity }.
ferry update
Usage: ferry update [options]
Update the agent tools on the boxes and on this machine.
On this machine, Ferry updates only the agent CLIs that are installed. It does
not update Ferry itself. Each box gets the tool versions of its policy, the
Ferry version of this machine, and Paseo when the integration is on. The Paseo
update restarts the daemon, which stops the agents on the box.
With [update] watch = true in ~/.ferry/config.toml, ferry watch runs this
update once each day for the tools with the "latest" policy. The gh update
runs sudo apt on the box, and the watch has no terminal for a password. Add
this rule on the box with sudo visudo -f /etc/sudoers.d/ferry:
<ssh-user> ALL=(root) NOPASSWD: /usr/bin/true, \
/usr/bin/apt update, /usr/bin/apt install gh -y
ferry status shows "Box sudo: PASSWORDLESS" when the rule works.
Options:
--yes run without a confirmation prompt
--dry-run print the update plan without running it
-h, --help display help for command
With --json: { dryRun, boxes: [{ name, ok, error, offline, skipped, plan, integrations }], operator, updated, failed }, also on failure. skipped is the reason that Ferry did not change the box.
ferry uninstall
Usage: ferry uninstall [options]
Remove Ferry's local state and restore paths changed by init
Options:
--yes run without a confirmation prompt
-h, --help display help for command
With --json: { removed, restored }.
ferry auth
Usage: ferry auth [options] [provider]
Start a login on the configured box without copying credentials.
Tools: gh, claude, codex, cursor, and each [tools.<id>] table with login keys
(see ferry tools --help). Ferry starts the vendor login on the box and prints
a URL, and a code if the tool has one. Finish the login in a browser
on this machine. When codex gives no device code, Ferry forwards local port
1455 to the box for up to 120 seconds. Pi has no remote login. Run pi on the
box and use /login.
ferry auth gh also creates ~/.ssh/id_ed25519 on the box if it is missing, and
adds it to your GitHub account with the title "<box host> (ferry)", so agents
on the box can push. Delete that key in GitHub to revoke it.
--mcp <server> logs in to a remote MCP server on the box. Give the provider,
as in ferry auth codex --mcp linear, or the name that ferry status shows, as
in ferry auth --mcp codex/linear. Ferry forwards the localhost callback port,
such as 3118 for Claude, for up to 300 seconds. The port must be free on
this machine.
On a box with mcp_gateway = true, ferry auth --mcp <server> with no provider
logs in the MCP gateway of the box, as does --mcp gateway/<server>. The
gateway keeps the token on the box.
Without a provider, Ferry lists the tools and their login: startable,
manual SSH flow, or off.
Options:
--mcp <server> start the MCP server login of the provider CLI on the box,
such as linear or codex/linear
-h, --help display help for command
With --json: { providers: [{ id, login }] } without a provider, where login is "startable", "manual", or "off", else the login result { kind, provider, ... }. A "login" event line with the URL comes before the envelope. A login that needs the code from the browser reads it as one line on stdin.
ferry sync
Usage: ferry sync [options]
Publish the snapshot and apply it to the selected boxes, or to all boxes.
A file that looks like a secret stops the sync before the publish. The error
names the file, never the value. Ferry skips a hook that refers to a home path
that the box does not have, and an MCP server that is neither a remote HTTPS
server nor a stdio command. Ferry also skips a stdio MCP server that refers to
a home path, runs an inline shell or interpreter script, runs a shell or an
interpreter with options that Ferry cannot classify, or runs from a macOS app
bundle. Sync prints a line for each skipped hook and server. A stdio MCP server
carries its command, its arguments, and the names of its env keys, never their
values.
Ferry syncs up to 4 boxes at the same time. A failed box does not stop the
other boxes. Sync also writes the ferry PATH block in ~/.profile on the box.
Sync writes ~/.ferry/box/AGENTS.md on each box from three parts: the Ferry
header, then ~/.ferry/boxes/<name>/AGENTS.md of this machine for that box
only, then your ~/AGENTS.md. One blank line separates the parts. A per-box
file that looks like a secret stops the sync of that box only.
If a plugin in enabledPlugins comes from a marketplace that
extraKnownMarketplaces does not list, run claude plugin marketplace add for it
once on this machine.
Options:
--dry-run print the plan without writing
--force back up live managed paths before Apply links them
-m, --message <message> snapshot commit message
-h, --help display help for command
With --json: { dryRun, published, boxes: [{ name, ok, step, error, skipped, plan, applyPlan, discarded }] }, also on failure of more than one box. skipped is the reason that Ferry did not connect to the box.
ferry history
Usage: ferry history [options]
List the recent snapshot commits and the paths each one changed.
Ferry reads the local snapshot checkout in ~/.ferry/store. Give a commit id to
ferry revert to undo that commit.
Options:
-n, --limit <count> the number of commits (default: 20)
-h, --help display help for command
With --json: { commits: [{ commit, date, subject, paths }] }, newest first.
ferry revert
Usage: ferry revert [options] <commit>
Undo one snapshot commit on this machine and on all boxes.
Ferry undoes the commit as git revert does, and later commits stay. The
skills, AGENTS.md, and extra roots on this machine link into the snapshot, so
they change with it. Ferry writes the reverted settings keys back into the
local settings files and keeps all other keys. Then Ferry syncs all boxes.
Ferry stops and changes nothing when a later commit changes the same lines,
or when this machine has changes that are not in the snapshot. Run ferry sync
first. Run ferry history for the commit ids.
Arguments:
commit the snapshot commit to undo
Options:
--dry-run print what the revert changes without writing
--no-sync do not sync the boxes after the revert
-h, --help display help for command
With --json: { dryRun, commit, subject, tip, paths, settings: [{ file, keys }], sync }. sync is the sync result, or null with --dry-run or --no-sync.
ferry move
Usage: ferry move [options] <path>
Continue a project on a box, on this machine with --from-box, or on another box
with both.
The path must be a directory inside the home. For one file, use ferry cp.
The destination uses the same path
relative to its home. Ferry refuses unpushed commits, uncommitted changes to
tracked files, and a destination path that exists. The destination clones from
origin with its own SSH key, so run ferry auth gh for a box first. Ferry
carries the untracked and ignored files that pass the deny rules, skips build
output such as node_modules and dist, and checks each file with SHA-256.
Between two boxes, the files go through a temporary directory on this machine,
and nothing stays here. With --remove, the source copy goes to ~/.Trash on
macOS, else to ~/.ferry/trash. Run --dry-run first.
Ferry also carries the Claude and Codex sessions of the project and the Claude
project memory, so claude --resume and codex resume find them on the
destination. A session file there stays, unless the source has the same file.
Ferry skips a session that fails the deny rules and names the file and the
rule. The source keeps its sessions.
The deny rules run on the source machine. It reads each file one time and
sends only the bytes that pass. With --from-box, the Ferry on the box does
this, so the box needs a release of Ferry from ferry install or ferry update.
--dry-run copies no file.
Arguments:
path project folder inside the home directory
Options:
--from-box <name> move the project from this box. Without --to-box, the
destination is this machine
--to-box <name> move the project to this box. Without it and --from-box,
Ferry uses default_box or the only box
--dry-run print what Ferry would carry, refuse, and skip without
changes
--remove after verification, move the source copy to a trash
directory
--include-env also carry .env files that pass the token and secret rules
--no-sessions do not carry the agent sessions and the project memory
--allow-secrets also carry sessions, and with --include-env .env files,
that hold tokens or secrets
--yes carry .env files with secrets without a confirmation prompt
-h, --help display help for command
With --json: { path, source, destination, dryRun, git, carry, refused, skipped, notes, trash, sessions }.
ferry cp
Usage: ferry cp [options] <source> <destination>
Copy one checked file between this machine and a box.
Use ferry cp <box>:<path> <local-path> to copy from a box, or
ferry cp <local-path> <box>:<path> to copy to a box. The prefix is a configured
box name. A conflicting --box is an error. With :<path>, the box is --box,
then default_box, then the only box. Exactly one endpoint must be a box.
Use ./ before a local file name that contains a colon.
A relative box path starts at the box home. Local paths start at the current
folder. Both accept ~/ and absolute paths. Give an exact destination file
path with an existing parent directory. Ferry refuses directories and
symbolic links, including symbolic links in the source path.
The source checks the file with the move deny rules before its bytes leave.
A source box needs Ferry from ferry install or ferry update. Ferry refuses
files larger than 128 MiB. It checks SHA-256 before it installs the file at
the destination. An existing destination stays unless --force is given.
Git state, agent sessions, and project memory do not take part in this copy.
Arguments:
source source file, local or <box>:<path>
destination destination file, local or <box>:<path>
Options:
--force replace an existing destination file
-h, --help display help for command
With --json: { box, source, destination, sha256 }.
ferry secrets
Usage: ferry secrets [options] [command]
Provision selected environment variables on one box outside the snapshot.
Every process started from a shell or service that loads these variables
can access them. Values are plaintext for the box user in ~/.ferry/secrets,
with directory mode 700 and file mode 600. Transfer uses SSH stdin.
Normal sync never transfers these values. Paseo is optional.
Provisioning writes ~/.ferry/secrets/load.sh and does not edit startup files.
To opt in, run ferry secrets shell install --file <name> for one selected
startup file, or add this exact line yourself on the box:
[ -r "$HOME/.ferry/secrets/load.sh" ] && . "$HOME/.ferry/secrets/load.sh"
Use ~/.profile for sh/dash login. Interactive non-login sh/dash use the
file selected by ENV, if set. For bash login use the first existing
~/.bash_profile, ~/.bash_login, or ~/.profile; use ~/.bashrc for interactive
non-login shells. Use ~/.zprofile for zsh login and ~/.zshrc for interactive
shells, under ZDOTDIR if set. Put the line before an early return.
Non-interactive paths that bypass startup files need explicit integration.
New shells load updates after you configure loading. Start agents there.
Paseo needs an explicit service restart, which stops active agents.
Options:
-h, --help display help for command
Commands:
set [options] <names...> Transfer explicitly selected variables from the
environment, a file, or hidden prompts
remove [options] <names...> Remove selected variables without revoking keys
or clearing running processes
status Show stored names and file presence, never values
or hashes
shell Configure explicit shell loading of box-local
secrets
help [command] display help for command
ferry secrets set
Usage: ferry secrets set [options] <names...>
Transfer selected names only. The default source is the operator environment.
--file reads literal NAME=value lines, with no shell evaluation, expansion,
or quote removal. --prompt reads each value with hidden input and requires
a terminal. --file and --prompt cannot be combined. Do not put values in argv.
Existing entries stay unless --replace authorizes replacement. Unrelated
entries stay. Names use letters, digits, and underscores, with no initial
digit. FERRY_SECRET_ is reserved. Values cannot contain line breaks, NUL,
other control characters except tab, or invalid UTF-8.
Every process started from a shell or service that loads these variables
can access them. --yes accepts this scope. Values are plaintext on the box.
Provisioning writes ~/.ferry/secrets/load.sh and does not edit startup files.
To opt in, run ferry secrets shell install --file <name> for one selected
startup file, or add this exact line yourself on the box:
[ -r "$HOME/.ferry/secrets/load.sh" ] && . "$HOME/.ferry/secrets/load.sh"
Use ~/.profile for sh/dash login; interactive non-login sh/dash use ENV.
For bash login use the first existing ~/.bash_profile, ~/.bash_login, or
~/.profile, and use ~/.bashrc for interactive non-login shells. Use
~/.zprofile for zsh login and ~/.zshrc for interactive shells, under ZDOTDIR
if set. Put the line before an early return.
After you configure loading, open a new shell and start new agents. Restart
Paseo explicitly
to load its new environment; the restart stops active agents.
Arguments:
names portable environment variable names
Options:
--yes authorize box-user environment scope without a confirmation
prompt
--file <path> read selected names from a literal NAME=value file
--prompt read selected values with hidden terminal input
--replace authorize replacing existing selected values
-h, --help display help for command
With --json: { box, secrets: { present, names }, steps }, or null when cancelled. Never values or hashes.
ferry secrets remove
Usage: ferry secrets remove [options] <names...>
Arguments:
names portable environment variable names
Options:
--yes authorize box-user environment scope without a confirmation prompt
-h, --help display help for command
With --json: { box, secrets: { present, names }, steps }, or null when cancelled.
ferry secrets status
Usage: ferry secrets status [options]
Options:
-h, --help display help for command
With --json: { box, secrets: { present, names }, steps }.
ferry secrets shell
Usage: ferry secrets shell [options] [command]
Options:
-h, --help display help for command
Commands:
install [options] Add the loader line to one selected startup file on one box
help [command] display help for command
ferry secrets shell install
Usage: ferry secrets shell install [options]
Add the guarded loader line once, before the existing content of one
selected startup file on the box. Other content and file permissions stay.
An absent selected file is created with mode 600. Symbolic links and other
non-regular files are refused; use your dotfile manager for a symlink.
Select one filename relative to the box home: .profile, .bashrc,
.bash_profile, .bash_login, .zprofile, or .zshrc. There is no default.
Use .profile for sh/dash login. For bash login select the first existing
readable file of .bash_profile, .bash_login, or .profile; use .bashrc for
interactive non-login shells. Creating bash login override files can stop
bash from reading .profile. Use .zprofile for zsh login and .zshrc for
interactive shells with default ZDOTDIR. Custom ZDOTDIR and ENV files need
the loading line added by the user.
The installed line is:
[ -r "$HOME/.ferry/secrets/load.sh" ] && . "$HOME/.ferry/secrets/load.sh"
A missing loader permits shell startup. Install does not transfer values
or create the loader; ferry secrets set writes it. Every process started
from a shell that loads these variables can access them.
Only this explicit command edits startup files for secrets. Provisioning,
removal, sync, update, and uninstall leave this line alone. After install,
open a new shell session that reads the selected file and start agents there.
Existing processes keep their old environment. No service restarts occur.
Options:
--file <name> select one startup filename on the box, relative to its home
--yes authorize editing the selected file and the box-user
environment scope
-h, --help display help for command
With --json: { box, file, changed, steps }, or null when cancelled. Never startup file content or secret values.
ferry adopt
Usage: ferry adopt [options] <skill>
Copy a skill that an agent wrote on a box to this machine.
ferry status lists the box-only skills of each box: skills in a harness skill
root or in the box checkout that the snapshot does not have. The Ferry on the
box runs the deny rules on the skill. A skill that fails a deny rule does not
reach this machine: Ferry copies no file of it. Else Ferry copies the files
that pass and shows the file list of a new skill or the diff against the copy
on this machine. The box needs a release of Ferry from ferry install or ferry
update. After the confirmation, Ferry writes the skill to
the same skill root on this machine and moves the box copy to
~/.ferry/backups on the box. Then run ferry sync. It publishes the skill,
links it on this machine, and links it on all boxes.
Arguments:
skill the skill name that ferry status lists
Options:
--from-box <name> copy the skill from this box
--yes adopt the skill without a confirmation prompt
-h, --help display help for command
With --json: { box, name, source, destination, replaces, files: [{ path, executable }], skipped, diff, adopted, boxBackup }, or null when cancelled.
ferry tunnel
Usage: ferry tunnel [options] [command] [ports...]
Open box ports on this machine until Ctrl-C, list the ports that listen on the
box, or follow the ports of ferry expose.
Local ports bind to 127.0.0.1 only. The box end is 127.0.0.1 on the box, so a
dev server that listens only on ::1 does not answer. A plain tunnel does not
reconnect. With --follow, the local port is the box port when it is free, else
the next free port, and Ferry connects again 5 seconds after a drop. Run
ferry tunnel install to run --follow as a user service.
Put a host before the box port to forward to a host that the box can reach,
such as a database that accepts connections only from the box network. A
numeric first part is a box port. The box resolves the host name. Put an IPv6
address in brackets. Ferry first checks that the box can connect to the host,
and stops with an error when it cannot. On a box without bash, timeout, or
/dev/tcp, Ferry cannot always make this check. Then it prints a warning and
opens the tunnel.
5432 127.0.0.1:5432 on the box, local port 5432
5432:15432 127.0.0.1:5432 on the box, local port 15432
db.example:5432 db.example:5432 from the box, local port 5432
db.example:5432:15432 db.example:5432 from the box, local port 15432
[fd00::1]:5432 [fd00::1]:5432 from the box, local port 5432
A plain tunnel works as the child process of another program. It never
prompts: OpenSSH runs in batch mode. The local port accepts connections after
the SSH connection is ready. SIGTERM closes the tunnel with exit code 0.
--follow writes its forwards to ~/.ferry/tunnels/<box>.json when it connects,
after each change, and when the connection drops. The menu bar app reads the
file. Fields: schemaVersion (1), box, pid, connected (false after a drop, with
no forwards), updatedAt, and forwards: [{ name, cwd, boxPort, localPort }].
name and cwd are missing when the entry of ferry expose has none. Ferry
removes the file when --follow stops on Ctrl-C or SIGTERM.
--follow also copies the new events of ferry notify on the box to
~/.ferry/tunnels/<box>.events.json, and keeps the newest 20. The file stays
when --follow stops. Fields: schemaVersion (1), box, updatedAt, and events:
[{ id, harness, kind, project, at, receivedAt }].
Arguments:
ports box port, box:local to pick another local port, or
host:port[:local] for a host that the box can reach, such as 3000,
3000:4000, or db.example:5432
Options:
--list list the TCP ports that listen on the box, with process names
--follow open a forward for each port that ferry expose announces on the
box, and close it when the port goes away
-h, --help display help for command
Commands:
install Install and start a user service that runs ferry tunnel --follow
for one box
uninstall Stop and remove the tunnel user service of one box
With --json: events forward-opened, forward-closed, forward-failed, following, connection-lost, tunnel-closed. With --list, one envelope: { box, listeners: [{ port, address, process }] }.
ferry tunnel install
Usage: ferry tunnel install [options]
Install and start a user service that runs ferry tunnel --follow for one box.
The box is --box, then default_box, then the only box. The service always
runs with --box <box>, so a later default_box does not change it. Each box has
its own service:
macOS ~/Library/LaunchAgents/dev.ferry.tunnel.<box>.plist
log: ~/Library/Logs/ferry-tunnel-<box>.log
Linux ~/.config/systemd/user/ferry-tunnel-<box>.service
log: journalctl --user -u ferry-tunnel-<box>.service -f
The service writes ~/.ferry/tunnels/<box>.json, as ferry tunnel --follow does.
The menu bar app shows its ports.
The service starts again each time it exits. The service records the path of
this Ferry, the current PATH, and SSH_AUTH_SOCK. PATH must find ssh, and
tailscale for a Tailscale box. Run the command again after you move Ferry or
change these values. A successful ferry self-update restarts the service when
it points at the updated Ferry.
Options:
-h, --help display help for command
With --json: { manager, path }.
ferry tunnel uninstall
Usage: ferry tunnel uninstall [options]
Stop and remove the tunnel user service of one box.
The box is --box, then default_box, then the only box. Ferry removes the file
that ferry tunnel install wrote. The macOS log stays.
Options:
-h, --help display help for command
With --json: { manager, path, removed }.
ferry expose
Usage: ferry expose [options] <command...>
Run a command on the box and announce its port to ferry tunnel --follow.
Ferry writes ~/.ferry/exposed/<pid>.json before the command starts and
removes it when the command exits. At the start, Ferry removes the entries
whose pid does not run. Ferry forwards SIGINT, SIGTERM, and SIGHUP to the
command and exits with its exit code. Put the command after --.
For example, a service script in paseo.json on the box:
"web": {
"type": "service",
"command": "ferry expose -- bun run dev --port $PASEO_PORT"
}
Arguments:
command the command to run, after --, such as -- bun run dev
Options:
--port <n> the port of the command. The default is $PASEO_PORT
-h, --help display help for command
With --json: events exposed and exited. The output of the command goes to stderr.
ferry notify
Usage: ferry notify [options] <harness> <kind>
Record an agent event on the box for the menu bar app of the operator machine.
A harness hook runs this command on the box. Ferry writes one event to
~/.ferry/events/<id>.json with the harness, the kind, the project, and the
time. The project is the cwd field of the JSON on stdin, else the current
directory. Ferry reads no other field, and writes no prompt text and no
agent output. Ferry keeps the newest 20 events of the last hour.
ferry tunnel --follow on the operator machine copies the new events to
~/.ferry/tunnels/<box>.events.json, and the menu bar app posts one
notification for each new event.
With [notifications] agents = true in the config of the operator machine,
ferry sync adds the Claude Stop and Notification hooks that run this command
to ~/.claude/settings.json on each box. The kinds are turn-ended and
waiting-for-input.
Arguments:
harness the harness id, such as claude
kind turn-ended or waiting-for-input
Options:
-h, --help display help for command
With --json: { id, harness, kind, project, at }.
ferry status
Usage: ferry status [options]
Inspect link, snapshot, managed paths, and box logins without writing.
The Tools part of each box shows one state for each tool: ok; drift, run
ferry update; missing, run ferry install; hidden, a login shell on the box
does not find the tool, run ferry sync; skipped, the tool has no target;
unknown, Ferry cannot read the box version. Box-only skills lists the skills
on each box that the snapshot does not have. ferry adopt --from-box copies one
to this machine. Skipped MCP servers lists each stdio MCP server of this
machine that Ferry does not carry, with its harness, its name, the reason, and
what to change. It never prints a command or an argument of a server.
Unsaved work lists each git project on the box with changes that are not
committed, or with a local branch or a detached HEAD that has commits that no
remote has. Ferry checks the projects of [box.<name>], the destinations of
earlier ferry move commands, and the linked worktrees of both. It shows only
the path, the branch, and the counts. A project where git fails shows
could not check. With
--json, result is the status report, schema version 2, and its skippedMcp has
that list. The ferry agent skill describes its fields.
Install the skill with ferry skills add dlhck/ferry --skill ferry.
--brief checks only the link, the free disk, memory, and load, the logins, the
MCP logins, the carried stdio MCP servers, and the tools of each box, and the
hooks of this machine that run a home file Ferry does not carry. It prints one
line for each item that needs action, with the Ferry command that fixes it.
ferry watch writes the same report to ~/.ferry/status.json.
The probe reads the free disk of the box home file system, the available
memory, and the load average in its SSH command. --brief shows an item when
the free disk is below both 10% and 5 GiB, or the available memory is below
10%. Set other limits in [status] of ~/.ferry/config.toml with
disk_free_percent, disk_free_gib, and memory_available_percent. A limit of 0
turns its part of the check off. When one disk limit is 0, the other decides.
The load is only in the JSON report.
Options:
--brief check only the link, the disk and memory, the logins, the MCP
logins, and the tools, and print what needs action
-h, --help display help for command
With --json: the status report, schema version 2. With --brief, { schemaVersion: 1, checkedAt, boxes: [{ name, host, online, error, summary, issues: [{ kind, name, state, summary, message, command }], resources: { disk, memory, load }, mcpGateway: { state, reason, servers: [{ name, state }] } }] }. mcpGateway.state is off for a box without mcp_gateway = true. mcpGateway is null when the box is offline or the gateway check failed.
ferry doctor
Usage: ferry doctor [options]
Check SSH, Tailscale, snapshot access, linger, and services, and print a fix for
each failure.
Ferry runs each check, also after a check fails, and changes nothing. It
checks that the SSH agent has a key, that this machine can read the snapshot
and push to it (git push --dry-run), and that the installed watch and tunnel
services run this Ferry. For each box, it checks that the box responds over
SSH with host key checks on, that Tailscale reaches a Tailscale box, that the
box can read the snapshot with the forwarded agent or the deploy key of
git_auth = "box", and that linger is on when a Ferry service runs on the box.
For each box, it also shows the lock of the box on this machine. A held lock
names the command that holds it and its pid, and is not a failure. The check
fails only for the lock of a Ferry version before 0.10.0 whose pid is alive.
When a Ferry process has the pid, the fix is ferry watch install, or to stop
that process. When a different program has the pid now, the fix removes the
lock file.
The exit code is 1 when a check fails. With --json, result has one entry for
each check, also on failure.
Options:
-h, --help display help for command
With --json: { schemaVersion: 1, ok, checks: [{ id, box, status, message, fix }] }, also on failure. status is ok, failed, or skipped.
ferry integrations
Usage: ferry integrations [options] [command]
List the integrations of each box, whether each one is enabled, its parts, and
the local app versions
Options:
-h, --help display help for command
Commands:
enable [options] <name> Install and start an integration on the box, then
turn it on in the config
disable [options] <name> Stop and remove an integration on the box, then turn
it off in the config
With --json: { boxes: [{ name, destination, integrations: [{ id, description, enabled, parts, available, localVersion, localSource, connectSteps }] }] }.
ferry integrations enable
Usage: ferry integrations enable [options] <name>
Install and start an integration on the box, then turn it on in the config.
paseo: Ferry installs Node 22 or later and the Paseo CLI at the version of the
local Paseo app, then starts the user service ferry-paseo.service. The daemon
listens on 127.0.0.1:6767 with the relay off by default. It has no password, so
use it
only on a box with one user. To connect Paseo Desktop, add the Remote SSH host
ssh://<box destination>. With Paseo on, sync carries the Paseo agent profiles,
managed Git and npm plugins, the portable fields of agents.providers,
agents.metadataGeneration.providers, daemon.appendSystemPrompt, and the
portable daemon.terminalProfiles. move registers the project in Paseo on the
box and imports each carried session as a Paseo agent. move --from-box does
the same in the Paseo of this machine.
For relay pairing, set paseo_relay = true in [integrations] of
~/.ferry/config.toml. A [box.<name>.integrations] table can override it.
Run ferry integrations enable paseo --box <name> again to apply a change.
A changed service config restarts the daemon and stops its agents.
Enable writes the whole ferry-paseo.service again, so a line that you added
to it by hand is gone. Put such a line in a drop-in file on the box, for
example ~/.config/systemd/user/ferry-paseo.service.d/local.conf.
The service has OOMPolicy=continue. When the kernel kills an agent process
that ran out of memory, the daemon and the other agents continue. Enable and
sync add the line to an older service without a restart of the daemon.
To carry daemon.autoArchiveAfterMerge, set paseo_auto_archive = true in
[integrations] of ~/.ferry/config.toml. A [box.<name>.integrations] table can
override it. Sync applies it with paseo daemon reload, without a restart.
An integration without a box part runs only on this machine. For it, Ferry
changes only the config and adds its commands when it can run here.
sherlock: needs the sherlock executable on this machine. Ferry adds ferry
sherlock add, and ferry status checks each connection that it added.
Arguments:
name integration name, such as paseo
Options:
--dry-run print the box commands without connecting or writing
--yes run without a confirmation prompt
-h, --help display help for command
With --json: { integration, action, dryRun, plan, output, enabled, connectSteps }.
ferry integrations disable
Usage: ferry integrations disable [options] <name>
Stop and remove an integration on the box, then turn it off in the config.
Ferry never removes ~/.paseo on the box. An integration without a box part
changes only the config.
Arguments:
name integration name, such as paseo
Options:
--purge also uninstall the integration package on the box
--yes run without a confirmation prompt
-h, --help display help for command
With --json: { integration, action, dryRun, plan, output, enabled, connectSteps }.
ferry sherlock
Usage: ferry sherlock [options] [command]
Add Sherlock database connections that tunnel through a box
Options:
-h, --help display help for command
Commands:
add [options] <name> Add a Sherlock connection whose tunnel is ferry tunnel
help [command] display help for command
ferry sherlock add
Usage: ferry sherlock add [options] <name>
Add a Sherlock connection whose tunnel is ferry tunnel.
Ferry runs sherlock connection add with
--tunnel-command "ferry tunnel --box <box> <target>:{{port}}". Sherlock opens
the tunnel on the first query and closes it when it is idle. The box is --box,
then default_box, then the only box.
The target is a box port, such as 5432, or a host and port that the box can
reach, such as db.example:5432.
On a terminal, Ferry asks for the password and gives it to Sherlock on stdin.
Sherlock stores it in the keychain of this machine. With --password-stdin,
Sherlock reads the password from the stdin of Ferry. Ferry never stores the
password and never changes the Sherlock config file. Ferry records the name,
box, and target in ~/.ferry/sherlock.json for ferry status.
With --json, Ferry asks nothing, so give --password-stdin or --password-env.
With --json: { name, box, target, tunnelCommand }.
Arguments:
name connection name in Sherlock
Options:
--target <target> box port or host:port that the box can reach, such as
5432 or db.example:5432
--type <type> postgres, mysql, mssql, or redis
--database <name> database name
--username <user> database user
--ssl <mode> off, require, or verify
--password-stdin Sherlock reads the password from stdin
--password-env <var> Sherlock reads the password from this environment
variable at query time
--force replace a Sherlock connection with the same name
-h, --help display help for command
ferry tools
Usage: ferry tools [options]
List the tools, the version policy of each one and of each box, and the versions
on this machine.
Ferry has recipes for gh and the agent CLIs claude, codex, pi, and cursor.
Define each other tool in ~/.ferry/config.toml. Ferry does not scan projects.
A policy is "operator" (the version on this machine), "latest", or an exact
version. The default is "latest" for an agent CLI and "operator" for a tool.
With "operator", Ferry skips a tool that this machine does not have.
[box.<name>.tools] sets the policy for one box.
"off" turns off gh or an agent CLI (claude, codex, pi, cursor). install,
update, and the daily watch update skip it, ferry auth refuses it, and
ferry status shows it as off. Ferry does not uninstall it from the box. An
off agent also turns off its harness: sync does not read it on this machine
and does not write it on the box, and removes the links that Ferry made
there before. Ferry never removes other files there. A box policy can turn
the tool on again. "off" is not valid in a [tools.<id>] table. To remove
such a tool, delete its table.
[tools]
gh = "latest"
codex = "0.156.1"
pi = "off"
[box.b.tools]
pi = "latest"
[tools.pnpm]
version = "operator"
local = "pnpm --version"
box = "pnpm --version"
latest = "npm view pnpm version"
install = 'npm install -g --prefix "$HOME/.local" pnpm@{version}'
path = [".local/bin"]
depends = ["node"]
[tools.northflank]
local = "northflank --version"
install = "npm install -g @northflank/cli@{version}"
auth_status = "northflank list projects"
auth_login = "northflank login --do-not-open-browser"
auth_hosts = ["northflank.com"]
local and install are required. local prints the version on this machine, box
prints the version on the box, and latest prints the newest version, which the
"latest" policy needs. update is the update command, and the default is
install. {version} is the only placeholder. path adds home directories to the
box PATH, and depends names the tools to install first. A comment must be on
its own line. Run ferry sync after a path change.
The auth keys let ferry auth <id> log the tool in on the box. auth_status
passes when the tool is logged in. auth_login starts a login that prints a URL
and finishes after the browser step, with no input on the box. auth_hosts names
the hosts that URL may have. Ferry passes the URL on with its fragment and
query, which can hold the login session. Give all three keys or none.
Options:
-h, --help display help for command
With --json: { tools: [{ id, name, kind, install, policy: { policy, default }, boxes, operatorVersion }] }.
ferry ps
Usage: ferry ps [options]
List the agent processes on each box, with their memory and CPU.
Ferry reads the processes of the box user in one SSH command and compares
their program names with the harnesses of the registry. An agent is a matched
process whose parent processes do not match. Its memory is the resident
memory of the process and all its child processes. Its CPU is the sum of the
CPU percent that ps gives for each of these processes, which is the average
since the start of the process. 100% is one CPU. The project is the working
directory of the agent process. The start time is in UTC.
The command line of a process does not leave the box. Ferry replaces a token
or a URL credential in a project path. An offline box gets one line with the
reason, and Ferry continues with the other boxes. Ferry changes nothing on
the box.
Options:
-h, --help display help for command
With --json: { boxes: [{ name, online, error, agents: [{ harness, pid, project, startedAt, memoryKiB, cpuPercent, children }] }] }.
ferry usage
Usage: ferry usage [options]
Show the tokens of the agents on each box, for each harness and project.
The Ferry on each box reads the session files of the harnesses and adds the
token counts for each harness, project, and day. Input is the input tokens
that are not a cache read. The days are UTC days. --since <date> counts from
that day on, in the form YYYY-MM-DD. Without it, Ferry counts all days. The
JSON result has the count of each day.
Ferry counts what the session files hold now. A session that a harness or
you deleted is not counted. A harness that records no token counts, such as
Cursor Agent, shows as not available. Ferry shows tokens, not money.
Only the harness ids, the project paths, the days, and the numbers leave the
box. Ferry replaces a token or a URL credential in a project path. An offline
box, or a box without the Ferry of a release, gets one line with the reason,
and Ferry continues with the other boxes. Ferry changes nothing on the box.
This machine is not in the report.
Options:
--since <date> count from this UTC day on, in the form YYYY-MM-DD
-h, --help display help for command
With --json: { since, boxes: [{ name, online, error, harnesses: [{ id, available, total, projects: [{ path, total, days: [{ day, input, output, cacheRead, cacheWrite }] }] }] }] }. total is { input, output, cacheRead, cacheWrite }, or null when available is false.
ferry watch
Usage: ferry watch [options] [command]
Watch the portable set and sync accepted changes.
The watch syncs all boxes one second after a change stays stable. A box that
fails retries with its own backoff, up to 60 seconds. The watch reads the
config in each cycle. With [update] watch = true, it also runs ferry update
once each day. Run ferry update --help for the sudo rule on the box.
At the start, every 5 minutes, and after each sync, the watch runs
ferry status --brief for all boxes and writes the report to
~/.ferry/status.json.
Options:
-h, --help display help for command
Commands:
install Install and start the watch user service
With --json: events watch-started, synced, sync-failed, sync-refused, content-refused, config-error, update-started, update-failed, status-failed, watch-stopped.
ferry watch install
Usage: ferry watch install [options]
Install and start the watch user service.
The macOS service is ~/Library/LaunchAgents/dev.ferry.watch.plist. Its log
is ~/Library/Logs/ferry-watch.log. The Linux service is
~/.config/systemd/user/ferry-watch.service. Read its log with
journalctl --user -u ferry-watch.service -f.
The service records the path of this Ferry, the current PATH, and
SSH_AUTH_SOCK. PATH must find git, ssh, and tailscale for a Tailscale box.
Run the command again after you move Ferry or change these values. A
successful ferry self-update restarts the service when it points at the
updated Ferry.
Options:
-h, --help display help for command
With --json: { manager, path }.
ferry menubar
Usage: ferry menubar [options] [command]
Install or remove the macOS menu bar app that shows what needs action on the
boxes
Options:
-h, --help display help for command
Commands:
install [options] Install and start the macOS menu bar app
uninstall Stop and remove the macOS menu bar app
help [command] display help for command
ferry menubar install
Usage: ferry menubar install [options]
Install and start the macOS menu bar app.
The app shows the report of ~/.ferry/status.json: offline boxes, logins, MCP
logins, and tool drift. ferry watch writes the file, so run ferry watch
install too. Click an item with a Ferry command to run it in Terminal.
The app also shows the ports of each running ferry tunnel --follow, from
~/.ferry/tunnels/<box>.json. Click a port to open it in the browser.
Ferry downloads ferry-menubar-macos.zip of the release of this Ferry,
verifies it against SHA256SUMS of the release, and unpacks it to
~/Applications/Ferry Menu Bar.app. When the release does not have these
files yet, Ferry stops and the installed app stays. --app installs a local build
of
macos/build.sh, a .app directory or its zip, without a checksum. A
development build of Ferry needs --app.
The app starts at login with ~/Library/LaunchAgents/dev.ferry.menubar.plist.
It records the path of this Ferry as FERRY_PATH, the current PATH, and
SSH_AUTH_SOCK. Run the command again after you move Ferry or update it.
Options:
--app <path> install a local build of macos/build.sh: a .app directory or its
zip
-h, --help display help for command
With --json: { app, path, version, ferryPath }. version is null with --app.
ferry menubar uninstall
Usage: ferry menubar uninstall [options]
Stop and remove the macOS menu bar app.
Ferry stops the app, and removes ~/Library/LaunchAgents/dev.ferry.menubar.plist
and ~/Applications/Ferry Menu Bar.app. The log stays.
Options:
-h, --help display help for command
With --json: { app, path, removed }.
ferry self-update
Usage: ferry self-update [options]
Update Ferry on this machine to the latest release.
Ferry updates in the same way as it was installed: with npm, or with the
release installer in the directory of this binary. It restarts installed
watch and tunnel services that point at this Ferry. On macOS, it also updates
an installed release menu bar app. It writes the Ferry agent skill of the new
version to ~/.agents/skills/ferry, unless ferry init --no-skill turned it off
or the skill folder has local changes. Then run ferry update to put the new
version on the boxes.
A release is visible before its build attaches the files. When the latest
release does not have its files yet, Ferry says that the release is not ready
and does not start the update. This is not an error. Run the command again
some minutes later.
On a terminal, each command also asks to update when a newer release is
there. Ferry reads the latest release at most once a day. It does not ask
with --json, with CI set, or with FERRY_NO_UPDATE_CHECK=1, and it does not
ask for a release that does not have its files yet.
Options:
-h, --help display help for command
With --json: { current, latest, updated, state, services: [{ service, action, message }], skill }. state is updated, up-to-date, or not-ready. not-ready: the release latest does not have its files yet, and Ferry did not start the update. skill is the message of the skill update, or null. The output of the installer goes to stderr.
ferry whoami
Usage: ferry whoami [options]
Print the role of this machine: the operator machine or a Ferry box.
On a box, Ferry also prints the box name from the last ferry sync, and the
parts of the generated instruction file ~/.ferry/box/AGENTS.md in their
order: the Ferry header, the per-box instructions from
~/.ferry/boxes/<name>/AGENTS.md on the operator machine when the box has
them, and the shared ~/AGENTS.md. The operator machine is the source of
truth. On a box, change a Ferry-managed file on the operator machine, not
on the box. This command runs on the operator machine and on a box install.
The managed paths of a box are the paths that the last ferry sync linked
there: the instruction files, the skill roots, and the other roots of the
harnesses that are on for the box, with the custom harnesses of the config.
A box that an earlier Ferry synced has no such record until the next sync.
Until then, Ferry lists the paths of the built-in harnesses that are links
of Ferry on the box.
Options:
-h, --help display help for command
With --json: { role: "operator" or "box", box, instructions: { file, sources: [{ part: "header", "box", or "shared", path }] }, managedPaths: { instructionFiles, skillRoots, roots } }. box is null on the operator machine and before the first sync of a box. instructions is null on the operator machine and on a box without the generated file. sources has the merged parts in order, and path is the file on the operator machine. On a box, managedPaths has the paths that the last sync linked there.
ferry relay
Usage: ferry relay [options] [command]
Run the team relay of agent messaging on this machine.
The relay stores the conversations of a team. It runs on one host of the
team, as the service ferry-relay.service or dev.ferry.relay, and keeps its
data in ~/.ferry/relay. Agents reach it over HTTPS, for example through
Tailscale Serve. With --box, relay install and relay uninstall change the
box key relay of [box.<name>], and the next ferry sync starts or removes the
relay on that box.
Options:
-h, --help display help for command
Commands:
setup Create the GitHub App of the relay
import-github-app [options] Store an existing GitHub App for the relay, when
the manifest flow is not possible. With --box,
store it on the box
install Install and start the relay service on this
machine. With --box, set relay = true for the box
uninstall [options] Stop and remove the relay service. Without
--keep-data, also remove ~/.ferry/relay, with the
data of the team. With --box, remove relay = true
of the box
owners [action] [owner] List the GitHub owners that the relay serves, or
add or remove one
status Print the version, database size, last backup,
GitHub App state, owners, and counts of the relay
on this machine
backup [options] Write a consistent copy of the relay database.
With --to -, write it to stdout
restore <file> Replace the relay database with a backup. Stop
the relay service first
help [command] display help for command
ferry relay setup
Usage: ferry relay setup [options] [command]
Create the GitHub App of the relay
Options:
-h, --help display help for command
Commands:
github-app [options] Create the GitHub App of the relay with the manifest
flow of GitHub, and store its key in ~/.ferry/relay.
With --box, store it on the box
help [command] display help for command
ferry relay setup github-app
Usage: ferry relay setup github-app [options]
Create the GitHub App of the relay with the manifest flow of GitHub, and store
its key in ~/.ferry/relay. With --box, store it on the box
Options:
--org <org> create the App for this organization, else for your user
--public let other owners install the App
--name <name> the App name
-h, --help display help for command
ferry relay import-github-app
Usage: ferry relay import-github-app [options]
Store an existing GitHub App for the relay, when the manifest flow is not
possible. With --box, store it on the box
Options:
--app-id <id> the numeric App id
--client-id <id> the client id of the App
--slug <slug> the App slug
--key-file <path> the private key file of the App. Ferry copies it into
~/.ferry/relay
-h, --help display help for command
ferry relay install
Usage: ferry relay install [options]
Install and start the relay service on this machine. With --box, set relay =
true for the box
Options:
-h, --help display help for command
ferry relay uninstall
Usage: ferry relay uninstall [options]
Stop and remove the relay service. Without --keep-data, also remove
~/.ferry/relay, with the data of the team. With --box, remove relay = true of
the box
Options:
--keep-data keep ~/.ferry/relay
--yes remove the data of the team without a question
-h, --help display help for command
ferry relay owners
Usage: ferry relay owners [options] [action] [owner]
List the GitHub owners that the relay serves, or add or remove one
Options:
-h, --help display help for command
ferry relay status
Usage: ferry relay status [options]
Print the version, database size, last backup, GitHub App state, owners, and
counts of the relay on this machine
Options:
-h, --help display help for command
ferry relay backup
Usage: ferry relay backup [options]
Write a consistent copy of the relay database. With --to -, write it to stdout
Options:
--to <path> the backup file, or - for stdout
-h, --help display help for command
ferry relay restore
Usage: ferry relay restore [options] <file>
Replace the relay database with a backup. Stop the relay service first
Options:
-h, --help display help for command
ferry messaging
Usage: ferry messaging [options] [command]
Let Claude Code and Codex sessions of a team send messages to each other.
Agents use the ferry_* MCP tools. These commands enroll a machine or a box,
set up the hooks, the MCP entry, the skill, and the worker service, and show
the state for people. Humans do not post through the CLI: tell your agent
what to send.
To start on this machine:
ferry messaging enroll --relay https://<relay host>
ferry messaging setup
For a box, run ferry messaging enroll --box <name>. It sets messaging = true
for the box, and the next ferry sync installs the hooks, the MCP entry, and
the worker on the box.
Options:
-h, --help display help for command
Commands:
enroll [options] Enroll this machine with the device flow of
GitHub, or with --box, give a box its own
device credential
setup Add the hooks, the MCP entry ferry-messaging,
the messaging skill, and the worker service on
this machine
teardown Remove what ferry messaging setup added. The
credential and the skill stay
status Print the worker state, the relay state, the
sessions, the held and failed deliveries, and
the outbox
conversations [options] List the conversations of the project of the
current directory
show [options] <conversation> Show the recent messages of a conversation (id
or slug)
requests [options] List the open requests to your sessions in the
project of the current directory. With --sent,
the requests that they sent
peers List the live sessions in the project of the
current directory
devices List the devices of your owner
revoke <device> Revoke a device credential of your owner, and
end its sessions
leave [options] Retire a session of your owner. Its memberships
end
remote Choose the Git remote of the project for the
checkout of the current directory
relay-url <url> Use a new relay URL, after a move of the relay.
ferry sync writes it to the boxes
help [command] display help for command
ferry messaging enroll
Usage: ferry messaging enroll [options]
Enroll this machine with the device flow of GitHub, or with --box, give a box
its own device credential
Options:
--relay <url> the HTTPS URL of the relay
-h, --help display help for command
ferry messaging setup
Usage: ferry messaging setup [options]
Add the hooks, the MCP entry ferry-messaging, the messaging skill, and the
worker service on this machine
Options:
-h, --help display help for command
ferry messaging teardown
Usage: ferry messaging teardown [options]
Remove what ferry messaging setup added. The credential and the skill stay
Options:
-h, --help display help for command
ferry messaging status
Usage: ferry messaging status [options]
Print the worker state, the relay state, the sessions, the held and failed
deliveries, and the outbox
Options:
-h, --help display help for command
ferry messaging conversations
Usage: ferry messaging conversations [options]
List the conversations of the project of the current directory
Options:
--query <words> words to find
-h, --help display help for command
ferry messaging show
Usage: ferry messaging show [options] <conversation>
Show the recent messages of a conversation (id or slug)
Options:
--before <message> the messages before this message id
-h, --help display help for command
ferry messaging requests
Usage: ferry messaging requests [options]
List the open requests to your sessions in the project of the current directory.
With --sent, the requests that they sent
Options:
--sent the requests that your sessions sent
-h, --help display help for command
ferry messaging peers
Usage: ferry messaging peers [options]
List the live sessions in the project of the current directory
Options:
-h, --help display help for command
ferry messaging devices
Usage: ferry messaging devices [options]
List the devices of your owner
Options:
-h, --help display help for command
ferry messaging revoke
Usage: ferry messaging revoke [options] <device>
Revoke a device credential of your owner, and end its sessions
Options:
-h, --help display help for command
ferry messaging leave
Usage: ferry messaging leave [options]
Retire a session of your owner. Its memberships end
Options:
--session <id> the session id (ses_...)
-h, --help display help for command
ferry messaging remote
Usage: ferry messaging remote [options] [command]
Choose the Git remote of the project for the checkout of the current directory
Options:
-h, --help display help for command
Commands:
set <name> Use the remote <name> for the checkout of the current
directory. Ferry writes ~/.ferry/messaging/remotes.json, not
the checkout
clear Remove the remote choice of the checkout of the current
directory
help [command] display help for command
ferry messaging remote set
Usage: ferry messaging remote set [options] <name>
Use the remote <name> for the checkout of the current directory. Ferry writes
~/.ferry/messaging/remotes.json, not the checkout
Options:
-h, --help display help for command
ferry messaging remote clear
Usage: ferry messaging remote clear [options]
Remove the remote choice of the checkout of the current directory
Options:
-h, --help display help for command
ferry messaging relay-url
Usage: ferry messaging relay-url [options] <url>
Use a new relay URL, after a move of the relay. ferry sync writes it to the
boxes
Options:
-h, --help display help for command
ferry config
Usage: ferry config [options] [command]
Read and change some keys of ~/.ferry/config.toml
Options:
-h, --help display help for command
Commands:
get Print the keys of each box, and the stdio MCP servers
of this machine that each box can share
set <key> [values...] Set a key in the config
unset <key> Remove a key from the config
help [command] display help for command
The keys:
notifications.agents true or false, for all boxes. Give no --box.
mcp_gateway true or false. false removes the key.
mcp_gateway_shared zero or more stdio MCP server names.
agent_memory_max one systemd memory size, such as 6G, 512M, or 50%.
projects zero or more paths relative to the box home.
A box key changes the [box.<name>] table of --box, else of default_box, else
of the only box. An empty list and unset remove the key. A value that is not
valid changes nothing. Put -- before the values when a value starts with -,
as in ferry config set projects --box dev -- -app.
Each change goes to the box at the next ferry sync. When the value changes,
Ferry prints the sync to run, and syncNeeded is true in the JSON result.
Ferry writes the config again, so the comments in ~/.ferry/config.toml are
lost after a change.
ferry config get
Usage: ferry config get [options]
Print the keys of each box, and the stdio MCP servers of this machine that each
box can share
Options:
-h, --help display help for command
With --json: { schemaVersion: 1, notifications: { agents }, boxes: [{ name, mcpGateway, mcpGatewayShared, agentMemoryMax, projects, stdioServers }], warnings }. stdioServers is [] when Ferry cannot read the MCP servers of this machine. Then result.warnings has the reason. Without a warning, result has no warnings key.
ferry config set
Usage: ferry config set [options] <key> [values...]
Set a key in the config
Arguments:
key notifications.agents, mcp_gateway, mcp_gateway_shared,
agent_memory_max, or projects
values the value, or the list items as separate arguments
Options:
-h, --help display help for command
With --json: { changed, box, key, syncNeeded }. box is null for notifications.agents.
ferry config unset
Usage: ferry config unset [options] <key>
Remove a key from the config
Arguments:
key notifications.agents, mcp_gateway, mcp_gateway_shared,
agent_memory_max, or projects
Options:
-h, --help display help for command
With --json: { changed, box, key, syncNeeded }. box is null for notifications.agents.
ferry box
Usage: ferry box [options] [command]
List, add, and remove the boxes of the config
Options:
-h, --help display help for command
Commands:
list List the boxes, their transport and destination, and
the default box
add [options] <name> Check a new box like ferry init, then add it to the
config
remove [options] <name> Remove a box from the config. With --uninstall,
remove Ferry from the box first
create [options] <name> Create a machine at Hetzner Cloud, then add it as a
box, install the tools, and sync
destroy [options] <name> Remove the machine of a box at Hetzner Cloud, then
remove the box from the config
default <name> Set default_box, the box of install, auth, move,
tunnel, and integrations enable|disable without
--box
help [command] display help for command
ferry box list
Usage: ferry box list [options]
List the boxes, their transport and destination, and the default box
Options:
-h, --help display help for command
With --json: { boxes: [{ name, transport, destination, default }] }.
ferry box add
Usage: ferry box add [options] <name>
Check a new box like ferry init, then add it to the config.
The first box add on a [host] config moves [host] to [box.default] and sets
default_box = "default". Ferry asks before it writes.
Ferry also creates the empty file ~/.ferry/boxes/<name>/AGENTS.md on this
machine and prints its path. Write instructions for this box only there.
ferry sync puts them into the instruction file of the box, after the Ferry
header and before your ~/AGENTS.md. The file never goes into the snapshot.
With --git-auth box, Ferry never forwards your SSH agent to the box. Ferry
creates ~/.ssh/ferry_snapshot on the box and tests read access to the
snapshot with it. If the test fails, Ferry prints the public key and does not
change the config. Add the key as a read-only deploy key on the snapshot
repository, then run the command again. To change an existing box, set
git_auth = "box" in its [box.<name>] table and run ferry init --box <name>.
Arguments:
name box name: 1 to 32 characters from a-z, 0-9,
and -
Options:
--host <host> Tailscale host name or IP address
--ssh-user <user> SSH user on the host
--ssh-destination <destination> explicit OpenSSH destination
--git-auth <mode> agent forwards your SSH agent to the box git;
box uses a read-only deploy key on the box
(choices: "agent", "box")
--yes change a [host] config to box tables without
a confirmation prompt
--accept-host-keys trust the SSH host keys of the snapshot host
on the box without a confirmation prompt
-h, --help display help for command
With --json: { name, transport, destination, gitAuth, migrated, instructionFile }.
ferry box remove
Usage: ferry box remove [options] <name>
Remove a box from the config. With --uninstall, remove Ferry from the box first.
Without --uninstall, Ferry does not connect to the box and does not change it.
With and without --uninstall, Ferry stops and removes the tunnel user service
of the box on this machine, which ferry tunnel install wrote. Your per-box
instruction file ~/.ferry/boxes/<name>/AGENTS.md stays. Ferry prints its path.
A later box with the same name gets its text. Delete the file when you do not
need it.
With --uninstall, Ferry reads the box, prints the plan, and asks you to type
the box name. Then it does these steps on the box, in this order:
1. It removes the hooks of ferry notify from ~/.claude/settings.json. The
other hooks stay. Without jq on the box, the hooks stay, and they do
nothing without Ferry.
2. It stops and removes each ferry-*.service user service, such as
ferry-paseo.service. A stopped service stops its agents.
3. It removes each skill link, instruction file link, and root link that
points into ~/.ferry/store or to ~/.ferry/box/AGENTS.md. When ferry sync
--force moved a file of yours to ~/.ferry/backups, Ferry moves the
newest backup of that path back. Else the path stays absent.
4. It removes the ferry PATH block of ~/.profile.
5. It removes ~/.ferry/box, ~/.ferry/exposed, the agent events
~/.ferry/events, ~/.ferry/store, the Ferry binary ~/.local/bin/ferry,
and the marker ~/.ferry/box.json.
Then Ferry removes the box from the config. Ferry keeps these on the box:
the logins and credentials, the SSH keys, the project directories,
~/.paseo, and the tools that Ferry installed: gh, jq, the agent CLIs, the
Paseo CLI, and the tools of the config. It also keeps the settings keys, MCP
servers, and plugins that ferry sync merged into the config files of the
box, ~/.ferry/trash, and each backup that it did not move back.
With --uninstall, Ferry holds the sync lock of the box from before it
connects until the box is out of the config. During that time, a sync that
includes the box fails with the code sync-busy, also a sync of ferry watch.
The watch syncs again later. When a sync for the box runs, the command fails
with that code and changes nothing. Run it again when the sync ends.
--dry-run takes no lock.
When Ferry cannot reach the box, or a box step fails, the box stays in the
config. Run the command without --uninstall to remove the box from the
config only.
Without --uninstall, Ferry refuses the last box of the config, because the
box keeps Ferry. With --uninstall, Ferry removes the last box too, also the
box default of a [host] config. Then the config has no [host] table and no
[box.<name>] table, and the rest of the config stays. ferry sync, ferry
status, ferry install, and ferry watch fail and name ferry box add, until
you add a box with ferry box add <name>. ferry init adds a box too.
Arguments:
name box name
Options:
--uninstall remove Ferry from the box, then remove the box from the config
--yes with --uninstall, do not ask for the box name
--dry-run with --uninstall, print the plan and change nothing
-h, --help display help for command
With --json: { name, defaultBoxRemoved, tunnelService, instructionFile }. tunnelService is the file of the tunnel user service that Ferry removed from this machine, or null. instructionFile is the per-box instruction file that stays on this machine, or null. With --uninstall, also uninstall: { dryRun, plan: { home, services, links: [{ path, link, backup }], notifyHooks, messagingHooks, profileBlock, paths, unsavedWork }, remaining }, or null when cancelled. notifyHooks has the settings files with the hooks of ferry notify. messagingHooks has the settings files with the hooks of agent messaging. unsavedWork is { checked, projects, unchecked } as in ferry status, or null when Ferry could not read it. The plan paths are relative to the box home. backup is the file that Ferry moves back to path, or null. remaining has the names that stay in ~/.ferry on the box. A dry run changes nothing.
ferry box create
Usage: ferry box create [options] <name>
Create a machine at Hetzner Cloud, then add it as a box, install the tools, and
sync.
The machine is in your Hetzner Cloud project and costs money until you run
ferry box destroy <name>. Ferry does not host machines.
Ferry reads the Hetzner Cloud token from the environment variable
HCLOUD_TOKEN, then from the macOS keychain (security find-generic-password
-s ferry -a hetzner -w), then from the Secret Service on Linux (secret-tool
lookup service ferry account hetzner). The token stays on this machine. It
is not in the config, the output, the snapshot, or on the box.
The [provider.hetzner] table of ~/.ferry/config.toml sets the machine:
server_type (default cax21), image (default ubuntu-26.04), location
(default fsn1), and ssh_public_key (default ~/.ssh/id_ed25519.pub, then
id_ecdsa.pub, then id_rsa.pub).
Ferry does these steps:
1. It creates the machine with a firewall that allows inbound TCP port 22
only. The machine gets the SSH user ferry with your public key. It has
no password login.
2. It makes the first SSH host key on this machine and puts it in the
cloud-init user data. It pins the key in ~/.ssh/known_hosts. After the
first connection, it makes a new host key on the box and pins that key.
Ferry never accepts an unknown host key.
3. As root, with your key: it installs Tailscale and joins your tailnet,
and installs gh with its apt source. With an auth key in
FERRY_TAILSCALE_AUTHKEY, or in the keychain or Secret Service entry
with the account tailscale, Ferry sends the key on SSH stdin. Else
Ferry prints a login URL.
4. It writes /etc/sudoers.d/ferry with this rule only, and turns off root
login:
ferry ALL=(root) NOPASSWD: /usr/bin/true, /usr/bin/apt update,
/usr/bin/apt update --error-on=any, /usr/bin/apt install gh -y,
/usr/bin/apt install jq -y, /usr/bin/apt install nodejs npm -y
So agents on the box cannot get root through the ferry user.
5. As the ferry user, it runs ferry box add, ferry install --box <name>,
and ferry sync --box <name>. The box gets gh = "latest" in
[box.<name>.tools], because the rule allows no exact gh version.
When ~/.ssh/known_hosts has another key for the address of the new machine,
Ferry stops. Remove the old key with ssh-keygen -R <address>. When a step
fails after the machine exists, the error names the machine. Run ferry box
destroy <name> to remove it.
--dry-run prints the plan and the price, and creates nothing.
Arguments:
name box name: 1 to 32 characters from a-z, 0-9, and -
Options:
--dry-run print the plan and the price, and create nothing
--yes do not ask before Ferry creates the machine, changes a
[host] config, or installs the tools
--accept-host-keys trust the SSH host keys of the snapshot host on the box
without a confirmation prompt
-h, --help display help for command
With --json: { name, dryRun, provider, serverType, image, location, monthlyPrice, currency, machine: { id, name, box, ipv4, ipv6, serverType, location }, tailscale }, or null when cancelled. machine and tailscale are null with --dry-run. A failure after the machine exists has error.details.machine.
ferry box destroy
Usage: ferry box destroy [options] <name>
Remove the machine of a box at Hetzner Cloud, then remove the box from the
config.
Ferry finds the machine by its label ferry-box=<name>, which ferry box create
sets. It prints the plan and the projects on the box with unsaved work, as
ferry box remove --uninstall does, and asks you to type the box name. When
Ferry cannot reach the box, it says so in one line and continues. Then it
does these steps:
1. It runs tailscale logout on the box, so the box leaves the tailnet.
When that fails, Ferry warns, and you remove the machine in the
Tailscale admin console.
2. It removes the machine and its firewall at Hetzner Cloud. The data on
the machine is lost.
3. It removes the lines of the box from ~/.ssh/known_hosts. Ferry removes
only the lines that it added.
4. It does what ferry box remove <name> does on this machine. It also
removes the last box.
Ferry does steps 1 and 4 only when [box.<name>] has the provider_id of the
machine, which ferry box create writes. Otherwise, for example after a
failed ferry box create, Ferry removes only the machine and its known_hosts
lines, and keeps the box in the config. When the removal of the machine at
Hetzner Cloud fails, the box stays in the config. When only the removal of
the firewall fails, Ferry warns with the firewall name and continues.
Ferry reads the token as ferry box create does.
--dry-run prints the plan and changes nothing.
Arguments:
name box name
Options:
--dry-run print the plan and change nothing
--yes do not ask for the box name
-h, --help display help for command
With --json: { name, dryRun, machine, removed, knownHosts, unsavedWork }, or null when cancelled. removed is the box remove result, or null when the box was not in the config or with --dry-run. knownHosts is the number of removed known_hosts lines. unsavedWork is { checked, projects: [{ path, branch, changes, unpushed: [{ branch, commits }] }], unchecked }, or null when the box is not in the config or Ferry could not reach it.
ferry box default
Usage: ferry box default [options] <name>
Set default_box, the box of install, auth, move, tunnel, and integrations
enable|disable without --box
Arguments:
name box name
Options:
-h, --help display help for command
With --json: { defaultBox }.
ferry skills
Usage: ferry skills [options] [command]
Install skills into the global harness roots that Ferry manages
Options:
-h, --help display help for command
Commands:
add [options] <source> [args...] Run npx skills add as a global copy install.
Ferry adds -g and --copy unless you pass
them.
Global copy installs match Ferry's snapshot
model. The skill is a real
directory in a global harness root, and the
next sync links it to the store.
Put arguments after -- to keep Ferry from
reading them.
Run ferry sync or ferry watch to publish the
skill.
help [command] display help for command
ferry skills add
Usage: ferry skills add [options] <source> [args...]
Run npx skills add as a global copy install.
Ferry adds -g and --copy unless you pass them.
Global copy installs match Ferry's snapshot model. The skill is a real
directory in a global harness root, and the next sync links it to the store.
Put arguments after -- to keep Ferry from reading them.
Run ferry sync or ferry watch to publish the skill.
Arguments:
source skill source, such as owner/repo or a git URL
args other npx skills add arguments, passed through unchanged
Options:
--project install into the current project and do not add -g
-h, --help display help for command
With --json: { argv }. The output of npx goes to stderr.