Password managers

A key in ZestSSH can keep its password in your password manager instead of in ZestSSH. The key holds only a reference to the item. Each time you connect, ZestSSH asks the password manager’s command line tool for the password, uses it for that connection, and does not keep it. Every host that signs in with that key gets its password this way.

It works for the keys in your personal space and for the keys in a team’s shared vaults. The reference syncs with the key like the rest of it. The password itself is never saved in ZestSSH and never synced.

Supported password managers

Password manager	Tool ZestSSH runs	What the key keeps
1Password	op	A secret reference: op://vault/item/field, or op://vault/item/section/field
Bitwarden	bw	The item’s id. The password is the item’s login password.
KeePassXC	keepassxc-cli	The entry’s path in your database, such as Servers/web-01, and the field that holds the password (Password unless you name another)

The tools run on Windows, macOS and Linux. Phones and tablets have no such tools: see On a phone or tablet.

Before you start

• 1Password: install the 1Password CLI (op), then turn on Integrate with 1Password CLI in 1Password, under Settings, Developer.
• Bitwarden: install the Bitwarden CLI (bw) and sign in to it once in a terminal with bw login. ZestSSH unlocks it with your master password when it needs to. On Windows, use the standalone bw.exe: the npm install gives bw.cmd, which ZestSSH does not run.
• KeePassXC: tell ZestSSH where your database is, in the settings below.

Setting up a tool

Wherever ZestSSH needs a tool (the key’s editor, Add from a password manager, Move to a password manager, or a connection that cannot fetch a password), it says where it found the tool in one line, such as “op found at /usr/local/bin/op”. When the tool is not there, it says so right there, for example “ZestSSH could not find op, 1Password’s command line tool, on this computer.”, and shows:

• Install it: the command that installs the tool on your system, with a copy button, where there is one, and Official page, the tool maker’s own instructions.
• The one step after installing: for 1Password, turning on Integrate with 1Password CLI; for Bitwarden, bw login once in a terminal; for KeePassXC, choosing your database.
• Check again, which looks for the tool once more (“Still not found. Install op, then check again.” when it is still missing), and Choose op.exe… (the tool’s file name on your system), to point ZestSSH at the program yourself. A file that cannot be run is not kept: “That file cannot be run. Choose op.exe.”

What you set up there is the same setting as in Settings.

Settings, Password managers

On a computer, open Settings, then Security, and find Password managers:

• Each tool, with where ZestSSH found it, and Choose to pick the program yourself; after you picked one, Find it goes back to looking for it. A tool that is not found shows the same setup as above.
• KeePassXC database: Choose your .kdbx file. A key file is optional; with one, Opens with the key file alone (no password) is for a database that has no password.
• Forget now: forgets what unlocked Bitwarden or KeePassXC right now. They ask again next time.

None of these settings is secret, and none of them syncs. Set them on each computer.

Where ZestSSH looks for a tool

ZestSSH runs a tool only by a full path it found itself, with its arguments passed one by one, never through a shell. It looks in this order:

1. The path you set under Password managers.
2. The usual install places: WinGet, Scoop and Chocolatey on Windows, and KeePassXC’s own folder; Homebrew and /usr/local/bin on macOS, and inside KeePassXC.app; /usr/bin, /usr/local/bin and Snap on Linux.
3. The folders on your PATH that are full paths. A relative folder such as . is skipped, so a program dropped wherever ZestSSH was started is never run.

On Windows only .exe files are run, because a .cmd or .bat file goes through cmd.exe.

Use a password manager for a key

1. Open Keys and select the key, or make a new one.
2. Under Authentication, choose Password manager.
3. Choose 1Password, Bitwarden or KeePassXC.
4. Use Choose from 1Password (or Bitwarden, or KeePassXC) to pick the item. For Bitwarden, type a search and press Enter: ZestSSH asks Bitwarden only for the items that match. You can also type the reference yourself in Secret reference, Item id or Entry. For KeePassXC, Field names the field when it is not Password.
5. Save the key.

Under the field ZestSSH says “The password stays in 1Password. ZestSSH fetches it each time it connects and never keeps it.” A key set to Password manager cannot be saved without an item: “Choose the item that holds the password.”

ZestSSH refuses a reference it cannot use safely, with “This is not a reference ZestSSH can use.”: a 1Password reference with a query such as ?attribute=, a part that starts with a dash, or a Bitwarden item id that is not in the form 00000000-0000-0000-0000-000000000000. When the picker fills in a 1Password reference, it uses the vault’s and the item’s names where they hold only letters, digits, spaces, dots, dashes and underscores, and their ids where they do not, so that a name with a slash in it can never point at another item.

What happens when you connect

• 1Password: op asks 1Password, which may show its own prompt, such as a fingerprint.
• Bitwarden: the first time after ZestSSH starts or unlocks, Unlock Bitwarden asks for your Master password. ZestSSH hands it to bw in the environment of that one run, never as an argument (other programs on the computer can read those), and keeps only the session bw gives back, in memory, until ZestSSH locks. When an item is not found, ZestSSH runs bw sync once and tries again.
• KeePassXC: Open your KeePassXC database asks for the Database password. ZestSSH hands it to keepassxc-cli on its input each time it reads a password, and keeps it in memory until ZestSSH locks.

When ZestSSH locks, when you sign out, or when you choose Forget now, what unlocked Bitwarden or KeePassXC is forgotten.

