/use-avibe-vault

name: use-avibe-vault
slug: use-avibe-vault
description: Use Avibe Vault for API keys, tokens, passwords, protected credentials, authenticated HTTP requests, or signing digests and Solana messages without exposing secret values to the agent.
version: 0.8.1

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:

• Vault approval auto-resume and Vault's `--no-callback` are unchanged by the retirement of Agent Run callbacks. Agent Run `--no-reply` does not disable Vault continuations.
• 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`, the command did not run; Avibe resumes this session once the request is decided, and after approval you run the same command once. Stopping a still-pending waiter leaves continuation to that callback. A fetch response lost after approval completion is different: follow its `execution_unknown` guidance rather than assuming the callback will fire.
• 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.
• `vault fetch` requires a running, compatible Avibe service. `service_unavailable` with `execution: not_executed` means no fetch ran; start/update the service only with the appropriate authorization. There is no offline SQLite fallback or automatic service start. `execution_unknown` means the result or approval continuation could not be confirmed: do not replay automatically. In Show `api/*.ts` handlers, use the server-only adapter documented by `use-show-pages` instead of spawning a CLI per fetch.
• 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.
• A protected BTC key signs only one bounded BIP86 key-path payment per request: `--scheme schnorr-secp256k1-bip341-keypath --digest DIGEST` with a `bitcoin-taproot-keypath-v1` `--signing-context-json`. The context has exactly `kind`, `network` (`bi