romanz/trezor-agent: Hardware-Backed SSH, GPG and age Keys
Hardware-based SSH/GPG/age agent
At a glance
- What is it?
- The trezor-agent project moves private key operations onto a Trezor, Jade or OnlyKey device so the key material never reaches the host. Here is what the repository documents, how installation works, and where the design runs into limits.
- Who is it for?
- Adopt trezor-agent if you already own a supported device and want its key material to stay off your workstation for SSH, GPG or age operations. Do not adopt it if you need a purely software agent, want a single binary with no Python dependency, or expect the README to walk you through rollback.
- 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 87 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 29, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What trezor-agent replaces on your workstation
The usual setup keeps a private key in a file on disk and unlocks it with a passphrase whenever ssh, gpg or age needs it. The README describes the alternative plainly: the key is generated and stored on the device and never reaches your computer. The host only asks the device to perform a signing or decryption operation and receives the result.
That changes the threat model rather than eliminating it. A compromised workstation can still ask the device to sign something while you are present, and it can still read anything the agent returns. What it cannot do is copy the private key, because the key was never on the host to begin with. For people who sign git commits, software packages, email or password-store entries, that distinction is the whole point.
The supported hardware list in the README is TREZOR One, TREZOR Model T, Blockstream Jade and OnlyKey. Each has its own agent package, and they share libagent. This is not a general-purpose PKCS#11 provider, and it is not a replacement for a full HSM. It is an agent layer that speaks the protocols Unix tools already expect: ssh-agent, gpg-agent and the age tooling.
How the agent splits work between host and device
The repository layout makes the architecture visible. libagent holds the shared code and is published on PyPI as libagent, currently at 0.16.1. Under it sit subpackages named libagent.age, libagent.device, libagent.gpg, libagent.signify and libagent.ssh. Those names map to the protocols the library supports, and the separate agents in the agents directory are thin wrappers around that shared core.
The split is deliberate: device communication, key derivation and protocol encoding live in libagent, while trezor-agent, jade_agent and onlykey-agent handle the specifics of talking to each vendor's hardware. That is why setup.py lists cryptography, ecdsa, pynacl, mnemonic and bech32 as dependencies. Key derivation from a seed uses mnemonic and bech32, elliptic curve work uses ecdsa and cryptography, and NaCl primitives come from pynacl.
The README points to doc/DESIGN.md for the full design. What the README itself confirms is the direction of data flow: the key is created and held on the device, the host sends a request, the device signs or decrypts, and the host gets the answer. A PIN entry program is handled separately, and doc/README-PINENTRY.md covers configuring one, which tells you the PIN is entered on the host side rather than on the device screen in every configuration.
Installing trezor-agent and running a first SSH login
The README does not inline installation steps. It links to doc/INSTALL.md and says installation instructions are there, so treat that file as the authority for your platform. What the repository does show is the packaging: libagent is on PyPI, and setup.py declares python_requires of 3.8 or later, with platforms listed as POSIX and win32. Windows users have a dedicated document, doc/README-Windows.md.
Once the package is installed, the SSH workflow is documented in doc/README-SSH.md. The shape of it is that you ask the agent to derive a public key for the device, then install that public key on the remote host. The exact invocation lives in that document rather than the top-level README, so copy the command from there instead of guessing at flags.
A minimal illustration of the intended pattern, using the package name the README gives:
pip install trezor-agentAfter installation, the README directs you to doc/README-SSH.md for the agent invocation and common use cases. The same pattern applies to GPG (doc/README-GPG.md) and age (doc/README-age.md). Before running any of them, connect the device and confirm the firmware version supports the operation, since the README attributes SSH login support to TREZOR firmware 1.3.4 and later, and GPG decryption to firmware 1.4.0.
For pass or passage users, the README lists password management among the supported workflows, which means the GPG agent path is what you configure first. Do not expect the top-level README to hold the flags for any of these; it consistently defers to the doc/ files.
Where the design gets in the way
Every operation needs the device present and unlocked. That is the intended trade-off, but it has practical consequences the README does not discuss. A cron job, a CI runner or a remote session that needs to sign something cannot do so unattended, because there is no key on the host to fall back on. If your workflow assumes a background agent holding an unlocked key, this is the wrong tool.
The supported device list is narrow and explicit. TREZOR One, TREZOR Model T, Blockstream Jade and OnlyKey. A Ledger or a generic smart card is not covered by the README, and no amount of configuration will change that.
Firmware version gates are another constraint. The README ties SSH login to TREZOR firmware 1.3.4 and GPG decryption to 1.4.0, which means older devices in a drawer may simply not be able to do the job. The README does not document rollback if a device is lost or a firmware update changes behaviour, and it does not describe what happens when an agent process is killed mid-operation. Those gaps matter more than usual here, because the recovery path involves a seed phrase rather than a key file you can restore from backup.
How this differs from gpg-agent with a smart card
The closest comparison is GnuPG's own smart card support. That approach uses OpenPGP card hardware and gpg-agent as the front end, and the card holds the key. The difference is scope and packaging. trezor-agent covers SSH and age in addition to GPG, and it works with consumer hardware wallets rather than OpenPGP cards, so the device you already own for storing cryptocurrency can double as a signing device.
The cost of that breadth is a Python dependency chain. setup.py pulls in cryptography, ecdsa, pynacl, mnemonic, bech32, python-daemon, ConfigArgParse and more, and the package targets Python 3.8 and above. A pure smart card setup leans on software already present on most Linux systems. If your environment cannot install Python packages or you want the smallest possible dependency surface, the smart card route is the more conservative choice.
A second difference is protocol coverage. libagent ships a signify subpackage alongside ssh, gpg and age, which is a wider protocol set than OpenPGP cards offer. If you only ever need GPG, that breadth buys you nothing and costs you the extra dependencies.
Maintenance, releases and the LGPL-3.0 licence
The repository is not archived, and the last push was on 2026-07-04. Releases are split between the library and the tooling: libagent 0.16.1 landed on 2026-03-01, libagent 0.16.0 on 2026-02-21, and v0.15.0 on 2024-09-06. The gap between v0.15.0 and the 0.16.x line is roughly eighteen months, so the cadence is not fast, and the version numbering suggests the library and the agent packages move on separate tracks. Check which package your install actually pulls before assuming a version number applies to the agent you run.
The licence is LGPL-3.0, which setup.py also records in its classifier as GNU Lesser General Public License v3 (LGPLv3). That is a copyleft licence with a linking exception, and it is more permissive for proprietary use than the GPL but not as permissive as MIT or Apache-2.0. If you plan to embed libagent in a closed product, the terms around modified library code and relinking obligations are the part to read. This is a description of the licence, not legal advice; talk to someone qualified before shipping.
The upgrade path is the practical question. Because the agents depend on libagent, a library bump can change agent behaviour, and the repository's release.sh and .bumpversion.cfg indicate versioning is scripted rather than manual. Pin your installed versions and read the release notes before upgrading, since the README does not describe a compatibility matrix between libagent versions and agent versions.
Editorial conclusion
Adopt trezor-agent if you already own a supported device and want its key material to stay off your workstation for SSH, GPG or age operations. Do not adopt it if you need a purely software agent, want a single binary with no Python dependency, or expect the README to walk you through rollback. Before committing, read doc/INSTALL.md for your platform, confirm your firmware exposes the signing operations the agent needs, and check the AGENTS.md or doc/DESIGN.md description of how the device is driven, because the top-level README does not cover failure recovery.
Frequently asked questions
Which hardware devices does trezor-agent support?
The README lists TREZOR One, TREZOR Model T, Blockstream Jade and OnlyKey. Each has its own agent package, with libagent providing the shared code.
Does the private key ever reach my computer when using trezor-agent?
According to the README, the key is generated and stored on the device and never reaches your computer. The host sends operations to the device and receives the signed or decrypted result.
What firmware does my Trezor need for SSH and GPG with trezor-agent?
The README attributes SSH login support to TREZOR firmware 1.3.4 and GPG signing and decryption support to later firmware releases, including 1.4.0 for decryption. Check your device's firmware version before configuring the agent.
What licence does trezor-agent use?
The repository is licensed under LGPL-3.0, and setup.py records it as GNU Lesser General Public License v3 (LGPLv3).
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/romanz-trezor-agent)