# docker pass **Description:** Manage your local OS keychain secrets. **Usage:** `docker pass set|get|ls|rm|run` ## 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://` and the engine resolves it just before the container starts. With `docker run -e`: ```sh docker run --rm -e OPENAI_API_KEY=se://openai/api-key busybox sh -c 'echo "$OPENAI_API_KEY"' ``` In a Compose file under `environment:`: ```yaml 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://` is replaced with the resolved secret; everything else is passed through untouched. ```sh 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/`, `docker/db//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://`, the engine fans the lookup out to every plugin whose declared pattern matches `` 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: ```sh docker pass plugins ls ``` Plugins marked as **configurable** can be enabled or disabled at runtime: ```sh docker pass plugins enable docker pass plugins disable ``` ### 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](https://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](https://github.com/docker/secrets-engine/issues). ## Examples ### Using keychain secrets in containers Create a secret: ```console $ docker pass set GH_TOKEN=123456789 ``` Create a secret from STDIN: ```console echo "my_val" | docker pass set GH_TOKEN ``` Run a container that uses the secret: ```console $ docker run -e GH_TOKEN= -dt --name demo busybox ``` Inspect the secret from inside the container: ```console $ docker exec demo sh -c 'echo $GH_TOKEN' 123456789 ``` Explicitly assign a secret to a different environment variable: ```console $ docker run -e GITHUB_TOKEN=se://GH_TOKEN -dt --name demo busybox ``` ### Using keychain secrets in Compose Store the secrets: ```console $ docker pass set myapp/anthropic/api-key=sk-ant-... $ docker pass set myapp/postgres/password=s3cr3t ``` ```yaml 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 | Command | Description | |---------|-------------| | [`docker pass get`](https://docs.docker.com/reference/cli/docker/pass/get/) | Get a secret from a keystore. | | [`docker pass ls`](https://docs.docker.com/reference/cli/docker/pass/ls/) | List all secrets from local keychain. | | [`docker pass plugins`](https://docs.docker.com/reference/cli/docker/pass/plugins/) | Manage secrets engine plugins. | | [`docker pass rm`](https://docs.docker.com/reference/cli/docker/pass/rm/) | Remove secrets from local keychain. | | [`docker pass run`](https://docs.docker.com/reference/cli/docker/pass/run/) | Run a command with `se://` environment references resolved. | | [`docker pass set`](https://docs.docker.com/reference/cli/docker/pass/set/) | Set a secret |