use-avibe-vault

Use Avibe Vault

When a task needs API keys, access tokens, passwords, wallet private keys, or other sensitive credentials, prefer Avibe Vault: agents reference secrets by name, tag, or skill tag, and users do not need to paste plaintext into chat.

Core concepts:

• Static secret: a regular secret value, such as an API key, token, database password, or deployment credential. Use it with vibe vault run for environment injection or vibe vault fetch for authenticated HTTP egress.
• A static secret can contain up to 32 named fields. NAME selects its default field (existing secrets call it value); NAME.field selects that field, including an explicit default label such as GITHUB_LOGIN.password. Field names match ^[a-z][a-z0-9_]{0,63}$. The default label may be renamed; extra labels and the choice of default cannot change after creation.
• Keypair secret: a signing key for digests or transactions, such as a wallet key or deployment signer. It cannot be exported as an environment variable and cannot be used with run / fetch; use vibe vault sign.
• Standard: for lower-risk routine automation. Agents can usually use it without interrupting the user unless it is configured to ask first.
• Protected: for high-risk secrets, such as production databases or wallet/funds keys. Because protected secrets are end-to-end encrypted, use requires browser approval and passkey unlock.

Rules:

• Refer to secrets only by secret name, record ref (NAME.field), tag, or skill tag.
• Static secrets can be used with run / fetch; keypair secrets can only be used with vibe vault sign. Keypairs do not accept field refs.
• Authorization is per secret: approving a protected secret unlocks all its fields for the grant's lifetime. The CLI cannot create, replace, or delete fields; the user does that in the browser.
• --env NAME.field delivers one value to NAME_FIELD (only the field is uppercased); --env LOCAL=NAME.field chooses the variable. --tag and --skill deliver every field of each selected secret, using NAME for the default and NAME_FIELD for extras. Conflicting variable mappings fail before delivery.
• list and find print the same value-free row: a static secret lists its fields, and a multi-field secret also names its default_field, the field NAME selects. If a ref fails with field_not_found, use the listed field names rather than guessing.
• export remains deprecated and has no delivery. Prefer run; advanced inject writes a restricted-permission file, so use it only for tools that require file-based configuration.
• With vibe vault run, the child process receives static secrets as environment variables, so never run commands that may print env vars, debug config, or secret-bearing errors.
• When protected run / fetch needs approval, Avibe automatically asks the user to decrypt and authorize access, and the command waits for that approval (540 seconds by default; --approval-wait SECONDS or --no-approval-wait to change it). If the command then succeeds, it ran once: do not run it again. If it returns approval_required, approval_wait_timeout, or approval_handed_off, or your call to it is stopped before it gets the approval, the command did not run; Avibe resumes this session once the request is decided, and after an approval you run the same run / fetch command once.
• If a Vault command fails with avault_authorization_required, avault needs a one-time macOS Keychain authorization on the Mac running Avibe. Do not retry, and do not run avault or vibe vault key authorize yourself: ask the user to choose Authorize avault on the Vault page (or to run vibe vault key authorize on that Mac), then run the command once after they confirm.
• When protected sign needs approval, Avibe creates a browser signing request and returns immediately. Do not rerun sign; when Avibe resumes this session, follow the callback instruction to read the completed request result and continue with the returned signature.
• For the listed standard-tier BTC Taproot addresses, use schnorr-secp256k1-bip341-keypath (BIP86, empty script tree). It requires an avault build supporting that scheme. Older builds fail closed: never retry with raw BIP340, rotate the key, or change the receiving address as a workaround. No Merkle-root/script-tree option is supported.
• schnorr-secp256k1-bip340 is raw signing under the internal public key, NOT signing for the listed tweaked Taproot address. ecdsa-secp256k1-der produces low-S DER for Bitcoin ECDSA; the caller constructs and validates the transaction sighash and appends any transaction-required sighash byte.
• Protected Bitcoin transaction signing is not supported yet. BTC addresses remain visible to identify existing funds; do not recommend deposits expecting this workflow to spend them. Never disguise a Bitcoin sighash as an agent operation or downgrade a protected key.
• Protected signing needs --signing-context-json with a supported verifiable context. An avault-agent-operation preimage must begin with avault-agent-operation:v1 followed by a real LF newline and nonempty operation text; its digest is SHA256 of those UTF-8 bytes. JSON encodes that newline as \n, not \\n. This domain is for agent operations only, not transaction authorization. A legacy unbound request must be recreated after both producer and sandbox are upgraded.