Skip to main content
The vault is an encrypted credential store that lives alongside your project in .polpo/vault.enc. It lets agents securely access API keys, OAuth tokens, SMTP credentials, and other secrets at runtime without exposing them in plaintext config files.

​
How it works

Credentials are stored as AES-256-GCM encrypted JSON. The file format is a binary blob: 
[ 12-byte IV ] [ 16-byte auth tag ] [ ciphertext ]
The plaintext, once decrypted, is a nested JSON object keyed by agent name and service name: 
{
  "back-office": {
    "sendgrid": {
      "type": "api_key",
      "label": "SendGrid production key",
      "credentials": { "apiKey": "SG.xxxxxxxxxxxx" }
    },
    "company-smtp": {
      "type": "smtp",
      "credentials": {
        "host": "smtp.example.com",
        "port": "587",
        "user": "agent@example.com",
        "pass": "${SMTP_PASSWORD}"
      }
    }
  }
}
The decrypted structure is Record<agentName, Record<serviceName, VaultEntry>>. Each agent can only access its own entries via vault tools.

​
Encryption key resolution

The vault key is resolved in order:
1

POLPO_VAULT_KEY environment variable

Set POLPO_VAULT_KEY to a hex-encoded 32-byte key (64 hex characters). This takes priority and is recommended for CI/CD and production deployments.
2

Auto-generated key file

If no environment variable is set, Polpo looks for ~/.polpo/vault.key. If it does not exist, a random key is generated and written there automatically on first use.
The key file at ~/.polpo/vault.key is created with 0o600 permissions (owner read/write only). Never commit this file. The encrypted vault.enc file is safe to commit — without the key it is opaque ciphertext.

​
VaultEntry types

Each entry in the vault has a type, an optional label, and a credentials map.
TypeUse caseTypical credential fields
smtpEmail sendinghost, port, user, pass
imapEmail readinghost, port, user, pass
oauthOAuth tokensclient_id, client_secret, refresh_token
api_keyThird-party API keysapiKey (or any key name)
loginUsername/password pairsusername, password
customAnything elseAny key-value pairs

​
Environment variable references

Credential values can be literals or ${ENV_VAR} references that are resolved at runtime: 
{
  "type": "smtp",
  "credentials": {
    "host": "smtp.example.com",
    "port": "587",
    "user": "agent@example.com",
    "pass": "${SMTP_PASSWORD}"
  }
}
When the agent calls vault_get, the ${SMTP_PASSWORD} placeholder is replaced with the value of the SMTP_PASSWORD environment variable.

​
VaultStore API

The VaultStore class provides programmatic access when building custom integrations:
MethodSignatureDescription
getget(agent, service)Retrieve a single entry
setset(agent, service, entry)Create or update an entry
removeremove(agent, service)Delete an entry
listlist(agent)List service names for an agent
getAllForAgentgetAllForAgent(agent)Retrieve all entries for an agent

​
Agent vault tools

Agents access the vault through two built-in tools that are always available when a vault.enc file exists in the project:
ToolDescription
vault_getRetrieve credentials for a specific service
vault_listList available service names for the calling agent
Agents can only access their own vault entries. An agent named back-office cannot read entries belonging to researcher. The orchestrator has read access to all entries.

​
Examples

{
  "type": "smtp",
  "label": "Transactional email",
  "credentials": {
    "host": "smtp.mailprovider.com",
    "port": "587",
    "user": "notifications@myapp.com",
    "pass": "${EMAIL_SMTP_PASS}"
  }
}

​
CLI setup

The polpo agent onboard command includes an interactive vault setup flow that walks you through adding credentials for the agent being onboarded. 
polpo agent onboard back-office

​
Git safety

Safe to commit

.polpo/vault.enc — encrypted, opaque without the key.

Must be gitignored

~/.polpo/vault.key — the decryption key. Add it to your global gitignore.
Your .gitignore should include: 
# Never commit the vault key
vault.key