Manual

Getting started

Bossanova is a digital safe that stores text and images encrypted on your computer. You must sign in to the app, including with a free account. Account sign-in is separate from the master password that opens your vault.

If Google says the account already exists on your device, return here and choose “Continue with email” using the same Google email address. If you have already registered with Bossanova using that email address, this signs you in to your existing account. You can also try another browser.

The current installer is for Windows 10/11 x64. Windows 32-bit and native ARM64 installers are not available. Installing or updating WebView2 may require an internet connection.

1. Download and install the installer for your operating system from the download page.
2. Complete installation, then open Bossanova from the Start menu. Windows 10/11 x64 is supported. The installer sets up WebView2 if it is missing. Contact your administrator if installation is blocked on a work computer.
3. On the app’s sign-in screen, sign up or sign in with Google, Apple, or email, then approve this device. A free account lets you save ten items.
4. Create a vault on the first screen and choose a long master password; keep it somewhere safe. To transfer an existing vault, choose “Import from another device” before creating one. A backup file uses the separate “Restore from backup” action.
5. Save a harmless example first. Try searching, viewing and copying it, then add real information and make an external backup.

The developer cannot recover a forgotten master password. Google, Apple, or email sign-in cannot reset it.

Storing and organizing data

A Bossanova vault is organized as folders → groups → data. A data item is one name with one value (text or an image); a group bundles related data items. A folder holds groups and ungrouped data items, and the vault is the set of folders. For example, an “API keys” folder can hold a “bossanova” group containing “OpenAI API key” and “Renewal date”. Each text or image data item counts as one.

Folders organize groups and data. Drag the handles to reorder. When deleting a folder you choose whether to keep or delete its contents.

Toggle AI access with the star icon. Hover to see its name; a pale green background means it is on; the icon stays outlined. The same button appears in lists, details, item editing and group creation/editing. All items and folders share one sort menu: Default, Newest, Oldest, Most used, Least used, Name A–Z and Name Z–A. The last choice is saved in this vault and restored next time. Names follow the display language, with 2 before 10. Choose Default to drag items into your own order inside a folder; other sorts preserve that order.

Settings → AI → AI access has “Automatically allow AI access for new data”, off by default. It applies to new text and images, data added when creating or editing groups, templates, and .env imports. You can override each AI icon before saving. Existing data, non-secret sharing and execution approvals are unchanged. The choice is saved in this vault.

1. Create folders with “Add and manage folders” in the left menu and drag the handles to reorder them.
2. Use “Add data” to enter a name, a type (text or image; older items keep their password, number or date type) and a value. Without a group, the data item sits directly in the folder. Images (PNG, JPEG, GIF, WebP, BMP, ICO, TIFF, TGA, PNM, QOI, HDR, up to 10MiB) are dropped or pasted in. Clicking a data item opens its detail, and “Edit” opens the edit dialog with the stored value filled in (use “Show value” to check it).
3. Drop a data item onto another to create a group, and drop a group onto a group to merge them. Handles reorder anything.
4. Use a data item’s view or copy action when you need its value. The destination app or document can see pasted values, so check where you paste.
5. Plus and Pro include templates for common groups. You still enter the actual values yourself.

Put secrets only in value inputs. Data names, descriptions, group and folder names may be shared with AI depending on your settings.

Importing a .env file

You can move the secrets in a project’s .env file into the vault in one step. Press “Import .env” at the bottom left of the “New group” dialog, or drop the file onto the vault page. One file becomes one group, and each variable becomes one data item named after the variable. Items remain secret; AI access follows “Automatically allow AI access for new data”.

1. The preview shows variable names only; values never appear on screen. Choose a group name (for example, web .env) and check the list.
2. Values that are probably not secrets, such as ports or public URLs, are marked as “Not a secret” candidates. Everything is a secret by default; only items you pick yourself are marked “Not a secret”, after you confirm a warning.
3. If you imported through the file picker, you can choose to delete the original .env file. Dropped files are not deleted.
4. The import is saved as a single step. If it would exceed your plan’s data limit, nothing is saved and an upgrade prompt appears; existing information is untouched.

AI can use an imported group as a whole in “Inject into a run”: every AI-enabled item in the group is injected as an environment variable named after the item. A .env file left in the project can be read by AI, so clean it up once its contents are in the vault.

