Ferretry Already set up? Open the app ↗

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
  1. 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 --check to inspect the steps without recording answers.

    Homebrew

    Homebrew · macOS
    brew tap kirinnee/ferretry https://github.com/kirinnee/ferretrybrew install --cask ferretryfy onboard

    The 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 onboard

    Updates 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 onboard

    On 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 onboard

    It checks the download and puts both programs in ~/.local/bin; add that to your PATH.

    Debian, Ubuntu or Fedora package? Every option is in INSTALLATION.md; run fy onboard after 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.
  2. 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 pair
    Pairing 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 pair waits up to two minutes for the scan. Add --no-wait to print the QR code and link and exit instead; add --open too when you are sitting at this computer, to hand the link to its browser.

    At this computer
    fy pair --open --no-wait
    Over SSH or from a script
    fy pair --no-wait

    No password to set: your phone registers a passkey, and risky actions ask for it later.

  3. 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.

Open the app