Legacy Secrets Vault

Vault entries are scoped by agent and service. Runtime tools receive resolved credentials without putting secret values in prompts, agent configuration, or chat history.

Vault is now a legacy compatibility surface. Use Connections for new API keys, OAuth accounts, remote MCP servers, channel credentials, shared integrations, and custom-tool credentials. Keep Vault only for existing agent-private secrets that still use the legacy vault_get / vault_list tools.

Polpo Cloud encrypts each credential object in the tenant database with AES-256-GCM. OSS and local deployments use the same encrypted data model in .polpo/vault.enc.

Entry schema

{
  "agent": "back-office",
  "service": "company-smtp",
  "label": "Transactional email",
  "type": "smtp",
  "credentials": {
    "host": "smtp.example.com",
    "port": "587",
    "user": "agent@example.com",
    "pass": "secret",
    "from": "agent@example.com",
    "secure": "false"
  }
}

Credential field names are validated by type:

Type	Required fields
`api_key`	`key`
`smtp`	`host`, `port`, `user`, `pass`, `from`; optional `secure`
`imap`	`host`, `port`, `user`, `pass`; optional `tls`
`oauth`	`access_token`; optional refresh/client/scope fields and provider fields
`login`	`username`, `password`
`custom`	At least one string key/value pair

Use key, not apiKey, for an api_key entry. SMTP and IMAP ports are numeric strings in the REST payload.

Agent access

vault_get and vault_list are always registered. They only expose entries belonging to the calling agent. vault_list returns service names, types, and credential key names without values. Custom tools no longer receive ctx.vault. New custom integrations should read credentials from project Connections through ctx.connections.

API

Method	Path	Description
`POST`	`/v1/vault/entries`	Create or replace an entry
`GET`	`/v1/vault/entries/{agent}`	List metadata for one agent
`PATCH`	`/v1/vault/entries/{agent}/{service}`	Merge a typed partial update
`DELETE`	`/v1/vault/entries/{agent}/{service}`	Delete an entry

PATCH still requires type so Polpo can validate credential field names. Create and update responses never return credential values.

await client.saveVaultEntry({
  agent: "researcher",
  service: "exa",
  type: "api_key",
  credentials: { key: process.env.EXA_API_KEY! },
});

const entries = await client.listVaultEntries("researcher");

Local encryption

For the file-backed OSS vault, the key is resolved in this order:

POLPO_VAULT_KEY, exactly 64 hexadecimal characters;
~/.polpo/vault.key, read or generated as 32 random bytes with owner-only permissions where supported.

The encrypted wire format is a 12-byte IV, a 16-byte authentication tag, and ciphertext. Credential strings may contain ${ENV_VAR} references; the runtime resolves them against its safe environment when it builds the agent’s vault.

Never commit the key. Although vault.enc is encrypted, treat it as sensitive configuration and exclude it from source control unless your security process explicitly permits encrypted secret artifacts and manages the key separately.

polpo deploy synchronizes local vault entries to the Cloud vault. Cloud then stores encrypted entries in the project database rather than reading .polpo/vault.enc at runtime.

Getting Started

Platform

Agents

Orchestration

Legacy Secrets Vault

Entry schema

Agent access

API

Local encryption

​Entry schema

​Agent access

​API

​Local encryption

Entry schema

Agent access

API

Local encryption