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

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




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