> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Legacy Secrets Vault

> Legacy encrypted agent-scoped credential storage

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

<Warning>
  Vault is now a legacy compatibility surface. Use [Connections](/docs/agents/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.
</Warning>

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

```json theme={null}
{
  "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.

```typescript theme={null}
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:

1. `POLPO_VAULT_KEY`, exactly 64 hexadecimal characters;
2. `~/.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.

<Warning>
  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.
</Warning>

`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.