How setup works
signeto setup runs seven steps, then prints an eighth for you to run with sudo (on macOS and Linux), which it never runs itself. This page explains what each step does and why. For what to type and what you see, follow the guide for your computer: Install on macOS, Install on Windows or Install on Linux. The Install page has the short path and a table of the steps.
Each step first checks whether it is already done, so if you stop halfway (or something fails), fix it and run signeto setup again: it picks up where it stopped. Run it from your repository's folder. It reads the repository name from the origin remote; pass --repo OWNER/NAME if that's not right.
1. Gateway
Setup asks for two names:
- A gateway name, for this machine. It appears on your phone's approval cards as "Request from name". The default is your computer's name.
- Your approver name, which goes into the policy (
signeto.yml) as the person who approves merges. The default is your login name. Pick it once and keep it: each paired device is recorded under an approver name, and a device can only approve rules for that name.
Everything lives in ~/.signeto (%USERPROFILE%\.signeto on Windows): the gateway key, the policy, the ledger and the encrypted credential store. The starter policy sends merges into main and deploy.yml workflow runs to your phone (only your approver can say yes), lets ordinary reads through without asking (they're still recorded), and asks for approval on anything it doesn't recognise.
This step pairs no approver: your phone is the approver, and it pairs in step 3. Until then, anything that needs approval is refused. The starter policy accepts approvals only from a key the gateway can verify is in hardware (software_keys: deny), which today means the Signeto app on iPhone (App Attest) or Android (Key Attestation). Earlier versions also paired "this machine" with a key kept in a file in ~/.signeto; anything running as you can read that file, including an agent with a shell, so setup no longer creates one. If you set up with an earlier version, signeto doctor and the gateway's log tell you how to retire that key once your phone is paired.
2. Account
The terminal prints a sign-in link and a short code. Open the link, check that the page shows the same code, and approve it with your passkey (or create an account first). The terminal continues by itself once you have.
Your account links your gateway to your phone. It never holds a GitHub credential, and it can't approve anything: approvals are signed on your phone with a key that never leaves it. See Passkeys and approvals for which passkeys work and why there are no passwords.
3. Phone
Open the Signeto app on your phone and sign in with the same account. Tap Pair and scan the QR code in the terminal. Once paired, the terminal prints the phone's and the gateway's fingerprints: check they match what the app shows.
Pairing adds the phone to your approver's device list in signeto.yml, so it can approve merges right away. If the app can't sign in, see Passkey sign-in on the phone.
From now on, a change to signeto.yml takes effect only after your phone approves it. When the file changes, the gateway keeps using the policy you last approved and sends your phone a request, "Change this gateway's policy", that lists what changes. That includes adding a second device later: your first phone approves it. A phone paired with an older version of the app shows this request with its raw details instead of one sentence; read the summary line. signeto status shows a change that is waiting or was denied.
4. GitHub
This step does two things.
It creates a GitHub App for this gateway. Your browser opens GitHub with the App already filled in. Click Create GitHub App, then install it on your repository. The App only asks for what Signeto needs: read access to code and pull requests, permission to merge and run workflows, and permission to post the green Signeto check on what it merges. Its private key goes straight into the gateway's encrypted store; it is never shown.
The gateway uses this App to create a token for one action at a time: a merge you approved gets a token that can merge that one pull request and expires within the hour. Claude Code never sees a token.
It protects your default branch. Setup adds a ruleset named "main only via Signeto": only the Signeto App can update main. Nobody can push to it or merge into it directly, including anyone with their own gh login or Git credentials, and including the agent. This is what makes the approval required rather than optional.
Setup asks before it creates the ruleset (pass --yes to skip the question). Without gh, it prints the exact ruleset to add in GitHub's settings. On a private repository owned by an account on GitHub's free plan, setup doesn't create one: see Private repositories on GitHub Free.
Why the branch has to be protected
Signeto can only require your approval where it stands between the agent and the credential. If Claude Code can also run gh pr merge or git push with your own GitHub login, it can merge without asking. The ruleset closes that gap on GitHub's side: only the Signeto App may update the branch, so every other route fails, however the agent tries. signeto doctor lists the credentials on this machine that the ruleset is covering for.
This applies to you too: the Merge button on GitHub stops working for that branch. Merge by asking the agent, and approve on your phone. To change this, edit or disable the ruleset in the repository's settings on GitHub.
signeto github audit lists any commit on the branch that didn't come through an approval, so you'll see it if the protection was ever off.
5. Claude Code
Setup adds the gateway to Claude Code for this project (claude mcp add-json with local scope: only you, only this folder) and checks that it connects. Claude Code then has tools like signeto__github__merge_pull_request.
It also offers to add allow rules for those tools to the project's .claude/settings.local.json. Say yes. Without them, Claude Code's own permission check (or auto mode) may block the merge tool as "merge without review", not knowing that your phone is the review. The rules cover only the Signeto tools, never shell commands, and every gated tool still needs your approval on the phone.
Restart Claude Code in the project afterwards so it picks up the new server.
6. Test
Setup sends a harmless request to your phone. The terminal shows a six-character code, and the notification on your phone shows the same code. Check that they match and approve with Face ID or your fingerprint. Nothing runs when you approve: it's a check that push, the card, the biometric check and the signed receipt all work. The test is recorded in your ledger like any other approval.
You can run it again any time with signeto test.
7. Doctor
signeto doctor checks the whole chain without changing anything, and prints a fix next to anything wrong:
- the gateway, policy, ledger and freeze switch;
- the connection to Signeto;
- your paired devices against the policy's device list;
- the Claude Code entry for this project;
- the GitHub App's permissions (including any you haven't accepted yet) and the branch ruleset;
- bypass: whether this machine has its own way into GitHub (a
ghlogin, a Git credential helper, SSH keys,GITHUB_TOKEN-style variables), and whether the ruleset blocks them.
When doctor passes, setup has one step left on macOS and Linux.
8. Move the gateway out of the agent's reach
Until now the gateway runs as you, with everything in ~/.signeto. Claude Code runs as you too, and it has a shell: an agent that wanted to could edit your policy, read the gateway's keys and the GitHub App's key, or replace the signeto program itself. signeto status and signeto doctor say so: "Agents with a shell on this account can bypass approvals." Setup ends by printing the fix:
sudo signeto system install --from ~/.signeto
It prints its plan, then carries it out: it creates a hidden account for the gateway (_signeto on a Mac, signeto on Linux), copies node and Signeto into a folder only root can change, moves your gateway (key, policy, ledger, pairings, relay registration and secrets) into a folder only that account can read, removes those keys and secrets from ~/.signeto, and starts the gateway as a system service. Your phone pairing, ledger and GitHub App carry over; nothing needs to be set up again. Claude Code keeps working as it was: the next tool call reaches the new gateway. (On Linux, log out and in again first, so your account's new group applies.)
Afterwards, changing the policy, pairing a device, revoking one, or changing a secret needs your admin password: sudo signeto policy edit, sudo signeto pair --relay, and so on. That is the point: the agent doesn't have your password. signeto status, signeto doctor, signeto approve and Claude Code itself need no sudo. signeto system status shows the install and checks that nothing in it is writable by your account. After npm install -g signeto brings a new version, run sudo signeto system upgrade to move the gateway to it. More in Using Signeto day to day.
If an agent had a shell on your account before this step, it could have read the GitHub App's key. To be safe, give the App a new key afterwards: sudo signeto setup github --recreate.
When signeto doctor shows system mode under "Privilege boundary", setup is finished.
Windows doesn't have this step yet: the gateway keeps running as your account. See What user mode means.