Troubleshooting

Start with signeto doctor: it checks the whole chain without changing anything and prints a fix next to anything wrong. If setup stopped, fix what it says and run signeto setup again; finished steps are skipped. Find your symptom or the error message below. Sections marked macOS or Windows apply only there.

Signing in and pairing

Passkey sign-in on the phone

On iPhone: the sign-in sheet only offers iCloud Keychain, not your password manager. iOS shows a password manager only if it's switched on under Settings → General → AutoFill & Passwords. Turn yours on there, then try again. If you created the passkey recently on another device, open your password manager's app on the phone once so it syncs.

On Android: the sign-in sheet only offers Google Password Manager. Other passkey providers need Android 14 or newer, and you switch them on in the phone's settings, under passwords and passkeys (the wording varies by maker). Turn yours on there, then try again.

Signing in on a computer that doesn't have your passkey. In the browser's passkey prompt, choose Use a phone or tablet (some browsers say Use a different device) and scan the QR code with your phone's camera, then unlock it (Face ID or fingerprint). Bluetooth has to be on for both. No phone at hand? Use Lost your passkey? on the sign-in page: it emails you a code that adds a passkey on that computer.

Sign-in fails with an error about the app and the domain. On iPhone: before allowing passkey sign-in, iOS checks that the app belongs to signeto.dev, and it caches the result from when the app was installed. If that check failed (for example, no network during install), delete the app, reinstall it, wait half a minute, and sign in again. On Android: the phone checks the app against signeto.dev/.well-known/assetlinks.json. Make sure the app came from Google Play, update Google Play services, and try again.

More on which passkeys work, signing in on a VM, and recovery: Passkeys and approvals.

"approver_unknown" or a device that can't approve

Each paired device belongs to one approver name, and the policy's rules name approvers. If your policy has more than one approver, pass --approver NAME to signeto pair. If signeto doctor reports a device "not in approvers.name.devices", add the device's name to that list in signeto.yml. Run signeto devices to see your devices and who they belong to.

"gateway limit" or "device limit"

The free plan allows one gateway and two devices per account. Reinstalling the app registers a new device. To free the gateway slot before setting up a new machine, run signeto relay unregister on the old one (or signeto teardown, which also removes everything else; see Removing Signeto). If the old machine is gone (reinstalled, wiped, or a setup you abandoned after signing in), remove the gateway on the web instead: Sign in at signeto.dev, then Overview → Gateways → Remove next to it. In the Signeto app, Remove gateway asks how: Remove from this iPhone (Remove from this phone on Android) only removes it from that phone, and the gateway keeps its slot; Remove and revoke on account also revokes it on your account after Face ID or biometric unlock, which frees the slot (your account gets an email). Older app versions only remove it from the phone.

"gateway revoked"

signeto doctor or signeto status says the gateway was revoked: every approval request fails until it is registered again. If it was revoked from your phone (Remove and revoke on account), run signeto relay register on its computer: the same gateway is attached again, and phones still paired with it work again at once. Pair the phone that revoked it again with signeto pair --relay. If you didn't do this, revoke that phone on your account (Overview → Devices) first. A gateway revoked on the account page or with signeto relay unregister can't be registered again. To free a device slot, revoke an old device with signeto devices revoke NAME.

GitHub

Private repositories on GitHub Free

GitHub doesn't enforce rulesets on private repositories for accounts on the free plan, so setup doesn't create one there: it would look like protection without being any. You can:

Signeto never changes your repository's visibility or your plan.

The Merge button on GitHub no longer works

That is the ruleset setup added, doing its job: only the Signeto App can update main, for anyone, including you. Merge by asking the agent, and approve on your phone. See Why the branch has to be protected.

Claude Code and the phone

Claude Code blocks the merge tool

If Claude Code says a merge was blocked by a permission check or by auto mode ("Merge Without Review"), the allow rules from step 5 are missing. Run:

signeto connect claude-code --allow-tools

Nothing arrives on the phone

Run signeto test. If it times out: check that notifications are allowed for Signeto in the phone's settings, that the app is signed in, and that opening the app shows the pending request. Then run signeto doctor, which checks the connection and your paired devices.

"gateway already running"

