Ferry

Security model

Normal Ferry sync carries configuration and excludes credentials. An explicit ferry secrets set command is an exception. It transfers selected environment variables from the operator machine to one selected box, outside the Git snapshot.

What normal sync excludes

Normal sync excludes logins, credential files, tokens, API keys, .env files, and whole settings files. A login starts on the box with ferry auth, and its token stays there.

Explicit secret transfer

ferry secrets set reads only selected names from the operator environment, an explicit literal file, or hidden prompt input. It sends values directly over SSH standard input, never through the snapshot or command arguments. Status, plans, logs, JSON results, and errors show no values or value hashes. Replacement requires --replace; unrelated entries stay.

Before transfer, Ferry explains that every process started from a shell or service that loads the variables can access them. This is a box-user environment with no project isolation. Values are plaintext accessible to the box user in ~/.ferry/secrets, with directory mode 700 and data file mode 600. An atomic pointer update selects the literal shell data and separately escaped systemd data together. The shell loader reads and exports values without evaluating them as code. Paseo is optional, and a missing secrets file permits a shell or its service to start.

Shell loading requires an explicit opt-in. ferry secrets shell install --file <name> adds the guarded loader line to one selected startup file on one box, after confirmation or --yes. It preserves unrelated content and file permissions, refuses symlinks, and reports no startup file content. Users can instead add the documented line through their dotfile manager. Provisioning, removal, status, sync, update, and uninstall do not read or change startup files for secrets. After the opt-in, new shell sessions load updates. Existing processes keep their environment. Paseo needs an explicit restart, which stops active agents. Removal does not revoke a key at its issuer or clear a running process environment. Ferry does not stop a CLI or agent from printing its own environment. Native login sessions and credential stores are outside this feature. See Box-local secrets for supported startup modes, limits, and commands.

Deny rules

Before each publish, Ferry checks the carried files against the deny rules:

Scripts, such as hook scripts, pass and keep their executable bit. A match stops the sync, and nothing is published. The error names the file, never the value.

ferry sync --dry-run prints the plan and the deny list. ferry status --json has the list in denyList.

Do not rename, move, split, or encode a file to get past a deny rule. Remove the secret from the file, or remove the file from the carried set.

Per-box instruction files

A per-box instruction file, ~/.ferry/boxes/<name>/AGENTS.md, gets the same deny rules as ~/AGENTS.md, and the private key rule. It never goes into the snapshot. Ferry sends it to its box on the standard input of an SSH command, so the text is not in a command line. A match stops the sync of that box only.

Settings and MCP servers on the box

Ferry merges the carried settings keys and MCP servers into the box files on the box: with jq for JSON files and with awk for the Codex config.toml. The box sends back only a status, never the file.

The MCP gateway

On a box with mcp_gateway = true, the MCP gateway is the OAuth client of each carried remote MCP server. These rules apply:

Stdio MCP servers

For a stdio MCP server, Ferry carries the command, the arguments, and the names of the env keys, never their values. Set the values in the env of the server on the box. Ferry keeps them: the box merges its own entry with jq or the agent CLI, and sends back only a status or key names, never a value. To keep the values of a Claude entry, the box runs claude mcp add-json with the entry, so the values are in its command line while it runs. On a box without hidepid for /proc, another user of the box can see them during that time.

Arguments that stop the sync

A command or an argument stops the sync when it has one of these:

Ferry decodes the percent escapes of a URL before the check, so pa%73sword= is password=. The same rules apply to a URL inside another URL, as it is or with percent escapes, as in https://proxy.example/?next=https://<user>:<password>@host.

In another scheme, a user without a password is a login name and passes, as in git+ssh://git@github.com/you/server or postgresql://alice@db.example/app.

The error names the server and the rule, never the value. Set secrets in the env of the server on the box.

Servers that Ferry skips

The sync continues and names the server when Ferry skips it:

A script file passes, as in node /srv/server.js -c conf.json or python3 -m some_server. Put the script in a file that Ferry carries, or run the server through a tool on the PATH.

