Install on macOS (self-hosted)

This page takes a Mac from nothing to Claude Code asking your phone before it merges a pull request into main, with the gateway running as its own system account where an agent can't reach it: what to install first, what each step of setup prints and what you do, and your first approved merge. How setup works explains what each step does and why. Allow about fifteen minutes.

Self-hosted means the gateway, the part that holds your GitHub App's key and checks your phone's signature, runs on this Mac. Signeto never holds your credentials. This is the free plan.

This guide on video, in 8½ minutes: install, setup steps 1 to 8, the first merge approved on the phone, and the record on the web. The phone is an iPhone; Android works the same. The video is served from signeto.dev; nothing loads from other sites. The signeto CLI you install may be newer than the one recorded, so a few steps may be worded differently; the steps on this page are kept current. Prefer YouTube? Watch it there.

Before you start

You need:

Everything below runs in Terminal.

Check what you already have

Paste this into Terminal to see what's installed already, and skip the steps that are done:

git --version; node --version; which node; gh auth status; claude --version; signeto --version

command not found means that tool isn't installed yet. Otherwise:

Step 5, a browser with your passkey, has nothing to check here.

1. Install Git

xcode-select --install

This installs Apple's command line tools, which include git. If they're already installed, it says so. Then tell Git who you are:

git config --global user.name "Your Name"
git config --global user.email "you@users.noreply.github.com"

2. Install Node.js from nodejs.org

Download the LTS macOS installer from nodejs.org and run it. Signeto needs Node.js 22.13 or newer.

Don't use Homebrew's node for Signeto. The last step of setup copies node into a folder only root can change. Homebrew's node loads libraries from /opt/homebrew, which your account (and so an agent) can write, so the install refuses it. Check which one you have:

which node

It should print /usr/local/bin/node. If it prints /opt/homebrew/bin/node, Homebrew's comes first in your PATH: run brew uninstall node (or brew unlink node), open a new Terminal window and check again. If you need Homebrew's node for other work, see Keeping Homebrew's node.

3. Install the GitHub CLI

The GitHub CLI's macOS installer is at cli.github.com. With Homebrew it's brew install gh (Homebrew is fine for everything but node). If you install Homebrew now, run the two or three "Next steps" lines it prints at the end, or the brew command isn't found.

Then sign in:

gh auth login

Choose GitHub.com, HTTPS, and Login with a web browser. Setup uses gh once, to protect your branch.

4. Install Claude Code

curl -fsSL https://claude.ai/install.sh | bash
claude

Sign in, then type /exit.

5. A browser with your passkey

Step 2 of setup signs you in to Signeto with a passkey, in your default browser. If your passkey is in iCloud Keychain, Safari has it already. If it's in a password manager such as 1Password, add the manager's extension to your browser and sign in to it. See Passkeys and approvals.

6. Install Signeto

sudo npm install -g signeto
signeto --version

The nodejs.org installer puts global packages in /usr/local, which belongs to root, hence sudo.

Run setup

Open Terminal in your repository's folder and run setup:

cd ~/code/your-repo
signeto setup

Setup reads the repository name from the origin remote; pass --repo OWNER/NAME if that's not right. It runs seven steps, then prints an eighth for you to run with sudo. Each step first checks whether it's already done, so if one fails, fix what it says and run signeto setup again: it picks up where it stopped.

Step What happens
1. Gateway Creates this Mac's gateway in ~/.signeto: its key, a starter policy, the ledger and an encrypted store for secrets, whose passphrase goes in your login Keychain
2. Account Signs you in to Signeto with your passkey and registers the gateway
3. Phone Pairs your phone by scanning a QR code
4. GitHub Creates a GitHub App for this gateway and protects your default branch
5. Claude Code Adds Signeto to Claude Code for this project
6. Test Sends a harmless request to your phone
7. Doctor Checks the whole chain
8. System install You run sudo signeto system install --from ~/.signeto: the gateway moves to its own account

Setup starts with a header, then numbers each step as it goes:

Signeto setup
  home /Users/you/.signeto · project /Users/you/code/your-repo · repo you/your-repo · user mode
  Each step checks what is already done. Stop any time; run signeto setup again to continue.

1/7 Create this machine's gateway

A line starting with ? is a question: type an answer, or press Return to take the default shown in [brackets]. A step that's already done prints ✓ already done and setup moves on. The sections below show what each step prints and what you do; each links to How setup works for what the step is for.

