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.

This guide on video, in 8 minutes: install, setup steps 1 to 8 on Ubuntu, 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.

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:

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:

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:

  1. 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".
  2. 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:

  1. 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.
  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.
  5. 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:

  1. Type a name for the phone (for example iphone or pixel), or press Enter for phone.
  2. On the phone, open the Signeto app, signed in with the same account as step 2.
  3. 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 setup again.
  4. 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, name is its model (for example Pixel 8), platform is android and attestation is verified (Android Key Attestation).

  5. The app shows the same fingerprint (also on the Gateways tab, under This iPhone, or This phone on Android). If they match, type y and 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:

  1. 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.
  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 the terminal, setup asks:

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

    Type y and 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:

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