Ferry

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.

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.