Finding information

Type a name or keyword in the search box while the vault is unlocked. Results update before you press Enter. Start with a short part of the name; exact matches rank ahead of partial and similar matches.

Search runs locally using algorithms, without sending your query to AI or the account server. It searches names and descriptions by default. Enable the option to also search value contents to include text values; matched secret values stay out of the result preview. Images are not searched with OCR. Select a result, then view or copy the field you need.

If nothing matches, shorten the query or adjust spacing. Clear the query to return to the full list. Search is unavailable while the vault is locked.

Language

Settings → General → Language — The language used on screen. It applies right away and is saved in this vault. The lock screen follows your computer's language.

Locking and quitting

Lock your vault when you leave your computer. New vaults lock after five minutes of inactivity by default; existing settings are kept. You can change the time in Settings. AI tasks that use secret values cannot proceed while the vault is locked. While AI is making requests, auto-lock is extended for up to 12 hours after you unlocked the vault, and the vault does not auto-lock within 60 minutes of the last AI request even if you step away. This keeps a long build from being cut off by a lock.

Closing the window leaves Bossanova running in the system tray. Click its tray icon to reopen it, or choose Quit from the tray menu to exit completely. AI cannot use the local vault when the computer is off or Bossanova has quit.

If you turn off auto-lock, lock the vault or press Ctrl/Cmd+L before leaving your desk.

Startup and unlock

In Settings → General → Startup and unlock, turn on Start when you sign in to your computer. Bossanova will open at your next login. This is off by default.

Open the vault automatically after computer login is a separate setting. Read the notice and confirm your master password to store an unlock credential in this device’s secure storage. With both settings on, Bossanova starts in the tray without opening a window at the next computer login.

Automatic opening works once per OS login. Manual lock, sleep, screen lock and restarting the app require your password. Changing the password or resetting security turns automatic opening off. Backups do not transfer the device unlock credential.

Automatic opening increases the risk of access by programs running as your OS user. Do not use it on shared computers. Keep your master password and external encrypted backups.

Device transfers and encrypted backups

The vault uses your OS user’s app data folder and secure storage, not the folder beside the EXE. Moving the executable does not move your vault. Devices do not sync automatically.

For ordinary device transfers, use the direct connection on the same Wi-Fi/LAN. The vault and images are encrypted and travel only between your devices, never through Bossanova servers. You do not need to carry a backup file on a USB drive. Bossanova (Windows) supports encrypted transfers up to 2 GiB, including images. Both devices need a version that supports this backup format.

A device receiving the vault for the first time joins the same vault. Later imports merge changes to folders, groups and data; you choose what to keep only when both devices changed the same item differently. This is not automatic sync: run an import whenever you want to exchange changes. AI connections and approvals do not transfer.

An encrypted backup is a separate copy for disaster recovery. Create or restore it in the desktop app under Settings → Backup. Keep a separate copy in a safe location that survives disk failure. Restoring returns to the backup’s point in time, so back up the current state first and preserve the originals until you verify recovery.

If damaged or missing image files prevent opening the vault, choose Restore from backup on the lock screen. Select a healthy backup of the same vault. Enter the current master password and the password used for that backup; they may differ. The app preserves the damaged original and remaining encrypted files before replacement, but cannot recreate missing contents. It restores the backup’s contents and keeps the current master password. Afterwards, review AI connections, approvals and value-sharing settings.

Automatic backups are copies kept on this PC (app data folder) for undoing accidental deletions. Export the vault again after changing the password or running a security reset.

Restore information from the backup, replacing later additions and changes. An encrypted copy of the current vault is saved on this PC first. Existing access history is retained; AI connections and value sharing are reset.

1. Connect both devices to the same regular Wi-Fi/LAN and sign in with the same Bossanova account. Open both apps and unlock any existing vaults. If the receiving device has no vault yet, start with “Import from another device” on its first screen.
2. On the sending device, choose Settings → Backup → “Send this vault”. The displayed code works once and expires after 3 minutes.
3. On the receiving device, choose “Import from another device” and enter the sender’s code and the master password for that vault. The app finds the sender automatically on the same LAN.
4. Keep both apps visible and existing vaults unlocked until completion. Moving an app to the background or locking a vault may cancel the transfer. Check the imported information and choose which versions to keep if there are conflicts.

