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.

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