Custom secret providers

A custom secret provider lets your agent use a password-manager item the same way it uses a Kody secret: a placeholder in fetch, resolved at the network boundary. The model never sees the value. User secrets use {{secret:name}}; providers use {{secret/<provider>:<ref>}}.

Provider packages declare an id such as 1password. Provider logic lives in a saved package you bind; Kody core does not talk to the vault itself.

Bind a provider

1. Save the vault door key as a Kody user secret. Paste it on /connect/secret-set, never into chat. URL shape: Secret setup URL reference.
2. Have a saved package that declares kody.secretProvider.id (for example 1password) and exports ./secretProvider.
3. Bind that package on /@<slug>/-/secret-providers (secretProviderBind): provider id, package, door-key secret name, and optional non-secret config.

Declaring metadata on a package does not bind it. Only the account owner can bind or unbind. Unbind, and rebind to a different package, drop every grant for that provider.

Use a placeholder

In secret-aware fetch:

{{secret/1password:i/<item-id>/password}}

<item-id> is a UUID (Service Account / web) or a 1Password Connect item id (^[a-z0-9]{26}$). op://Vault/<item-id>/password is a writable synonym that canonicalizes to the same grant key when the item segment is one of those ids. Name-based vault paths are not interpreted in Kody core.

The item's websites are the host allowlist. Empty websites refuse the fetch. The request URL must be https:.

Ad hoc execute does not need a package grant. Saved packages do: secretProviderLock returns the Allow URL; grant and revoke on /@<slug>/-/secret-providers. A package runs in the org that owns it, so a collaborator holding a grant uses that org's binding and grants, not their own.

Search does not crawl vaults. secretProviderList returns binding metadata only.

MCP

Search secretProviderList / secretProviderBind / secretProviderLock first; open capability detail for the exact call shape.

Where to go next

• Secrets — the no-secret_get rule, placeholders, and host approval