Step 1: Gateway

Setup asks for two names:

1/7 Create this machine's gateway
? Name for this gateway [your-mac]:
? Your approver name (used in the policy) [you]:

What to do:

  1. Name for this gateway. Press Return for the default (your Mac's name), or type one: letters, digits, dots, dashes and underscores, no spaces. It appears on your phone as "Request from name".
  2. Your approver name. Press Return for the default (your login name), or type one: 2 to 32 lowercase letters, digits, _ or -, starting with a letter. It goes into the policy as the person who approves. Pick it once and keep it.

Setup then creates the gateway in ~/.signeto and prints four lines:

  ✓ 1/4  Gateway key        created  Ed25519  /Users/you/.signeto/gateway-key.json (0600)
  ✓ 2/4  Policy             wrote /Users/you/.signeto/signeto.yml
  ✓ 3/4  Credential store   created  ...
  ○ 4/4  Approver           none yet: pair your phone (below). Until then every action that needs approval fails closed.

✓ Gateway your-mac is ready.

"Approver none yet" is expected: your phone becomes the approver in step 3. The secrets store's passphrase goes into your login Keychain. What this step sets up: 1. Gateway.

Step 2: Account

Setup prints a sign-in link and a short code, then waits:

2/7 Sign in to your Signeto account
Sign in to the relay to register this gateway:
  1. open   https://api.signeto.dev/...
  2. check  the page shows CODE and approve it with your passkey

What to do:

  1. ⌘-click the link to open it in your browser. Setup doesn't open the browser itself.
  2. No account yet? Create one on that page.
  3. Check the page shows the same code as the terminal. If it doesn't, close the page and don't approve.
  4. Approve with your passkey: Touch ID with iCloud Keychain, or your password manager. If the passkey is on your phone only, choose Use a phone or tablet and scan the QR code with the phone's camera.
  5. Go back to Terminal. It continues by itself:
✓ gateway your-mac registered at https://api.signeto.dev

If the code expires before you approve, run signeto setup again for a new one. Which passkeys work, signing in on a VM, and recovery: Passkeys and approvals. What your account is for: 2. Account.

Step 3: Phone

Setup asks for a name for your phone, then shows a QR code:

3/7 Pair your phone
  Install the Signeto app and sign in, then tap Pair and scan the QR code shown below.
? Name for your phone (used in the policy) [phone]:

What to do:

  1. Type a name for the phone (for example iphone or pixel), or press Return for phone. It's used in the policy's device list.
  2. On the phone, open the Signeto app and sign in with the same account as step 2.
  3. Tap Pair and scan the QR code in the terminal. If the code doesn't fit in the window, make the window bigger or the text smaller (⌘ and −) and run signeto setup again.
  4. The terminal shows the device that scanned it and asks you to confirm:

    Device claiming this pairing
      fingerprint ...
      name        Your iPhone
      platform    ios
      attestation verified (App Attest)
      Check the fingerprint against the phone (Gateways tab › This iPhone, or This phone on Android) before you accept.
    ? Pin this device for approver you? [y/N]
    

    On an Android phone, name is its model (for example Pixel 8), platform is android and attestation is verified (Android Key Attestation).

  5. In the app, open the Gateways tab and compare the fingerprint under This iPhone (This phone on Android) with the one in the terminal. If they match, type y and press Return. If they don't, press Return (the answer is no) and start the step again.

Setup ends the step with ✓ paired Your iPhone through the relay and adds the phone to your approver's devices in the policy. If the app can't sign in, see Passkey sign-in on the phone. What pairing changes: 3. Phone.

Step 4: GitHub

This step has three parts, and setup numbers them 1/3 to 3/3: create a GitHub App, install it, protect the branch.

What to do:

  1. Create the App. Your browser opens GitHub with the App's form already filled in (if nothing opens, ⌘-click the link in the terminal). Click Create GitHub App. GitHub may ask for your password first.
  2. Install it. GitHub then asks where to install the App. Choose Only select repositories, pick your repository, and click Install. The terminal waits until it sees the install.
  3. Protect the branch. Back in Terminal, setup asks:

    Create ruleset "main only via Signeto" on you/your-repo with your gh login (you)? [y/N]
    

    Type y and press Return. Pressing Return alone answers no, and setup prints the ruleset to add by hand in GitHub's settings.

When it's done:

  ✓ 1/3  GitHub App   created YOUR-APP (id 1234567) · https://github.com/apps/...
  ✓ 2/3  Install      installed · covers you/your-repo
  ✓ 3/3  Protect      ...

✓ GitHub is set up for YOUR-APP.

From now on, only the App can update main: gh pr merge, git push and the Merge button on GitHub no longer work for main, for anyone, including you and the agent. See Why the branch has to be protected. If the ruleset step warns about a private repository, see Private repositories on GitHub Free.

Step 5: Claude Code

Nothing to do in this step: setup asks no questions. It adds the gateway to Claude Code for this project only, and allow rules for the two Signeto tools in .claude/settings.local.json (why: 5. Claude Code). Look for these two lines:

✓ added MCP server signeto (local scope) for /Users/you/code/your-repo
✓ claude mcp get signeto: ✓ Connected

If it says the claude command was not found, install Claude Code (step 4 of "Before you start"), open a new Terminal window and run signeto setup again.

Step 6: Test

Setup offers to send a harmless request to your phone:

6/7 Send a test request to your phone
? Send a harmless test request to your phone now? [Y/n]

What to do:

  1. Press Return (the default is yes). The terminal shows a six-character code and waits up to two minutes:

    Sending a test request to Your iPhone through https://api.signeto.dev
    
      Code: K7M2QX
    
      On your phone: open the notification, check the code matches, and approve.
    
  2. On the phone, open the Signeto notification.

  3. Check the code on the phone matches the terminal, then approve with Face ID or your fingerprint.

Nothing runs when you approve; the terminal confirms the round trip:

✓ approved on Your iPhone by you

If nothing arrives, open the app: the request shows there too. If it says no answer, check notifications are allowed for Signeto and the app is signed in, then run signeto test. More: 6. Test.

Step 7: Doctor

Nothing to do but read. signeto doctor checks the whole chain and prints a fix next to anything wrong. At this point, expect one warning, which step 8 fixes:

Privilege boundary
  ⚠ user mode: the gateway runs as your account
    Agents with a shell on this account can bypass approvals. Run `sudo signeto system install`.

Setup then finishes with:

✓ Signeto is set up. Restart Claude Code in /Users/you/code/your-repo and ask it to merge a PR: your phone will ask you first.

and the command for step 8. If doctor shows any other ⚠ or ✗, do what the line under it says and run signeto doctor again. What doctor checks: 7. Doctor.

If a step fails

Setup stops and says where:

✗ stopped at "github" (exit 1). Fix what it says above, then run signeto setup again; finished steps are skipped.

Read the lines above it, fix what they name, and run signeto setup again from the same folder. To leave a step out, pass --skip with its name: gateway, account, phone, github, claude, test or doctor. Errors by name: Troubleshooting.

Step 8: move the gateway out of the agent's reach

Until now the gateway runs as you, and so does Claude Code, which has a shell (why that matters). Setup ends by printing the fix:

sudo signeto system install --from ~/.signeto

It asks for your admin password, then reads the credential store's passphrase from your login Keychain. macOS may ask whether to allow that: click Allow. It prints its plan, asks once, then:

It ends with Signeto VERSION runs as _signeto. macOS then shows a notification, "App Background Activity: Software from 'Node.js Foundation' can run in the background": that's the Signeto service, which runs on the copy of node the install made. You can see it under System Settings → General → Login Items & Extensions; leave it on. Your phone pairing, ledger and GitHub App carry over, and Claude Code keeps working: its next tool call reaches the new gateway. Check it:

signeto doctor

When it shows system mode under "Privilege boundary", setup is finished. If an agent had a shell on your account before this step, it could have read the GitHub App's key: give the App a new key with sudo signeto setup github --recreate.

If the install refuses Homebrew's node, or a folder under /usr/local, see Troubleshooting: macOS.

Your first approved merge

Restart Claude Code in the repository's folder and type /mcp: signeto should show as connected. Open a pull request (or ask Claude Code to make one), then ask Claude Code to merge it.

Claude Code may try gh pr merge first. GitHub refuses it, because of the ruleset, and Claude Code then uses Signeto's merge tool. Your phone shows the request: the repository, the pull request, the target branch, the merge method and the exact commit. Approve it, and the merge goes through with a green Signeto check on the commit. Deny it, and Claude Code is told you said no, with your reason if you gave one.

Then look at the record:

signeto status
sudo signeto ledger
sudo signeto github audit

Next