Get started
One command to your fleet
Install Ferretry where Claude Code or Codex runs, then run fy onboard to check the first-run
steps. Use fy runtime scan to inspect your setup, then fy runtime link claude or
fy runtime link codex to link it. Pair your phone with fy pair.
Rather have your agent do it? Copy the prompt — it hands you each command to run.
- Latest release v5.0.0
- macOS on Apple silicon · Linux amd64 / arm64
- Needs Claude Code or Codex, and tmux
-
Step 01
Install it, then run setup.
Pick how you install software. The tab for this device is chosen for you. Each one ends with
fy onboard, which checks the first-run steps and records what is found. Missing setup can be left for later.Run
fy onboard --checkto inspect the steps without recording answers.Homebrew
Homebrew · macOS brew tap kirinnee/ferretry https://github.com/kirinnee/ferretrybrew install --cask ferretryfy onboardThe cask clears macOS's quarantine flag for you, so the first run just works.
Nix profile
Nix · macOS or Linux nix profile install github:kirinnee/ferretryfy onboardUpdates with
fy update, no config to edit.Home Manager or nix-darwin
Add to your flake inputs.ferretry.url = "github:kirinnee/ferretry";home.packages = [ inputs.ferretry.packages.${pkgs.stdenv.hostPlatform.system}.default ];Then rebuild home-manager switch --flake .fy onboardOn nix-darwin, rebuild with
darwin-rebuild switch --flake .instead. Updating means bumping the flake input, because your config owns the version.Installer
Any Mac or Linux curl -fsSL --connect-timeout 30 --max-time 600 https://github.com/kirinnee/ferretry/releases/latest/download/install.sh | bashPATH="$HOME/.local/bin:$PATH" fy onboardIt checks the download and puts both programs in
~/.local/bin; add that to yourPATH.Debian, Ubuntu or Fedora package? Every option is in INSTALLATION.md; run
fy onboardafter any of them.Or let your agent do it.
Paste this into Claude Code or Codex on the computer you want to use. It looks around, recommends one way to install, and hands you each command to run. It never installs anything itself, so its safety checks never get in the way.
Prompt for Claude Code or Codex Help me set up Ferretry on this computer. Follow these rules exactly. How to talk to me - Whenever I need to do something, reply in exactly this shape, then stop and wait: **Run this** ```bash <the exact command(s), nothing else> ``` **Why:** <one short line> **What you'll see:** <one short line> - One action at a time. No paragraphs, no repeated caveats. - Report what you find in 3 to 5 short lines, then your recommendation. What you may run - Only read-only checks and the fy commands named below. I run every install, update, sudo or service command myself. - Claude Code: tell me to type the command after a ! in this chat. Codex: tell me to run it in my own terminal, and hand me any check your sandbox blocks. - Anything that needs sudo goes in my own terminal. - If a command is blocked or fails, tell me the error in one line and stop. Never retry it or look for a way around it. - Never print, save or ask for a token, a secret or a pairing code. 1. Look around (read-only; an error just means "not there"): uname -sm command -v brew nix fy home-manager darwin-rebuild fy onboard --check --json If that says "complete": true, go to step 3. Otherwise recommend ONE way to install with a one-line reason, list the others one line each, and let me choose: - Homebrew, if brew is there: easiest updates. - Home Manager or nix-darwin, if I use one: it lives in my config. - nix profile, if nix is there: one command, no config. - Installer, otherwise: one line, nothing else needed. 2. Hand me ONE "Run this" for my choice. Homebrew: brew tap kirinnee/ferretry https://github.com/kirinnee/ferretry brew install --cask ferretry fy onboard --yes nix profile: nix profile install github:kirinnee/ferretry fy onboard --yes Home Manager or nix-darwin: first show me where these two lines go in my flake. Then hand me the rebuild (home-manager switch --flake . or darwin-rebuild switch --flake .) and fy onboard --yes: inputs.ferretry.url = "github:kirinnee/ferretry"; home.packages = [ inputs.ferretry.packages.${pkgs.stdenv.hostPlatform.system}.default ]; Installer: curl -fsSL --connect-timeout 30 --max-time 600 https://github.com/kirinnee/ferretry/releases/latest/download/install.sh | bash PATH="$HOME/.local/bin:$PATH" fy onboard --yes 3. Check: run fy onboard --check --json. Read the steps and remedies. If incomplete, show the next remedy and wait. --yes leaves missing steps for later; it does not install or import. 4. Pair my phone: hand me fy pair as a "Run this" for my own terminal, not this chat, so the code never reaches you. What I'll see: a QR code to scan with my phone's camera within two minutes. 5. Stop. Afterwards, only when I ask: fy daemon status, fy login ls, fy runtime ls, fy runtime link claude or fy runtime link codex, and fy onboard (it asks questions, so I run it in my own terminal). To update later: fy update, or the Update button in the app. -
Step 02
Pair your phone.
After checking the first-run steps, run this and scan the QR code with your phone's camera. The code lasts two minutes and works once.
Your phone does not need to be on the same network. When it cannot reach the computer directly, it connects through Ferretry's end-to-end encrypted relay, which never sees the code or anything you send.
On your computer fy pairPairing over SSH, or at this computer
Run these in your own terminal, never through an agent: the code is a live key to this computer.
fy pairwaits up to two minutes for the scan. Add--no-waitto print the QR code and link and exit instead; add--opentoo when you are sitting at this computer, to hand the link to its browser.At this computer fy pair --open --no-waitOver SSH or from a script fy pair --no-waitNo password to set: your phone registers a passkey, and risky actions ask for it later.
-
Step 03
Finish setup in the app.
Once your phone is paired, the app opens setup by itself. Every step can be skipped and changed later in Settings.
- Claude Code and Codex — use your existing login and setup
- Keys — add logins and providers; keys go in the secret store
- Voice — on-device dictation, with optional clean-up
- Warden — what watches your sessions, and how much it may spend
Troubleshooting
If something is off.
-
Check everything.
Check the first-run steps, changing nothing.
Check fy onboard --check -
Is the daemon running?
Says whether it is serving, and what started it.
Status fy daemon status -
What went wrong?
Checks this CLI against the daemon, plugin by plugin.
Doctor fy doctor -
macOS says it can't open
fy.The programs are not code-signed. Homebrew handles this; after any other install, clear the quarantine flag once.
macOS xattr -d com.apple.quarantine "$(command -v fy)" -
Review the first-run steps again.
Forgets which first-run steps were answered so you can check them again. Your setup and paired devices stay in place.
Reset fy onboard reset
Already set up?
Open the app and go to your machines. This guide is only for a computer that has no Ferretry yet: to add another one, run step 1 on it.