Guest Wi-Fi isolation, a VPN or a firewall can prevent discovery. Use the same regular Wi-Fi on both devices, allow local network access and try again. There is no automatic internet relay fallback. Copying between devices can also carry deletions or mistakes, so it does not replace a separate backup.

Security

Settings → Security → Change master password — A normal change only changes the password that unlocks the vault. The internal encryption key and old backups remain unchanged. If exposure is suspected, use “Incident response · Reset security”.

Settings → Security → Incident response · Reset security — Protect current information with a new encryption key and password. Fields and values are preserved; all AI connections, access, and value sharing are reset. A new access history starts; the old history remains in the backup.

An encrypted backup from before the change is kept on this PC. Old backups still open with their old password and cannot directly overwrite the new vault. Recover them separately in an empty location.

If you suspect malware, first use a trusted device. Changing a password on an infected PC does not protect it.

Previously leaked information cannot be recalled. Change or revoke exposed passwords and API keys at their respective services. Create a new external backup afterwards.

Permanent vault deletion requires the master password and removes this PC’s vault and internal backups. It cannot be undone. External backups saved elsewhere remain.

Accounts, plans and devices

All plans, including Free, require sign-in in the app. Sign in with Google, Apple, or email and approve the displayed device. If you are already signed in, check the account and subscription section in Settings.

Choosing Hide My Email with Apple may create a separate account from one you already use with Google or email. To keep using an existing subscription, sign in with the method you used for that account.

Plan item limits apply to adding data and editing existing content. AI listing and use of stored data are not limited by item count. AI access and non-secret sharing can each be turned on or off even for read-only data. Sharing still requires consent; execution still requires an unlocked vault, an approved connection, an active device and operation approval.

After your subscription ends, you can still view, search, copy, back up and recover existing information. The ten fixed basic fields remain editable; additional fields are read-only. Renaming or reordering does not change this allocation. Templates require Plus or Pro.

Register a free pass under Settings → Account & subscription → Promotion code in the app, or in the code field on your account page. Enter discount codes in Paddle checkout after choosing a plan.

A free pass needs no card and ends on the date shown, without automatic charges. Passes for the same tier extend the remaining period. If you have paid access or a pass for another tier, wait until it ends. If you left a checkout unfinished, cancel the unpaid checkout on your account page before using a pass.

After applying a discount code, choose an eligible plan and complete Paddle checkout. A payment method is required and the subscription renews until canceled. Check the discount, number of discounted payments and full annual price. After the discount ends, renewals use the regular price. Manage billing lets you update payment methods, view receipts and cancel.

Sign in to the pricing page to change your plan or billing interval. Changes take effect immediately after you review and confirm the payment amounts. Use subscription management to cancel. While using a pass, choose Plus or Pro to reserve a subscription. There is no charge now: register a payment method and confirm the first billing date and renewal amount. Your selected plan starts after the pass ends and the first payment succeeds. Canceling the reservation preserves the original pass’s remaining time. Cancel it before adding another pass. Some price-specific discounts cannot be used for reservations. In regions such as South Korea that require additional consent, Paddle asks for confirmation before the first paid renewal. Without consent, the reservation is canceled without charge.

Signed-in devices lists the apps connected to your account. Only devices allowed to edit a vault count toward your plan limit. Stop editing switches a device to read-only at its next account check; Sign out beside a device requires it to sign in again. Neither action deletes vault files or backups.

Signing out locks your vault; sign in again to use it. Your original vault and backups are not deleted. If you cannot sign in, use Emergency backup export on the sign-in screen to export an encrypted backup once with your master password. While signed in, an expired paid plan still lets you edit ten basic fields; additional fields remain read-only. Paid features work offline for up to seven days.

Connecting AI

AI is optional. Once connected, AI hands any work that needs a value to Bossanova without ever receiving the value. When you turn on AI access for a data item, AI sees only its name, description and group, never the value. Where a value may be used is decided by you, on an approval card in the app, the first time AI tries to use it.

The trash icon at the top right of an approval revokes only that approval. Connection help and manual setup is for repairing connections or adding an unlisted AI app; normal use needs no changes there.

