docker pass

Description

Docker Pass is a helper for securely retrieving secrets from a range of backends, such as your local OS keychain, password managers, or remote vaults, and injecting them into containers and host commands when needed. Each backend is implemented as a plugin.

Secret References

A secret reference is written using the se:// URI scheme and either identifies a specific secret or matches multiple secrets through a pattern over the realm structure. For example:

• se://docker/auth/hub/alice — resolves to a specific secret, Alice's Docker Hub credential.
• se://docker/auth/hub/* — matches every credential stored directly under Docker Hub.
• se://docker/auth/** — matches every Docker auth secret across all registries.

Resolution fans out across every plugin whose pattern matches the reference, so even a specific ID can return multiple values if more than one plugin has stored a secret under that ID. The same reference can be reused across environments and storage backends without rewriting Compose files or application configuration. For example, it may resolve against your local OS keychain in development and against a production vault in CI or on a server.

The engine resolves these references in two contexts:

Containers

Anywhere Docker accepts an environment-variable value, write se://<id|pattern> and the engine resolves it just before the container starts.

With docker run -e:

docker run --rm -e OPENAI_API_KEY=se://openai/api-key busybox sh -c 'echo "$OPENAI_API_KEY"'

In a Compose file under environment::

services:
  app:
    image: your/image
    environment:
      DB_PASSWORD: se://postgres/prod/app-user

Host commands

docker pass run wraps any host process and resolves se:// references in its environment before exec'ing it. Any env variable whose value has the form se://<id|pattern> is replaced with the resolved secret; everything else is passed through untouched.

GH_TOKEN=se://gh-token docker pass run -- gh repo list

Identifiers

Secret IDs are hierarchical, path-like strings. Components are separated by /; each component may contain A-Z, a-z, 0-9, ., -, _, or :. No leading, trailing, or empty components. Matching is case-sensitive. A predictable realm/namespace structure (e.g. docker/auth/<registry>, docker/db/<env>/password) makes automation and access control easier.

Patterns

Patterns follow the same rules as identifiers, with two extra tokens:

• * — matches exactly one component.
• ** — matches zero or more components.

Wildcards must occupy a whole component (e.g. auth/*/token is valid; auth/foo* is not), and a single component may contain at most one of * or **.

Example patterns:

• docker/auth/** — every Docker auth secret in any sub-realm.
• myrealm/*/password — password entries one level deep under myrealm.
• ** — catch-all.

Routing

When a container references se://<id|pattern>, the engine fans the lookup out to every plugin whose declared pattern matches <id|pattern> and merges their responses. If no plugin matches, the lookup fails and the container does not start.

Plugin Management

Use the CLI to inspect loaded and available plugins:

docker pass plugins ls

Plugins marked as configurable can be enabled or disabled at runtime:

docker pass plugins enable <name>
docker pass plugins disable <name>

Plugins

OS Keychain

• Plugin name: docker-pass
• Storage backend: the local OS keychain, accessed via platform-specific APIs:
  • Windows: Windows Credential Manager API
  • macOS: Keychain Services API
  • Linux: org.freedesktop.secrets API (requires DBus and a Secret Service provider such as gnome-keyring or kdewallet)
• Use: holds secrets you store directly with docker pass (and internal secrets used by other plugins, such as the 1Password service account token). Always on; not configurable.

1Password (configurable)

Each item matches the requested pattern under up to three candidate IDs:

1. Raw item ID — the opaque alphanumeric ID that 1Password assigns (e.g. alphanumeric_26char).
2. <vault-id>/<title> — the vault's ID joined with the item's normalized title.
3. <vault-name>/<title> — the vault's display name joined with the item's normalized title.

Normalization (applied to vault names and titles) follows 1Password's secret-reference syntax: spaces become -, ( and ) are stripped, / and & become _, any remaining character outside [a-zA-Z0-9-._] is removed, and the result is lowercased. Following 1Password's matching rules makes the plugin case-insensitive, so existing op:// references can be reused as-is. Candidates that don't produce a valid ID are skipped silently, so items with unusual names are still matchable through one of the other forms.

CLI version

• Plugin name: 1password-cli

• How it authenticates: delegates to the op CLI. You need op installed and an active 1Password session. On macOS this typically means the 1Password desktop app with biometric unlock enabled; on other platforms, op signin.

• Setup: no tokens to manage. If your local op is signed in, the plugin can resolve secrets.

• Behavior: when Docker Desktop starts, the plugin performs an initial fetch of all items, which triggers a 1Password authorization prompt. The resulting cache is then refreshed periodically.

• Fatal errors: the plugin treats a few conditions as unrecoverable and stops itself instead of retrying:

  • the op binary cannot be found on PATH,
  • the user dismisses or lets the 1Password authorization prompt time out.

  When this happens the plugin is reported as crashed in docker pass plugins ls. Resolve the underlying issue (install op, sign in, accept the prompt) and re-enable the plugin with docker pass plugins enable 1password-cli.

• Enable / disable:

  docker pass plugins enable 1password-cli
  docker pass plugins disable 1password-cli

Service account token version

• Plugin name: 1password-sdk
• How it authenticates: uses the official 1Password Go SDK with a service account token scoped to the vaults you want to expose.
• Setup: supply the token once on stdin. It is stored in the OS keychain and the plugin is enabled in the same step:

  echo "$OP_SERVICE_ACCOUNT_TOKEN" | docker pass plugins 1password setup

• Teardown: remove the token and disable the plugin:

  docker pass plugins 1password purge

Feedback and SDK

Use the Go SDK at github.com/docker/secrets-engine to integrate secret resolution into your own code, build custom clients, or write new plugins.

Have a feature request or hit a bug? File an issue at github.com/docker/secrets-engine/issues.

Examples

Using keychain secrets in containers

Create a secret:

$ docker pass set GH_TOKEN=123456789

Create a secret from STDIN:

echo "my_val" | docker pass set GH_TOKEN

Run a container that uses the secret:

$ docker run -e GH_TOKEN= -dt --name demo busybox

Inspect the secret from inside the container:

$ docker exec demo sh -c 'echo $GH_TOKEN'
123456789

Explicitly assign a secret to a different environment variable:

$ docker run -e GITHUB_TOKEN=se://GH_TOKEN -dt --name demo busybox

Using keychain secrets in Compose

Store the secrets:

$ docker pass set myapp/anthropic/api-key=sk-ant-...
$ docker pass set myapp/postgres/password=s3cr3t

services:
  api:
    image: service1
    environment:
      - ANTHROPIC_API_KEY=se://myapp/anthropic/api-key
      - POSTGRES_PASSWORD=se://myapp/postgres/password

  worker:
    image: service2
    command: worker
    environment:
      - ANTHROPIC_API_KEY=se://myapp/anthropic/api-key

  db:
    image: postgres:17
    environment:
      - POSTGRES_PASSWORD=se://myapp/postgres/password

Subcommands