Skip to content

Use vaultfold in your browser

The vaultfold browser extension fills logins, saves new ones, offers passkeys and one-time codes, and locks your vaults. It keeps no vault, key, seed or password of its own: every request goes to the vaultfold agent on your computer, which decides what leaves.

  • The vaultfold CLI, which installs vaultfold-native-host beside it.
  • A vault with at least one login entry that has a URL (see store and read).
  • Chrome, Edge, Brave or Chromium, or Firefox. Safari needs the desktop app, which does not exist yet, so Safari is not supported.
  • The extension's store listings are not live yet. The registration below allows only published extension ids, so until a listing exists you need a development build. On Firefox a development build carries the published add-on id and works with the registration below; on Chromium browsers the registration allows no extension yet, so a development build needs a hand-written manifest. extension/README.md in the source repository describes both.

The browser starts the host and the host talks to the agent. Nothing listens on a network port.

Terminal window
vaultfold browser install
vaultfold browser status

install writes a per-user manifest for every browser it detects. Pass --browser chrome, chromium, brave, edge or firefox (repeatable) to choose, or --manifest-dir <dir> --kind chromium for another Chromium-family browser such as Arc or Vivaldi. Firefox installed as a Snap needs the system-wide manifest:

Terminal window
sudo vaultfold browser install --browser firefox --system

Snap Chromium and Flatpak browsers cannot reach native hosts, and install says so instead of writing a manifest. vaultfold doctor checks the registration and the host.

The first time the extension connects, the agent asks you to approve it, naming the browser and the extension id. Answer in the dialog, or from a terminal with vaultfold agent approve. An extension that is not a published vaultfold listing needs you to type allow to confirm. Until you approve it the extension can do nothing.

Approval is per browser and per extension id: approving Chrome does not approve Edge. To forget one:

Terminal window
vaultfold browser uninstall --extension <id>

Run that outside an AI agent session; forgetting an extension is a human decision. vaultfold browser uninstall on its own removes the host registration.

Open a login page and click the vaultfold icon in the field, or press Ctrl+Shift+L (Command+Shift+L on a Mac) to fill the best match. If the vault is locked, the extension asks the agent to show its unlock prompt; you never type a passphrase into the browser.

  • vaultfold fills only on a click or the shortcut. Auto-fill on page load is off.
  • It fills only on https pages, plus http on localhost, with a warning.
  • The match is by site, using the public suffix list: an entry for github.com is offered on gist.github.com, but an entry for alice.github.io is not offered on mallory.github.io. An entry's match field narrows this to the exact host, the exact origin, or never.
  • If the form is in a frame from another site, or posts to another site, the menu names both sites and asks before filling.
  • When you submit a new or changed login, the extension offers to save or update it. A generated password is saved as soon as you accept it, tagged unconfirmed, and the prompt after you submit keeps or discards it.
  • Entries in a collection with touch policy always (such as prod) are not served to the browser. Use the CLI for those.

On Chromium browsers and Firefox the extension offers to create and use passkeys. Each one asks you to confirm in an extension prompt that names the site and account, and the key is created and used inside the agent. Choose "Use another passkey or security key" to use the browser's own. Where the extension cannot serve a request, such as a site that requires a hardware attestation, the browser's own passkey prompt appears as if vaultfold were not installed.

Choose "Scan QR code with vaultfold" from the right-click menu while a site shows its two-factor setup code. The extension reads the otpauth:// code, asks which login to attach it to, and sends the seed to the agent. On a two-factor page the menu on the code field offers the current code. The extension never sees the seed again. On the options page you can have the agent put the code on the clipboard after a login fill; it clears after 30 seconds.

Press Alt+Shift+L, or use the popup's lock button, to lock every vault. You can also set, in the [agent.browser] table of your profile.toml (see paths):

[agent.browser]
lock_on_close = "session" # "off", "session" or "lock"
idle_lock_minutes = 0 # lock after this much browser idle time; 0 is off
collections = [] # collections browsers may read; empty means all
save_collection = "" # where the browser saves new logins

lock_on_close = "lock" locks the agent when the last connection from a browser closes. The extension's options page shows idle_lock_minutes read-only.

The extension can read all content of every page it runs on, because it needs to find login forms. On the options page, turn on On-click mode to register no content script at all: nothing runs in a page until you click the toolbar button, press the shortcut, or use a context menu item, and then only in that tab. On-click mode turns off the inline menu, auto-fill, save offers, social login detection and passkeys.

You can also turn off the browser's own offer to save passwords so that two password managers do not both ask. That asks the browser for the optional privacy permission when you click it, and gives it up when you turn the setting off.

  • It never returns a password for an entry other than the one you chose, and never a one-time code seed or a passkey private key.
  • It refuses to run in browsers under automation or remote debugging, and an AI agent session cannot drive it.
  • It serves only login entries and passkeys, never API keys, SSH keys or certificates.

See the threat model for what a compromised browser or extension could still get, and the vaultfold browser reference for every flag.