1. Unlock Bossanova and select Find AI on this computer in Settings → AI. This discovers Claude Desktop and local CLI hosts. Connect ordinary ChatGPT Chat separately in the ChatGPT card.
2. Connect each AI with its switch. Claude Desktop also installs bsnv for its local Code tab: use /mcp to check the connection and /bsnv for guidance. Chat uses + → Connectors and receives guidance through MCP. After an update, existing connections refresh the skill when you unlock Bossanova. Connect all excludes native Claude Code to avoid duplicates, but includes WSL rows.
3. Fully quit and reopen Claude after connecting it. The Codex row configures the Codex host. Ordinary Chat in the ChatGPT app and web uses the official OpenAI tunnel connection; the Codex configuration alone does not connect it.
4. For CLI hosts, start a new conversation and check that the Bossanova tools are listed. Turn on AI access for the data you want to use, then ask the AI to do its job as usual (for example, “Deploy with the deploy token stored in Bossanova”). AI picks the data by name and description.
5. The first time AI tries to use a data item, an approval card appears in Bossanova. Check the data and the target (a service, or an executable, folder, variable name and carrier) and choose Deny, Just this once, 24 hours, 7 days, 30 days or Always. Once allowed, the same target is not asked again.

Project control supports ordinary Chat in the ChatGPT app/web and Claude Desktop. WSL and Windows registrations are separate. Refresh tools or start a new conversation if the existing conversation retains an older MCP connection.

How AI uses a value

AI never receives the value. Work that needs a value is done by Bossanova on its behalf in one of two ways.

“Send on my behalf”: the AI provides an HTTPS request (method, URL, headers, body) with a placeholder where the value goes; Bossanova sends the request itself and inserts the value only there. The value is never in the AI’s code, request or response. The first time a service is used, the approval card lists the data and the service’s host set (well-known services such as GitHub group their hosts together); other paths and methods of the same service are not asked again. Only https on port 443 to public addresses is allowed, redirects are not followed, and the response is returned to the AI with any echoed value masked. This is the right way for secrets that are sent to a server, such as deploy tokens and payment, mail or cloud API keys.

“Inject into a run”: the AI names an executable (absolute path; scripts by their file), a working folder, this run’s arguments and an environment variable name. The approval card appears on first use; once allowed, Bossanova launches the program itself and passes the value only through the carrier stated on the card. Arguments are free per run and not part of the approval; a changed executable, folder, variable name, carrier or script content asks again. There are four carriers: environment variable (the value as is), temporary file (its path in the variable, deleted after the run), proxy (the process gets only a fake token; Bossanova’s per-run HTTPS proxy swaps it for the real value only in requests to the hosts on the card) and SSH agent (the key signs only inside Bossanova). With the proxy and agent carriers the process never receives the value itself (a value echoed back in a response is turned back into the fake token). Unlike “Send on my behalf”, the process sees responses first, and with the SSH agent the program can have any server signed with that key; the approval card says so.

Values that must end up inside an app, such as build tools and client SDK keys, belong to the environment variable carrier. The value is then inside that process and may remain in the program, its child processes and its outputs. Data already bound to a service through “Send on my behalf” cannot be injected through the environment variable or temporary file carriers (so server secrets never enter AI-written code). A group imported from .env can be injected as a whole, and commands that never end, such as a dev server, run as a session so the AI can read the running log and ask to stop it. Linux paths in WSL run inside that distro. A run is limited to 24 hours.

The AI gets back the exit code, the duration and the run log with the value masked (plain, base64 and URL-encoded forms are masked and secret-looking strings are stripped). If the command printed the value, the log is withheld from the AI and only the reason is returned; you can read the masked log under Recent runs in the AI tab.

There is one approval per data item and target, regardless of which AI asked (the requesting AI is only recorded in the access log). Durations are Just this once, 24 hours, 7 days, 30 days and Always, and approvals can be revoked in the approval list of the AI tab. Revoking does not undo a request that already reached its destination or a value already handed to a running program.

Images such as stamps and signatures are stored for you to view and copy; there is no feature that lets AI use them automatically. Nor is there any feature that fills in browser forms or completes documents on your behalf.

With env or file, the approved process receives the real value. Even send, proxy and agent can expose a secret indirectly if it is stored in an approved service and later read through another path. Never save secrets to AI-readable documents, logs or messages. The OS, app and approved target are trusted.

