Quickstart

Reins has two halves: the reins daemon on the machine where your agents run, and the app on your phone. This page takes you from nothing to your first approval.

1. Install the daemon

One static binary with no runtime dependencies, for macOS (Apple Silicon and Intel), Linux and WSL2.

Homebrew

$ brew install enraio/tap/reins

$ brew services start reins

Homebrew then owns starting reins at login, so run setup with --no-service in the next step.

Install script

$ curl -fsSL https://reins.enraio.com/install.sh | sh

The script puts reins in ~/.local/bin (set REINS_INSTALL_DIR to change that) and checks the download against the release's SHA-256 sums when sha256sum or shasum is available.

By hand

Download a build from Releases with its checksums.txt, and check it before you run it:

$ shasum -a 256 -c checksums.txt

2. Run reins setup

$ reins setup

Setup does three things, and says which as it goes: it installs the daemon as a login service (launchd on macOS, a systemd user unit on Linux and WSL2), wires hooks into every supported agent it finds, and prints a pairing QR. Each step is also a command of its own: reins service install, reins install-hooks and reins pair.

Installed with Homebrew: reins setup --no-service.
On a Linux server: loginctl enable-linger, so reins keeps running after you log out.
Under WSL2: switch systemd on first ([boot] systemd=true in /etc/wsl.conf, then wsl --shutdown).
Pairing a second phone: give each one a name with --device NAME, so the second does not revoke the first.

3. Scan the QR from the app

Get the app from the App Store or Google Play. Open it and scan the QR from the pairing screen.

The QR carries every route to your machine (LAN, Tailscale and so on), your username, the SSH host-key fingerprints, the pairing token and an SSH key minted for this pairing. Never a password. The app checks the host key against those fingerprints and refuses a mismatch. Anyone who photographs the QR can reach the machine, so treat it like a key.

Want approvals away from home? Put the machine and the phone on Tailscale or a VPN; the phone picks up the new route on its next connect. See Staying reachable.

4. Your first approval

Restart agents that were already running so they reload their config. Then ask one to do something that needs permission. The request reaches the phone with the agent, the working directory, the exact command and, for an edit, the diff. Destructive commands (rm -rf, force-push, DROP and similar) need a press-and-hold.

If no phone is attached, the agent shows its own prompt at your desk, as it always did. If a phone is attached and nobody answers within three minutes, the same happens. An unanswered approval is never a denial.

5. Check it with reins doctor

$ reins doctor

$ reins logs -f

doctor prints one line per check (the daemon, sshd, each agent's hooks, the multiplexers) and ends with a verdict. logs -f follows what the daemon is doing.

What it writes

Path	What
`~/.reins/token`	The pairing token: random, mode 0600, made on first run. Delete it to rotate, then pair again.
`~/.reins/hook.sock`	The Unix socket the hook shims use. Only your user can open it.
`~/.reins/daemon.log`	The log reins logs reads.
`~/.reins/daemon.out`	The login service's own output.
`~/.reins/sessions.json`	The session list, so a restart doesn't empty the phone's board.
`~/.reins/push_devices.json`	Phones registered for the wake-up push, if you turned alerts on.
`~/.ssh/authorized_keys`	reins pair adds the phone's key here. Same weight as any key you add yourself.

Agent config files are listed per agent in Agents and hooks.

Removing it

reins uninstall-hooks        # take the hooks out of every agent
reins service uninstall      # stop starting at login
# then delete the phone's line from ~/.ssh/authorized_keys