PaperClipAI/docs/deploy/secrets.md

title, summary

title	summary
Secrets Management	Master key, encryption, and strict mode

Paperclip encrypts secrets at rest using a local master key. Agent environment variables that contain sensitive values (API keys, tokens) are stored as encrypted secret references.

Default Provider: local_encrypted

Secrets are encrypted with a local master key stored at:

~/.paperclip/instances/default/secrets/master.key

This key is auto-created during onboarding. The key never leaves your machine. Paperclip best-effort enforces 0600 permissions when it creates or loads the key file. paperclipai doctor and the provider health API warn when the file is readable by group or other users.

Back up the key file together with database backups. A database backup without the key cannot decrypt local secrets, and a key backup without the database metadata is not enough to restore named secret versions.

Configuration

CLI Setup

Onboarding writes default secrets config:

pnpm paperclipai onboard

Update secrets settings:

pnpm paperclipai configure --section secrets

Validate secrets config:

pnpm paperclipai doctor

Environment Overrides

Variable	Description
PAPERCLIP_SECRETS_MASTER_KEY	32-byte key as base64, hex, or raw string
PAPERCLIP_SECRETS_MASTER_KEY_FILE	Custom key file path
PAPERCLIP_SECRETS_STRICT_MODE	Set to true to enforce secret refs

Strict Mode

When strict mode is enabled, sensitive env keys (matching *_API_KEY, *_TOKEN, *_SECRET) must use secret references instead of inline plain values.

PAPERCLIP_SECRETS_STRICT_MODE=true

Recommended for any deployment beyond local trusted.

Authenticated deployments default strict mode on unless explicitly overridden by configuration or PAPERCLIP_SECRETS_STRICT_MODE=false.

External References

Provider-owned secrets can be linked without copying values into Paperclip by using managedMode: "external_reference" plus a provider externalRef. Paperclip stores metadata and a non-sensitive fingerprint, never the value. Runtime resolution remains server-side and binding-enforced.

The built-in AWS, GCP, and Vault provider IDs currently accept external reference metadata, but runtime resolution requires provider configuration in the deployment. Their provider health check reports this as a warning until configured.

Migrating Inline Secrets

If you have existing agents with inline API keys in their config, migrate them to encrypted secret refs:

pnpm secrets:migrate-inline-env         # dry run
pnpm secrets:migrate-inline-env --apply # apply migration

Secret References in Agent Config

Agent environment variables use secret references:

{
  "env": {
    "ANTHROPIC_API_KEY": {
      "type": "secret_ref",
      "secretId": "8f884973-c29b-44e4-8ea3-6413437f8081",
      "version": "latest"
    }
  }
}

The server resolves and decrypts these at runtime, injecting the real value into the agent process environment.