Install on Linux (self-hosted)
This page takes a Linux machine 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 machine. Signeto never holds your credentials. This is the free plan.
The commands are for Ubuntu and Debian; we've tested Ubuntu 26.04. Other distributions with systemd work with their own package commands.
Before you start
You need:
- A Linux machine with systemd and a desktop session (setup opens your browser), and
sudo, once, for the last step. - An iPhone, or an Android phone (Android 9 or newer) with the Signeto app from the App Store or Google Play, signed in with your Signeto account, and Face ID or Touch ID, or a fingerprint or face unlock. New to the app? Watch the one-minute setup: account, code and passkey.
- A GitHub repository you administer. It needs to be public, or owned by an account on a paid GitHub plan; see Private repositories on GitHub Free.
Everything below runs in a terminal. Make the terminal window big (maximize it): step 3 shows a QR code that needs about 40 lines.
Check what you already have
Paste this into the 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:
git --versionprints a version andgh auth statussays you're logged in to github.com: skip step 1, but still tell Git who you are if you haven't.node --versionprintsv22.13.0or newer, andwhich nodeprints/usr/bin/node: skip step 2. If it prints a path in your home folder (for example fromnvm), do step 2.claude --versionprints a version: skip step 3.signeto --versionprints a version: skip step 5.
Step 4, a browser with your passkey, has nothing to check here.
1. Install Git and the GitHub CLI
sudo apt update
sudo apt install -y git curl gh
git config --global user.name "Your Name"
git config --global user.email "you@users.noreply.github.com"
gh auth login
For gh auth login, choose GitHub.com, HTTPS, and Login with a web browser. Setup uses gh once, to protect your branch. If your distribution has no gh package, cli.github.com has its own repository.
2. Install Node.js 22 or newer
Signeto needs Node.js 22.13 or newer, and many distributions ship an older one. NodeSource's packages are current:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version
The last step of setup copies node into a folder only root can change, so it has to be a node that loads its libraries only from system folders. Check:
ldd "$(which node)"
Every path it lists should start with /lib or /usr/lib. A node from NodeSource or your distribution passes. Don't use nvm for Signeto: its node lives in your home folder, which your account (and so an agent) can change, and sudo can't find it.
3. Install Claude Code
curl -fsSL https://claude.ai/install.sh | bash
claude
Sign in, then type /exit. If claude isn't found afterwards, open a new terminal: the installer adds ~/.local/bin to your PATH.
4. A browser with your passkey
Step 2 of setup signs you in to Signeto with a passkey, in your browser. On Linux a passkey usually lives in a password manager's browser extension (1Password, Bitwarden and others): add the extension and sign in to it. If your passkey is only in iCloud Keychain, use Lost your passkey? on the sign-in page: it emails you a code that adds a passkey on this machine. See Passkeys and approvals.
5. Install Signeto
sudo npm install -g signeto
signeto --version
NodeSource's npm puts global packages in /usr, which belongs to root, hence sudo.
Run setup
Open the 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 machine's gateway in ~/.signeto: its key, a starter policy, the ledger and an encrypted store for secrets, whose key is a file next to it |
| 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 /home/you/.signeto · project /home/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 Enter to take the default shown in [brackets]. A step that's already done prints ✓ already done and setup moves on.
Step 1: Gateway
Setup asks for two names:
1/7 Create this machine's gateway
? Name for this gateway [your-machine]:
? Your approver name (used in the policy) [you]:
What to do:
- Name for this gateway. Press Enter for the default (the machine's hostname), or type one: letters, digits, dots, dashes and underscores, no spaces. It appears on your phone as "Request from name".
- Your approver name. Press Enter 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 creates the gateway in ~/.signeto:
✓ 1/4 Gateway key created Ed25519 /home/you/.signeto/gateway-key.json (0600)
✓ 2/4 Policy wrote /home/you/.signeto/signeto.yml
✓ 3/4 Credential store created /home/you/.signeto/credentials.json (key in /home/you/.signeto/credentials.key (0600))
⚠ anything running as you, an agent with a shell too, can read it; sudo signeto system install moves it out of their reach
○ 4/4 Approver none yet: pair your phone (below). Until then every action that needs approval fails closed.
✓ Gateway your-machine is ready.
"Approver none yet" is expected: your phone becomes the approver in step 3. The ⚠ is about the secrets store's key, which step 8 moves out of your account. 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/account/device#code=ABCD-EFGH
2. check the page shows ABCD-EFGH and approve it with your passkey
waiting for approval (code expires in 10 min; ctrl-c to give up)…
What to do:
- Ctrl-click the link to open it in your browser (in GNOME Terminal; or copy it into the browser). Setup doesn't open the browser itself at this step.
- No account yet? Create one on that page.
- Check the page shows the same code as the terminal. If it doesn't, close the page and don't approve.
- Approve with your passkey.
- Go back to the terminal. It continues by itself:
✓ signed in
✓ gateway your-machine registered at https://api.signeto.dev
If the code expires before you approve, run signeto setup again for a new one. Signing in through your phone and a QR code instead needs Bluetooth on both, which often doesn't work in a virtual machine. Which passkeys work, and recovery: Passkeys and approvals.
If it stops with gateway_limit, your plan's gateway slot is taken: the message names the gateway using it and where to remove it. See "gateway limit".
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:
- Type a name for the phone (for example
iphoneorpixel), or press Enter forphone. - On the phone, open the Signeto app, signed in with the same account as step 2.
- Tap Pair a gateway and scan the QR code in the terminal. If the top of the code is cut off, the window is too small: maximize it, or make the text smaller (Ctrl and −) and run
signeto setupagain. -
The terminal shows the device that scanned it and asks you to confirm:
Device claiming this pairing fingerprint ... name iPhone platform ios attestation verified (App Attest) ? Pin this device for approver you? [y/N]On an Android phone,
nameis its model (for examplePixel 8),platformisandroidandattestationisverified (Android Key Attestation). -
The app shows the same fingerprint (also on the Gateways tab, under This iPhone, or This phone on Android). If they match, type
yand press Enter. If they don't, press Enter (the answer is no) and start the step again.
Setup ends the step with paired phone through the relay and adds the phone to your approver's devices in the policy. What pairing changes: 3. Phone.
Step 4: GitHub
This step has three parts: create a GitHub App, install it, protect the branch.
What to do:
- Create the App. Your browser opens GitHub with the App's form already filled in (if nothing opens, open the
http://127.0.0.1:…link the terminal prints). Click Create GitHub App. GitHub may ask for your password first. - 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.
-
Protect the branch. Back in the terminal, setup asks:
Create ruleset "main only via Signeto" on you/your-repo with your gh login (you)? [y/N]Type
yand press Enter. Pressing Enter alone answers no, and setup prints the ruleset to add by hand in GitHub's settings.
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.
Step 5: Claude Code
Nothing to do: setup 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). It ends with claude mcp get signeto: ✓ Connected.
If it says the claude command was not found, install Claude Code (step 3 of "Before you start"), open a new terminal and run signeto setup again.
Step 6: Test
Setup offers to send a harmless request to your phone. Press Enter (the default is yes). The terminal shows a six-character code; on the phone, open the Signeto notification, check the code matches the terminal, and approve with Face ID or your fingerprint. Nothing runs when you approve; the terminal confirms the round trip with ✓ approved. If nothing arrives, open the app: the request shows there too. More: 6. Test.
Step 7: Doctor
Nothing to do but read. signeto doctor checks the whole chain. At this point, expect one warning, which step 8 fixes:
⚠ Agents with a shell on this account can bypass approvals. Run `sudo signeto system install`.
sudo signeto system install --from ~/.signeto
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, for example ✗ stopped at "github" (exit 1). Read the lines above it, fix what they name, and run signeto setup again from the same folder: finished steps are skipped. 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: an agent that wanted to could read the gateway's keys and the GitHub App's key, or replace the signeto program (why that matters). Setup ends by printing the fix:
sudo signeto system install --from ~/.signeto
It prints its plan, asks once (? Perform this plan? [y/N], type y), then:
- creates a system account
signeto(no login shell), which runs the gateway, and a groupsignetoclients, and adds you to it so you can reach the gateway; - copies
nodeand Signeto into/opt/signeto, owned by root; - moves your gateway (key, policy, ledger, pairings, relay registration and secrets) into
/var/lib/signeto, which onlysignetocan read, and removes the keys and secrets from~/.signeto; - starts the gateway as a systemd service,
signeto-gateway, listening on/run/signeto/gateway.sock.
It ends with ✓ Signeto VERSION runs as signeto.
Then apply your new group: log out and back in, or, in the terminal you're using, run
newgrp signetoclients
Until you do, Claude Code and signeto status can't reach the gateway. Your phone pairing, ledger and GitHub App carry over. Check it:
signeto doctor
When it shows system mode and ends with ✓ everything checks out, 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 node, see Troubleshooting: Linux.
Your first approved merge
Start Claude Code in the repository's folder:
claude
The first time, Claude Code asks whether you trust the folder, and lists the two Signeto tools setup allowed. The highlighted answer is No, exit: press the down arrow to Yes, I trust this folder, then Enter.
Open a pull request (or ask Claude Code to make one), then ask Claude Code to merge it. Even with auto mode on, the merge waits for your phone: it shows the repository, the pull request, the target branch, the merge method and the exact commit. Approve it with Face ID or your fingerprint, and Claude Code reports the merge, 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
github audit ends with ✓ every commit on the default branch came through a Signeto approval. The same decisions are on the web: Sign in at signeto.dev, then Overview and Ledger, where your browser checks each signature itself.
Next
- Using Signeto day to day: what needs
sudo, changing the policy, upgrading, the emergency stop, logs. - Troubleshooting: the group after step 8,
nodefromnvm, sign-in, devices, plan limits, private repositories. - Removing Signeto:
signeto teardown, setup in reverse.