An agent logs in to a website with agent-browser. nodkey is its credential plugin: after your tap on the phone, the plugin gives agent-browser one login from the shared Bitwarden collection. agent-browser fills the form. The password is not in the agent's commands or in agent-browser's normal output.
Tested with agent-browser 0.38.1, on 2026-11-13. Another version may speak another protocol. Use 0.38.1, or test the new version first (DESIGN.md section 21.10).
What the agent can still see: a filled field, if it reads it; the session after the login; and a TOTP code, which it fills itself (THREAT-MODEL.md T48).
- The broker hands out website logins: setup.md, "Website logins: a
shared collection". The
rule of the items needs
preapprove = true. - nodkey is installed on the agent machine, and
nodkey doctorshows no problem. - agent-browser 0.38.1 is installed on the agent machine.
As the user of the agent, put this into ~/.agent-browser/config.json.
If the file has other settings, add only the plugins entry.
{
"plugins": [
{
"name": "nodkey",
"command": "/usr/local/bin/nodkey",
"args": ["agent-browser-plugin"],
"capabilities": ["credential.read", "command.run"]
}
]
}Give the full path of nodkey (command -v nodkey shows it). Put
agent-browser-plugin into args: agent-browser does not split
command at spaces. Check it:
agent-browser plugin show nodkeyEach login takes three steps. Use the page of the login form for
--url, the same in each step.
-
Find the item ID. The list needs no tap.
agent-browser plugin run nodkey nodkey.list --payload '{"url":"https://example.com/sign-in"}'It prints the ID, the name and the username of each login for the page, and never a password.
-
Ask for the tap. This waits until you tap Approve on the phone, as long as any other nodkey request:
nodkey preapprove --login 11111111-1111-1111-1111-111111111111 --url https://example.com/sign-in
-
Within 60 seconds after the tap, log in:
agent-browser auth login example --credential-provider nodkey --item 11111111-1111-1111-1111-111111111111 --url https://example.com/sign-in
It prints
Logged in as 'example'. The tap allows this one login; the next login needs a new tap.
Why the tap comes first: agent-browser waits only 15 seconds for a plugin, and a tap often takes longer. The plugin itself never asks for a tap.
When the login form is already open, after some clicks, add
--no-navigate. agent-browser then checks that the open page has the
origin of --url.
When the site asks for a code after the password, get it within 2 minutes after the login:
agent-browser plugin run nodkey nodkey.totp --payload '{"itemRef":"11111111-1111-1111-1111-111111111111","url":"https://example.com/sign-in"}'It prints the code, and the agent fills it. The broker makes the code; the seed never leaves it. You get one code for each login.
| what you see | why | what to do |
|---|---|---|
Plugin 'nodkey' returned success=false after auth login |
agent-browser does not show the reason. Most often: no tap first, or more than 60 seconds since the tap | Run nodkey preapprove --login again, then auth login at once. The broker's audit log has the cause; no_tap means no tap |
Failed to start plugin 'nodkey' |
the command is not a path to nodkey, or the subcommand is in command |
Fix step 1 |
nodkey: the item is not an item ID |
--item is a name |
Use the ID from nodkey.list |
nodkey: the request has no page URL |
no --url |
Give --url with the page of the login |
nodkey: the page URL: ... not https |
the page is http |
nodkey hands out logins only for https pages |
nodkey: totp: denied |
no login in the last 2 minutes, or the code was already given | Log in again, then ask for the code |
A Google Chrome that an agent drives offers to save a filled password in
Chrome's own password manager ("Save password?"). The offer is outside
the page, so the agent does not see it. But a person at the screen can
click Save, and with a lasting profile the password then stays on the
disk of the agent machine. The command line flag
--disable-save-password-bubble no longer works.
Make one Chrome profile for agents, with saving turned off.
agent-browser copies a named profile to a new temporary folder for each
session, so every session starts from it. Make it in Chrome itself:
agent-browser finds profiles by their names in Chrome's Local State
file, and a folder made by hand is not found.
These steps are not yet tested from start to end. A profile with the two settings of step 7 is tested: Chrome 153 shows no prompt with it.
Once, on the agent machine, as the user of the agent:
- In Chrome: the profile menu, then Add, then Continue without an
account. Name the profile
agents. - In the window of that profile, open
chrome://password-manager/settings. Turn off Offer to save passwords and Sign in automatically. - Open
chrome://settings/addresses. Turn off saving and filling of addresses. - Open
chrome://settings/payments. Turn off saving and filling of payment methods. - Close the window. Do not use this profile by hand, do not sign in to Google in it, and do not add extensions to it: every agent session gets a copy of it.
- In
~/.agent-browser/config.json, add"profile": "agents". - Check: the
Preferencesfile in the profile's folder has"credentials_enable_service": falseand"profile": {"password_manager_enabled": false}. Then do a test login (section 2): Chrome must show no "Save password?" prompt.
Never unlock your own vault in this browser, or in any browser or app that an agent can drive (THREAT-MODEL.md T32 and T46).