With the system install (step 8) there is one gateway for the machine, run by the system, and this message does not appear; signeto stop doesn't apply to it. Before step 8: you can use Signeto in several projects at once. Every Claude Code session for a Signeto home folder (~/.signeto) shares one gateway: the first session that needs it starts it in the background, the others connect to it, and it stops by itself a few minutes after the last session closes. Each session's requests are recorded under its own name, session and project folder. Other commands, including signeto test and signeto doctor, work alongside it, and signeto status shows the running gateway and how many sessions use it.

Older versions of Signeto ran the gateway inside the first Claude Code session, so a second project got this message and no Signeto tools. If you still see it, a gateway from an older version is running: run signeto stop, then restart the Claude Code session that has no Signeto tools. Also run signeto stop after you upgrade Signeto or change its secrets; the next tool call starts a fresh gateway.

Every project under one home uses the same policy, the home's signeto.yml. A signeto.yml inside a project folder is ignored. If a project needs a different policy, give it its own home; pointing one project at another policy file with SIGNETO_POLICY while a gateway with a different one runs is refused ("policy_mismatch"). The same goes for a second, separate gateway on the same machine (for example, a test setup): export SIGNETO_HOME=~/signeto-test before every signeto command, and setup records that home in Claude Code's entry for the project.

After the system install

"needs_root" or "run with sudo"

With the system install, the gateway's files belong to its own account, so commands that change them (policy, pairing, devices, secrets, freeze) or read them (signeto ledger, signeto devices) need sudo. The message shows the full command. It names /usr/local/lib/signeto/bin/signeto (/opt/signeto/bin/signeto on Linux): that copy belongs to root, while the signeto on your PATH is your account's, and so an agent's, to replace. See Using Signeto day to day for which commands need it.

macOS

Step 8 refuses Homebrew's node

The install says node "loads libraries from paths your account can write". Install Node.js from nodejs.org, make sure which node prints /usr/local/bin/node (see step 2 of Install on macOS), and run sudo signeto system install --from ~/.signeto again.

Keeping Homebrew's node

If you need Homebrew's node first in your PATH for other work, install the nodejs.org package too, and run step 8 with it explicitly:

sudo /usr/local/bin/node /usr/local/lib/node_modules/signeto/dist/bin.js system install --from ~/.signeto

Use the same form for system upgrade.

"the directories the install goes into must be root's"

On an Intel Mac, Homebrew takes ownership of folders under /usr/local, including /usr/local/lib. Anyone who owns a parent folder can swap the install under it, so the install refuses. The message names the folders; give them back to root (for example sudo chown root:wheel /usr/local/lib) or uninstall Homebrew's copy, then run step 8 again.

Linux

Claude Code or signeto status can't reach the gateway after step 8

Your account isn't in the signetoclients group yet in this session. Log out and back in, or run newgrp signetoclients in the terminal you're using. id should list signetoclients. If it still doesn't after logging in again, add yourself: sudo usermod -aG signetoclients $USER.

Step 8 refuses node

The install says node "loads libraries from paths your account can write". Install Node.js from NodeSource or your distribution (see Install on Linux), check ldd "$(which node)" lists only /lib and /usr/lib paths, and run sudo signeto system install --from ~/.signeto again.

"sudo: signeto: command not found"

sudo uses its own PATH, which doesn't include folders in your home. Install Signeto with the system npm (sudo npm install -g signeto), not one from nvm.

The QR code in step 3 is cut off

The terminal window is too small for the code. Maximize the window, or make the text smaller (Ctrl and −), and run signeto setup again: finished steps are skipped and a new code is shown.

Windows

"npm.ps1 cannot be loaded because running scripts is disabled"

Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, then try again. See step 2 of Install on Windows.

"The term 'claude' is not recognized"

Claude Code's folder isn't on your PATH. See step 4 of Install on Windows.

"Author identity unknown" when you commit

Git needs your name and email. See step 3 of Install on Windows.

"gateway_unverified"

A gateway from Signeto 0.2.5 or older is still running, and can't prove it's yours. Run signeto stop, then restart Claude Code.

"gateway_identity_mismatch"

Another program is listening on this gateway's pipe and couldn't prove it holds the gateway's key, so Claude Code's session wasn't sent to it. Restart Windows (or sign out any other accounts), then start Claude Code again. If it keeps happening, tell us at security@signeto.dev.

Still stuck

Email support@signeto.dev with what you were doing, what you expected and any error code you saw, but never a passkey, a token or a key. See Support.