Why this matters
Your passwords are the keys to your email, your money, and your identity. Lose control of them and you lose control of everything they unlock.
A mainstream password manager like 1Password or Bitwarden is a good choice. Each one encrypts your vault so that even the company running it cannot read your passwords. For most people, picking one of those and turning on a passkey is a sound decision, and far better than reusing one password across every site.
This guide builds something different, for people who would rather hold their own keys. Your passwords stay as scrambled files on your own computer, and they sync to no one unless you choose where. The secret that unscrambles them sits sealed inside a small device you carry, where no software can read it out and no copy can be made. To open your passwords, a person needs the physical key in their hand and the PIN in their head.
Three things change as a result. You stop depending on a company’s servers, its staff, and the laws of the country it operates in. The master secret stops being a passphrase that can be phished or guessed, and becomes an object a thief has to physically take. And an AI agent working on your machine cannot drain the vault while you are away, because each unlock waits for a finger on the key.
Three small tools do the work. gopass is the password manager, storing each password in its own scrambled file. GPG is the lock and the maths behind the scrambling. The YubiKey is the physical key that holds the unscrambling secret, which never leaves the device.
You give up the polished app and one-click browser autofill of a mainstream manager, and you become your own backup. In return, no company holds your passwords, the key to them cannot be copied, and a stolen laptop stays shut.
This suits someone comfortable pasting commands into a terminal and reading what comes back, or a confident person setting it up for a less technical relative. If you would rather not touch a terminal at all, a mainstream manager with a passkey is a fair choice.
How this compares
| A mainstream manager | This setup | |
|---|---|---|
| where the vault lives | the company’s servers, synced to you | only your own machine, synced where you choose |
| who you trust | the company, its staff, its country’s laws | yourself |
| the master secret | a passphrase you type | a secret sealed in a chip, never typed in full |
| if the computer is infected | the unlocked vault can be read | the key’s secret stays inside the key |
| if the secret is phished | possible, it is something you type | nothing to phish, the key must be present |
| everyday autofill | built into the app and the browser | copy and paste, no autofill |
| an AI agent running wild | reads whatever sits unlocked | hits a wall, each unlock needs a touch |
| cost | a monthly or yearly fee, or free | two security keys, bought once |
| who it suits | almost everyone | people who want to hold their own keys |
What to buy
One thing to buy, plus a couple of items you may already have.
YubiKey 5C NFC
The physical key. Get the 5 Series specifically, because it is the line that can hold a GPG key. Do not buy the Security Key Series or the Bio key, as neither can do this job.
Buy two: one to carry, one as a backup. The key cannot be copied later, so a single key is a single way to get permanently locked out.
The 5C NFC fits modern USB-C laptops and works with phones. If a machine you use is older USB-A, make one of them a 5 NFC instead.
Two USB sticks
Small drives to hold an encrypted backup of your master key. Keep them in two different places, for example one at home and one elsewhere.
A spare USB stick
Used once to create your key on a clean, offline system called Tails. A nicety for the security-minded, not a requirement. Explained at the end of the setup.
Buy YubiKeys from Yubico directly or a well-known retailer, never second hand. A used security key could have been tampered with.
NFC lets you tap the key against a phone instead of plugging it in, for signing into apps and reading two-factor codes on a phone. On your laptop you use the plug, so NFC only matters if you later want to use the same key with a phone.
Why a security key, and not a USB stick
You may already own USB memory sticks, so why buy a security key to hold the secret? It comes down to one thing: whether the key can be copied.
On a USB stick, the unlocking secret is an ordinary file. Every time you use it, the computer reads that file into its memory to do the work. So anything harmful on the computer can read it while the stick is plugged in, and anyone who gets a moment alone with the stick can copy the file without leaving a trace. You would never know a copy had been made.
A security key is built the other way around. The secret is sealed inside a chip and can never be read out. The unlocking happens inside the key itself, so the secret never reaches the computer. Steal the key and you still face the PIN, and a few wrong guesses lock the chip. Steal a stick and the only thing in the way is the passphrase, which can be guessed at forever on another machine.
| Plain USB stick | Security key | |
|---|---|---|
| the secret | a file that can be copied | sealed in a chip, never copyable |
| if the computer is infected | can be taken from memory | stays inside the key |
| if it is lost or stolen | passphrase guessed offline, no limit | locks after a few wrong PINs |
| stops an AI agent running wild | no, nothing to tap | yes, each use needs a touch |
A hardware-encrypted stick with its own PIN pad, such as an Apricorn Aegis or an IronKey, sits in between. It resists a thief who finds it, but once you unlock it and the computer reads the key, an infected computer can still take it. Only the sealed chip of a security key keeps the secret out of the computer entirely.
It does not have to be a YubiKey. Any key works as long as it carries the OpenPGP feature this setup relies on. Nitrokey, which is open source and made in Germany, and OnlyKey both qualify. Many cheap keys handle only website sign-in and cannot hold this kind of key, the same limit as the YubiKey Bio and Security Key lines.
How it stays safe, and stays usable
Security people talk about three factors: something you know, something you have, and something you are. Good security uses more than one. Convenience comes from not having to prove all of them every single minute.
In this setup, your face or fingerprint unlocks the computer, the thing you are. The YubiKey in the port is the thing you have. A short PIN proves it is you using the key, the thing you know. The convenience dial is a timer: once you have proven yourself, the vault stays open for a set number of minutes before it asks again.
You will set two timers during setup. The touch window means one tap on the key covers a short burst of activity instead of a tap per password. The PIN window means you type your PIN once and then work quietly for, say, ten minutes. Slide them shorter for more safety, longer for more comfort.
Unlock the laptop with your face. The first time you open a password, tap the key once and type the PIN once. After that, a morning of work passes with almost no friction, while an unattended or stolen machine stays firmly shut.
Set it up, step by step
Every command below can be copied and pasted. After each one, the guide tells you what you should see. If a step asks a question in the black window, the guide says what to answer.
The key-creation steps, 4 to 6, are the important ones. If you are helping a less technical relative, sit with them for those. Everything is recoverable except losing your master key with no backup, which is exactly what step 4 prevents.
Open the terminal and install four programs
Click Start, type Terminal, and open it. Paste these lines one at a time and press Enter. Windows may ask permission; say yes.
# the password manager and the lock it relies on
winget install Git.Git
winget install GnuPG.Gpg4win
winget install gopass.gopass Then install the small tool that configures the YubiKey. Download YubiKey Manager from yubico.com and install it. It adds a command called `ykman` that you will use in step 6.
Close the terminal, open a fresh one, and type `gopass —version`. It should print a version number rather than an error.
Insert your first YubiKey and check it is seen
Put one YubiKey into a USB port. Run:
gpg --card-status
This should print a block of details about the card. If instead it says no card is found, see If something breaks before continuing.
Replace the key's factory PINs
Every new YubiKey ships with the same well-known PINs, so change them before anything else. There are two: a normal PIN for daily use, and an Admin PIN for settings.
ykman openpgp access change-pin ykman openpgp access change-admin-pin
When asked for the current values, the factory PIN is `123456` and the factory Admin PIN is `12345678`. Choose new ones and write them in a safe place that is not on the computer.
Type the wrong PIN too many times and the key locks itself as a theft defence. Get these right and store them somewhere physical.
Generate your encryption key on the computer
Run the command below. It asks a short series of questions.
gpg --full-generate-key
- Kind of key: choose RSA and RSA, which is the default.
- Size: type 4096.
- Expiry: 0 for no expiry is fine for home use.
- Name and email: use your own, as a label.
- Passphrase: a long one you can remember. This protects the backup you make next.
You created a private key. Right now it lives on the computer. In the next two steps you back it up, then move the working part onto the YubiKey so the computer no longer holds it.
Save the key to your USB sticks
First find your key’s ID:
gpg --list-secret-keys --keyid-format=long
Look for the long code after `sec rsa4096/`. That is your `KEY_ID`. In the three lines below, replace `KEY_ID` with it.
gpg --export-secret-keys --armor KEY_ID > master-key.asc gpg --gen-revoke KEY_ID > revocation.asc gpg --export --armor KEY_ID > public-key.asc
Copy all three files onto both USB sticks. The `master-key.asc` file is the one that can rebuild everything, the `revocation.asc` file lets you cancel the key if it is ever stolen, and `public-key.asc` is harmless and shareable.
Without this backup, two dead or lost YubiKeys means every password is gone forever. Do not continue until both sticks hold these files. Store them in two separate places.
Hand the working key to your hardware
Open the key editor:
gpg --edit-key KEY_ID
You are now at a `gpg>` prompt. Type these one at a time:
gpg> key 1 # selects the encryption part gpg> keytocard # choose slot 2, Encryption gpg> save
To put the same key on your second YubiKey, plug it in, import your backup, and repeat:
gpg --import master-key.asc
gpg --edit-key KEY_ID
# then: key 1 → keytocard → save, as above Run `gpg —card-status` again. Under the encryption slot it should now list your key fingerprint instead of being blank.
Require a tap, but not on every action
This makes the key blink and ask for a physical touch when it unlocks something, with one touch covering a fifteen-second burst.
ykman openpgp keys set-touch enc cached ykman openpgp keys set-touch sig cached ykman openpgp keys set-touch aut cached
It will ask for the Admin PIN from step 3. Want maximum safety? Use `on` instead of `cached` to require a tap every single time. Want maximum comfort? Use `off` to skip touches entirely. Remember to set this on both keys.
Choose how often it asks for your PIN
Open the settings file for the unlocking service:
notepad $env:APPDATA\gnupg\gpg-agent.conf
If Notepad offers to create the file, say yes. Paste in these two lines and save:
default-cache-ttl 600 max-cache-ttl 7200
The first number keeps the vault open for ten minutes after each use. The second is the hard limit of two hours before it always asks again. Both are in seconds, so adjust to taste. Then apply it:
gpgconf --reload gpg-agent
Point gopass at your new key
gopass setup
When it lists keys, choose the one you just made. If it asks about a git remote for syncing, you can skip it for now and add one later in the backup section.
You now have a working vault. Test it by saving your first password in the next section.
Optional: the extra-careful route
The steps above create your key on your everyday Windows machine, which is fine for most people. If you want the strongest version, create the key on a clean computer that has never touched the internet, so nothing could possibly copy it as it is born.
The easy way to get such a machine is Tails, a small operating system you run from a USB stick. It loads into memory, writes nothing to disk, and forgets everything when you shut down. You would boot Tails with the network off, run steps 4 to 6 there, save the backup, move the keys to your YubiKeys, then shut down. Your normal Windows is untouched and no copy of the master key is ever left behind. This route is optional, and suited to a key you intend to rely on for years.
Everyday use
A handful of commands cover almost everything. The first time each day, expect a PIN prompt and a tap on the key. After that, the window keeps things quiet.
Save a password you already have
It asks for the password and stores it under that name.
Create a strong new one
Makes and saves a random twenty-character password.
Copy a password to paste
Puts it on the clipboard and wipes it after a short while.
Find something
Lists everything. Use `gopass find github` to search.
Two-factor codes
If you saved a 2FA secret, this prints the rolling code.
Sync across devices
Pushes and pulls changes if you set up a remote.
Backing up your store
Your passwords are already scrambled files, so backing them up is safe even to places you do not fully trust. gopass keeps them in a folder it can track with git, which means every copy is a full backup with history.
If you run a home server such as a Synology, the best home for the backup is a private git repository on it, reached over your own private network. Point gopass at it once, then `gopass sync` keeps it current.
The scrambled files back up freely to your server and its own backups. The master key from step 5 stays offline on your two USB sticks. The files are useless to a thief without the key, and the key is useless without the files. Keep both, in different ways.
Do not export your passwords to a plain readable file “for safekeeping”. The entire design depends on them staying scrambled. Test your backup now and then by restoring it on a clean machine and confirming a key can open it.
Using it with Claude Code or another AI agent
An AI coding agent often needs a secret, such as a key for a service, to do its job. The danger is that an agent reads everything in its terminal, so a secret printed on screen ends up in its memory and its saved logs. The rule is simple: the secret value must never be printed.
Inject, never print
Instead of showing the agent a secret, hand it straight to the program that needs it. gopass does this with one command that runs a tool with the secret loaded into its environment, where it stays invisible.
# the secret goes into the deploy process, not onto the screen
gopass env work/deploy-key -- npm run deploy The agent sees the command and the normal output of the deploy, but never the secret itself. In your instructions to the agent, always refer to a secret by its name in the store, never by its value.
Fence it off
Tell the agent which commands it may run. In your project’s `.claude/settings.json`, allow the safe injecting command and block the ones that would print a secret outright.
{
"permissions": {
"allow": ["Bash(gopass env:*)"],
"deny": ["Bash(gopass show:*)", "Bash(gopass cat:*)"]
}
} The hardware brake
This is where the YubiKey touch policy earns its place. With touch set to `on` or `cached`, the agent physically cannot drain your whole store while you are away, because each unlock needs a finger physically on the key. A runaway loop hits a wall it cannot pass.
Batch the agent’s secret-using work into one window so you tap once and let it run, rather than fighting a prompt every few seconds across a long session.
If you keep redacted logs of agent sessions, add your secret names to the scrub list as a backstop. The no-print habit should mean nothing leaks, but a second net costs nothing.
If something breaks
| Symptom | What to try |
|---|---|
| card not found | Unplug and replug the key. If Windows still misses it, close other apps that talk to smart cards, then run `gpg —card-status` again. A reboot clears most first-time conflicts. |
| gopass: gpg not found | Close every terminal and open a fresh one so it picks up the new programs. If it persists, reinstall Gpg4win and reopen the terminal. |
| PIN keeps being asked | Normal after the window expires. Shorten or lengthen it by editing the two numbers in step 8. |
| key blinks, nothing happens | It is waiting for a touch. Tap the metal contact within fifteen seconds. |
| lost or broken YubiKey | Use your second key as normal. Then provision a replacement from the backup in step 5, and use your `revocation.asc` to cancel the lost key if you fear it was stolen. |
| forgot the PIN | The Admin PIN can reset the normal PIN. Lose both and you reset the key and re-provision it from your backup. |
Quick reference
| Command | Does |
|---|---|
| gopass insert NAME | save a password by hand |
| gopass generate NAME 20 | make and save a strong one |
| gopass -c NAME | copy to clipboard |
| gopass ls | list everything |
| gopass find TEXT | search by name |
| gopass otp NAME | print a 2FA code |
| gopass sync | back up and pull changes |
| gopass env NAME — CMD | run a tool with a secret, unseen |
| gpg —card-status | check the YubiKey |
| ykman openpgp keys set-touch enc cached | change the touch rule |
Common questions
The questions people ask before they decide whether this setup is worth the effort.
Isn't 1Password or Bitwarden already secure?
Yes. They are well built, and they encrypt your vault so the company cannot read it. The difference is where your vault lives and what the master key is. With them, your vault sits on a company's servers and the key is a passphrase you type. Here, the vault never leaves your machine and the key is sealed in hardware that cannot be copied or phished.
Do I need to be technical to use this?
You need to be comfortable pasting commands into a terminal and reading what comes back. Each command in the guide tells you what to expect. If that is not you, a confident friend or relative can set it up alongside you. If you would rather not touch a terminal at all, a mainstream manager with a passkey is the better fit.
What happens if I lose my YubiKey?
Use your second key, which is why you buy two. Then provision a replacement from the offline backup you made in step 5, and use your revocation.asc file to cancel the lost key if you fear it was stolen.
What if I lose both keys?
As long as you kept the master-key backup on your two USB sticks, you restore it onto a new key and carry on. Lose both keys and the backup, and the passwords are gone for good. That is the price of having no company able to reset it for you, and the reason step 5 insists on the backup.
Can I use it on my phone, or on a Mac?
This guide is written for a Windows computer. The same key can tap a phone over NFC for app sign-ins and two-factor codes. The tools also run on macOS and Linux, with slightly different commands. A full phone vault is a separate setup, not covered here.
Can I move my passwords over from my current manager?
Yes. Export your passwords from your current manager, import the entries into gopass, then delete the export. Do not leave a plain, readable export sitting on your disk afterwards.
How do I fill passwords in my browser?
gopass copies a password to the clipboard and wipes it after a short while, so you paste it into the login box. There is no built-in browser autofill like the big managers have. This is the main day-to-day trade.
What does it cost, and why two keys?
The software is free. The cost is two security keys, bought once. One key is a single point of failure, because a key cannot be copied. The second is your spare, and the reason a lost key is an inconvenience rather than a disaster.
Is it safe to back up my password files to a server or the cloud?
Yes. Every entry is an encrypted file, useless to anyone without your key. Back the files up wherever you like. Keep the master key itself offline on your USB sticks, separate from the files.