Turning off AI access pauses secret use and keeps time-based approvals, including Always. Turning it back on lets new requests reuse those approvals if the value and destination are unchanged; the original expiry does not move. Earlier waiting requests and one-time approvals do not resume. Use Revoke approval to cancel an approval. Non-secret sharing is a separate setting.

Marking data as “Not a secret”

Settings that AI must read as they are, such as port numbers, public URLs and project IDs, are marked “Not a secret” in the data detail view. This is separate from AI access and is off by default. Connected AI reads a “Not a secret” value directly through a dedicated read tool, and AI connected later can read it too. Even with “AI access” off, a “Not a secret” value can still be read through the read tool; it just does not appear in the lists used by “Inject into a run” and “Send on my behalf”. On screen, “Not a secret” values are not masked: text shows in full in the list and the detail view, and images show as a small preview in the list and a large one in the detail view.

In add and edit dialogs, marking a value as Not a secret makes it visible immediately. The eye icon stays in place but is dimmed and disabled.

1. Open the data detail or edit dialog and turn on “Not a secret”. Read the warning that values already sent to AI cannot be recalled, then choose “I understand, mark as not a secret”. This setting cannot be changed from a list row. In lists and details, the eye icon uses a warning colour.
2. In the .env import preview, candidate items can be marked the same way.
3. Turning the mark off blocks future reads but cannot recall values already sent to AI. In data and group creation or editing, the setting stays on while you type and text is unmasked. Saving with it on also shares the changed value. Restoring a backup turns the mark off.

A value marked “Not a secret” can reach the selected AI service and cannot be recalled once sent. Do not mark passwords or API keys this way; use “Send on my behalf” or “Inject into a run” instead.

Updates and file verification

In Settings → General → App updates, enable automatic checking and downloading, or check manually. You can keep using your vault during the download. A ready update installs next time you open the app, or choose Update and restart after finishing your edits. If signed updates are not ready, check the official download page.

Updating locks your vault and replaces app files while keeping saved information. To update manually, run the new official installer and keep the existing installation location. For a signed public release, check the publisher under Digital Signatures in Windows file properties. Unsigned internal test builds are not signed public releases. SHA-256 is an additional integrity check.

Starting with Bossanova 0.1.41, uninstalling on Windows signs you out. If you keep your vault, sign in to the same account after reinstalling and open it with its master password. Uninstalling keeps your vault data by default. Selecting data deletion in the Windows uninstaller can also delete your vault. External backups are separate. To move to a new PC, use export and import on the same Wi-Fi. Restoring an external backup is also available.

Updates download in the background without sending vault contents or account details.

Get-FileHash .\Bossanova-Setup.exe -Algorithm SHA256

Do not delete the vault data folder. If a signature or checksum does not match, do not run the file; check the official release.

Troubleshooting

1. If the app does not open, check Windows version, x64 support and any WebView2 message. Check the release status and file on the official download page before acting on security warnings.
2. If search is empty, check the lock state and query. If adding data or importing .env is blocked, check your plan’s data limit (10 on Free) and subscription status.
3. If AI tools are missing, make sure that AI’s connection toggle is on in Settings → AI, then start a new conversation. WSL and Windows AIs are listed separately, so connect the one you actually use. The Claude app and the ChatGPT app need a restart after connecting before the tools appear.
4. Turning on a connection in Settings → AI grants connection permission. There is no second connection card; data-use approvals remain separate. Turn on old pending or denied connections explicitly. For DENIED, check reason, detail and connection. Reconnecting alone does not grant permission.
5. If the AI says it did not receive the run log, the command printed the value. Read the masked log under Recent runs in the AI tab and change the command so it does not print the value.
6. Windows curl with Schannel ignores SSL_CERT_FILE. Pass that path with --cacert inside the approved process. Use --ssl-revoke-best-effort only for missing/offline revocation lists; never --insecure. Consider WSL for Windows gh. AWS request signing needs a suitable carrier such as env or file. For docker login, the approved process can read the file carrier’s file into --password-stdin. Use a temporary DOCKER_CONFIG and remove it afterwards.
7. For help, send the error text, OS, app version and reproduction steps. Do not send passwords, vault files, secret values or connection tokens.

Bossanova does not control the OS or other programs. Broad AI access to administrator functions, files, screens or memory, or a compromised computer, can expose information through other paths. See the secret protection notice for details.