docs/data/cli/secrets/docker_pass.yaml

command: docker pass
short: Manage your local OS keychain secrets.
long: |-
    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.

    ### Installation

    On Docker Desktop, Secrets Engine and `docker pass` are integrated by default.
    For Docker CE, install the packages separately from Docker's official
    repository. This requires Docker Engine (`dockerd`) 29.2.0 or later. If you did
    not install Docker Engine from that repository, add it with the official
    convenience script:

    ```shell
    curl -fsSL https://get.docker.com | sh -s -- --setup-repo
    ```

    apt (Debian/Ubuntu):

    ```shell
    sudo apt-get update
    sudo apt-get install docker-secrets-engine docker-secrets-engine-plugins
    ```

    dnf (Fedora):

    ```shell
    sudo dnf install docker-secrets-engine docker-secrets-engine-plugins
    ```

    Then enable the service for your user:

    ```shell
    systemctl --user daemon-reload
    systemctl --user enable --now docker-secrets-engine.service
    ```

    For full instructions see the [Secrets Engine README](https://github.com/docker/secrets-engine/blob/main/README.md).

    ### 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`:

    ```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
    ```

    Note: `docker compose build` is not supported yet.

    #### 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.

    ```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/<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:

    ```sh
    docker pass plugins ls
    ```

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

    ```sh
    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](https://developer.1password.com/docs/cli/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](https://developer.1password.com/docs/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:**
      ```sh
      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](https://developer.1password.com/docs/service-accounts/get-started/)
      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:
      ```sh
      echo "$OP_SERVICE_ACCOUNT_TOKEN" | docker pass plugins 1password setup
      ```
    - **Teardown:** remove the token and disable the plugin:
      ```sh
      docker pass plugins 1password purge
      ```

    ### 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).
usage: docker pass set|get|ls|rm|run
pname: docker
plink: docker.yaml
cname:
    - docker pass get
    - docker pass ls
    - docker pass plugins
    - docker pass rm
    - docker pass run
    - docker pass set
clink:
    - docker_pass_get.yaml
    - docker_pass_ls.yaml
    - docker_pass_plugins.yaml
    - docker_pass_rm.yaml
    - docker_pass_run.yaml
    - docker_pass_set.yaml
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
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
    ```