trezor-agent: Putting SSH, GPG and age Keys on Hardware You Can Unplug
Hardware-based SSH/GPG/age agent
At a glance
- What is it?
- romanz/trezor-agent moves private key material off the workstation and onto a Trezor, Jade or OnlyKey. It is a thin Python agent layer over a real hardware boundary, and the boundary is the whole point.
- Who is it for?
- Adopt trezor-agent if your threat model is a compromised workstation and you already own a supported device, because the key never reaches the host and signing happens on the hardware. Do not adopt it if you need unattended signing, CI keys, or a device you can script without a human tap, since the physical confirmation step is the mechanism, not an inconvenience to route around.
- Can I use it commercially?
- Yes, with conditions. LGPL-3.0 is a weak copyleft licence: you can use it inside commercial and closed-source software, but if you distribute changes to its own files, you must publish those changes under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 73 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is the passphrase-protected key sitting on disk
The README states the design goal directly: instead of keeping your key on your computer and decrypting it with a passphrase when you want to use it, the key is generated and stored on the device and never reaches your computer. That single sentence separates this project from the usual agent setup. With ssh-agent or gpg-agent alone, the private key exists as a file, protected by a passphrase that you type into a machine that may already be running hostile code. Once the passphrase is entered, the key is in memory and the agent will sign whatever it is asked to sign. The passphrase protects the key at rest, not the act of using it.
The audience is narrower than the README's list of use cases suggests. It is for people who already own a Trezor One, a Trezor Model T, a Blockstream Jade or an OnlyKey, and who want that device to become their signing identity for SSH logins, GPG operations and age encryption. The README names signing emails, git commits and software packages, password management through pass and passage, and authenticating web tunnels and file transfers. Those are all cases where a human is present to approve the operation. If nobody is present, the model does not fit.
What actually runs: libagent plus one agent per device family
The repository is not a single program. The README lists libagent as a shared library published on PyPI, then separate agents built on top of it: trezor-agent for Trezor devices, onlykey-agent for OnlyKey, and jade_agent, which the README points at Blockstream's own Jade repository rather than this one. That split matters when you install. The library carries the shared logic for talking to a device and exposing an agent interface; each agent package carries the device-specific protocol work.
The data flow implied by the design is consistent across protocols. Your SSH client or GPG or age talks to the agent over the standard agent interface, the agent forwards the signing or decryption request to the hardware, the device prompts you and performs the operation internally, and only the result travels back. The private key is never serialized to the host. The README links a design document at doc/DESIGN.md for the details, and that document is where you should look before trusting the boundary, because the security argument rests entirely on what crosses the USB link and what does not.
Installation is per-device, and the docs are split by protocol
The README does not inline install commands. It points to doc/INSTALL.md for installation, doc/README-SSH.md for SSH, doc/README-GPG.md for GPG, doc/README-age.md for age, doc/README-PINENTRY.md for the Trezor-style PIN entry configuration, and doc/README-Windows.md for Windows. Treat those files as the source of truth rather than any command copied from a blog post, because the package names differ by device. On PyPI the README names libagent, trezor-agent and onlykey-agent as separate distributions, so installing trezor-agent does not give you the OnlyKey path, and the Jade agent lives in a different repository entirely.
The PIN entry document is the one people skip and then hit. A hardware device that requires a PIN to unlock needs a program to collect that PIN, and the README treats this as its own configuration topic. If you install the agent and the device keeps asking for confirmation you cannot supply, the PIN entry setup is the first thing to check. Beyond that, this review cannot confirm specific flags or environment variables, because the README does not show them and the linked documents were not available here.
The human tap is the security property and the operational limit
Every operation that touches the key requires the device to be present and, in practice, approved by a person. That is exactly why the passphrase problem disappears: there is no secret on the host to steal, and no unattended signing to abuse. It is also why this tool is wrong for a large class of automation. A CI pipeline that signs release artifacts, a backup job that encrypts files on a schedule, a server that needs to decrypt something at boot: none of these can wait for someone to press a button on a USB device. If you need a machine identity that works without a human, this is the wrong tool, and no amount of configuration changes that, because the confirmation step is the mechanism.
There is a second, quieter cost. The README lists four supported devices and three agent packages, with the Jade agent maintained outside this repository. Support therefore tracks firmware and upstream projects you do not control. A device that is supported today can fall behind if its firmware changes or if the third-party agent stops being updated. The README's own release history shows an uneven cadence: v0.15.0 in September 2024, then libagent 0.16.0 and 0.16.1 in early 2026. That is not a criticism of the maintainers, but it does mean you should check the last commit date and the release notes for your device before standardizing on it.
Compared with a software agent plus a passphrase
The obvious alternative is ssh-agent or gpg-agent with a passphrase-protected key on disk, optionally backed by a FIDO2 security key for SSH. The difference is where the secret lives and when it is exposed. A software agent decrypts the key into process memory once and then signs on demand, which is fast and fully scriptable. trezor-agent keeps the key on the device and produces signatures only after a physical confirmation, which is slower and not scriptable. The trade is deliberate: you give up automation and latency in exchange for removing the key from the host entirely.
A second alternative is a smartcard or PGP card, which also stores keys off-host and also requires a PIN. The practical difference is the interface and the ecosystem. The README's approach reuses the standard agent protocols, so an SSH client or GPG does not need to know a Trezor is involved; it sees an agent. That is a smaller integration surface than a card reader stack, but it also means the security properties depend on the agent implementation and the device firmware rather than on a card standard with its own long history.
Licence, maintenance and what to verify before you commit
The project is licensed under LGPL-3.0. That is a copyleft licence with a linking exception aimed at libraries, and libagent is published as a library that other agents build on. If you are considering embedding it in a product rather than using it as an end user tool, the licence terms are the thing to read first, and this is a case where a lawyer should read them rather than a review. Nothing here is legal advice.
On maintenance, the repository is not archived and shows a push in July 2026, with the most recent releases being libagent 0.16.1 in March 2026 and 0.16.0 in February 2026, following v0.15.0 in September 2024. The gap between v0.15.0 and the 0.16.x line is worth noting if you depend on a specific device, because fixes may land in libagent and require a matching agent release. Upgrading means tracking two packages, not one, and for Jade it means tracking a third project outside this repository. Check the release notes for your device and confirm the agent version you install matches the libagent version it expects before you upgrade a working setup.
Who this is for, stated plainly
Use trezor-agent if you own a supported device, you sign and authenticate interactively, and you want the private key to never exist on your laptop. The README's examples, signing commits and emails, managing passwords through pass, authenticating tunnels, all fit that shape. Skip it if your keys need to work while you are asleep, or if you are looking for a general-purpose secrets manager rather than a signing agent. The project does one thing: it turns a hardware wallet into an agent that holds your keys. That narrowness is why it works, and it is also the boundary you should test against your own workflow before you move a key onto a device.
Editorial conclusion
Adopt trezor-agent if your threat model is a compromised workstation and you already own a supported device, because the key never reaches the host and signing happens on the hardware. Do not adopt it if you need unattended signing, CI keys, or a device you can script without a human tap, since the physical confirmation step is the mechanism, not an inconvenience to route around. Before committing, verify three things against the repository: that your exact device model appears in the supported list, that the PIN entry program described in doc/README-PINENTRY.md is configured, and that the agent you install matches the device (trezor-agent, onlykey-agent, or the Jade agent maintained in Blockstream's own repository).
Community notes