Ferry knows only the shells and interpreters in its list. It carries a tool that is not in the list and that runs code from its arguments, such as ssh host CODE, awk, or find -exec. The credential rules still apply to the arguments of that tool.

Ferry never installs a command. ferry status --brief names each missing env key, each command that is not on the box, and each server that Ferry did not carry. The full ferry status lists each skipped server, also a server from a macOS app bundle, with its harness, its name, and the reason, and never with a command or an argument.

SSH

Boxes that Ferry creates

ferry box create creates a machine at Hetzner Cloud with an API token of the operator. ferry box destroy removes it. See Boxes.

The provider token

SSH login and sudo

The SSH host key

Hetzner Cloud has no API that gives the console output of a new machine. So Ferry makes the first host key itself:

  1. Ferry makes an ed25519 host key pair on the operator machine. It puts the key pair in the cloud-init user data of the machine, and it pins the public key for the IP address in ~/.ssh/known_hosts.
  2. Ferry connects with StrictHostKeyChecking=yes and UserKnownHostsFile=~/.ssh/known_hosts on the command line. These options win over ~/.ssh/config. A key that is not the pinned key stops the command at once.
  3. On that connection, Ferry makes a new host key on the box, removes the other host keys, and reloads sshd. Then it removes the first key from known_hosts, pins the new key, and connects again with it.

Hetzner Cloud keeps the user data for the life of the machine, and its API cannot delete it. After step 3, the first key in the user data has no use, because the box has no copy of it. Between the creation and step 3, about one to two minutes, a person with read access to your Hetzner Cloud project can read the first key.

Ferry never accepts an unknown host key and never turns off host-key checks. It only appends lines with the comment ferry:<box> to ~/.ssh/known_hosts, and it removes only those lines. When the file has another key for the address of the new machine, Ferry stops and changes nothing in the file. A provider can give the address of an old server to a new one. Remove the old key with ssh-keygen -R <address>, then create the box again.

Tailscale

The public SSH port

The firewall of the machine allows inbound TCP port 22 only. The port stays open after the Tailscale join. The machine has no password login, so the console of Hetzner Cloud cannot log in. With port 22 closed, a failed Tailscale would leave only the rescue system of Hetzner Cloud as a way in. Port 22 accepts only your SSH key.

Destroy

ferry box destroy runs tailscale logout on the box, removes the machine and its firewall at Hetzner Cloud, removes the known_hosts lines of the box, and then removes the box from the config. It runs tailscale logout and removes the box from the config only when the box table has the provider_id of the machine, which ferry box create writes. A host with the same box name that you added with ferry box add keeps its tailnet login and its box table. The SSH key that Ferry added to the Hetzner Cloud project stays, because other machines can use it.

Files that leave a box

ferry move --from-box and ferry adopt --from-box copy files from a box. For a skill or a project that leaves a machine, that machine checks and copies in one step:

Hashes and names

The origin URL of a project

A credential in the origin URL of a project stays on its machine. ferry move takes the user and the password, a token in the place of the user, and each secret query parameter out of the URL before the URL leaves the source. The destination clones from the URL without them, so it needs its own login for the clone. A login name stays, as in ssh://git@host and git@host:path. In an output, [credential] stands for a credential in a URL.

The limit of the rule

The normal sync and file-transfer deny rules depend on a box that runs an honest Ferry. Explicit ferry secrets set is the selected operator-to-box environment transfer exception described above.

The check on the box protects against mistakes and against files that change. It does not protect against a box account that an attacker controls, because that Ferry can give any answer and any bytes. This is why the operator machine applies its own deny rules to the bytes that arrive from a box.

Ferry runs commands with your SSH user. Use a box and a user that you trust with the agents that run there.

The session scan of ferry move also has a limit. See Moving a project.

Report a vulnerability

Do not open a public issue for a security problem. Report it privately with GitHub private vulnerability reporting. See SECURITY.md for the scope.