A tool gets 120 seconds to answer. A question ZestSSH asks you that nobody answers within two minutes counts as no.

In a team: allow it once per address

Others in a team can change a key and its hosts. Pointed at another item of yours, or at a server of their own, your password manager would hand over a secret for someone else to catch. So the first time a key’s password goes to an address on this device, ZestSSH asks Send a password from 1Password? It shows:

• the item as your password manager names it, not as a synced label claims: its name, where it is (the 1Password vault, or the KeePassXC database) and, for Bitwarden, its user name,
• To the user, host and port the password would go to, such as deploy@web-01.example.com:22.

Choose Allow or Don’t allow. Don’t allow stops the connection: “Not allowed, so the password was not sent.”

ZestSSH asks again when the key’s reference, the user name, the host or the port changes. What you allowed is kept on this device only, in the team’s own database, as hashes that name no item and no host. The newest 500 are kept for each team. Keys in your personal space are only ever changed by you, so they are never asked about.

When the password cannot be fetched

When the tool is not installed, is signed out, cannot find the item, or does not answer in time, 1Password did not give the password says why, and what to do. What it said shows the tool’s own error, with Copy. You can type the password in Or type it this once and choose Connect: it is “Used for this connection only and not kept.” When the tool is not on the computer at all, the same dialog shows the tool’s setup, so it is ready for the next time.

If you said no in the password manager, or cancelled unlocking it, the connection stops. A password manager key never falls back to asking for a password and saving it.

On a phone or tablet

Phones and tablets cannot run these tools. A key that uses a password manager still works there: when you connect, Password from 1Password asks you to type the password, or to fill it from your phone’s password manager. It is used for that connection and not kept, and your phone’s password manager is not offered to save it.

Set such a key up on a computer. On a phone, Password manager is offered only for a key that already uses one.

Add keys and hosts from a password manager

1. Open Keys. On the Saved passwords line, choose From a password manager (or choose New key, then Add from a password manager).
2. Choose the password manager, then tick the items. For Bitwarden, search and press Enter first.
3. Choose Add. The button counts what you ticked, such as Add 3.

Each item becomes a key that keeps only a reference to it: no password is copied into ZestSSH. The key is named after the item. It signs in with the user name in the item’s SSH address, else the item’s own user name, else your user name on this computer.

An item whose address is an SSH one also becomes a host that uses the new key. These count: ssh://web-01.example.com, deploy@web-01.example.com:2222, web-01.example.com:22 and web-01.example.com. A web address such as https://web-01.example.com does not, and neither does a single word with no dot, no user and no port. In the list, an item that will become a host says so, such as “host web-01.example.com:22”.

Afterwards ZestSSH says what it added, such as “Added 3 keys and 2 hosts.”

Added to a team, the keys are shared with it: “They are added to this team: others in it will see the items’ names and vaults.”

Move a saved password into a password manager

For a key in your personal space that keeps its password in ZestSSH, on a computer:

1. Open Keys and select the key.
2. In the key’s details, choose Move to a password manager.
3. Choose the password manager. For 1Password, choose the Vault. For KeePassXC, check the New entry path, which starts as ZestSSH/ and the key’s name. Bitwarden asks to be unlocked.
4. Choose Move.

The password goes into a new item named after the key, with the key’s user name. The key then fetches it from there, and ZestSSH deletes its own copy: “Moved to 1Password. ZestSSH no longer keeps this password.” The password reaches the tool on its input, never as an argument.

Keys in a team’s shared vaults cannot be moved this way: a team’s password copied into someone’s own password manager would be an export.

SSH keys held by 1Password or Bitwarden

1Password and Bitwarden can also keep SSH keys and answer as an SSH agent. To use one of their keys:

1. Open Keys, choose New key, then Connect via ssh-agent.
2. Choose System agent, 1Password or Bitwarden.
3. Tick the keys and choose Add key (or Add n keys).

Such a key shows as “Agent key, 1Password”, under SSH agent on the Keys page. The private key never leaves the password manager. Each device finds that agent itself, since where it listens differs by system and by how the manager was installed.

• On Windows, 1Password and Bitwarden answer on the OpenSSH agent pipe, so the Windows “OpenSSH Authentication Agent” service must be off. Only one of them can answer at a time.
• KeePassXC has no agent of its own: it adds its keys to the system agent. Choose System agent for those.
• When the manager’s agent does not answer: “1Password’s SSH agent did not answer. Turn it on in 1Password’s settings and unlock 1Password, then Refresh.”

Things to know

• The password is never saved. Not in ZestSSH’s database and not in sync. Only the reference is kept, and a reference that arrives by sync and does not read as a valid one is dropped.
• Nothing runs in the background with these keys. The Server Monitor’s background checks and automation (scheduled tasks and the API) never ask anyone anything, so they cannot sign in with a key whose password is in a password manager.
• A test connection from the host editor fetches the password the same way as a connection, and asks the same questions.
• What a tool answers is never logged. Its answer is the password. Its errors are shown so that you can copy them.

Next steps

• Teams overview: how teams and their vaults share hosts and keys.
• Session sharing and moderation: let teammates in the same vault watch a session.
• Setup as code: a setup file names a host’s key by its name, and never carries a password.
• Password authentication: passwords kept in ZestSSH itself.