locket

A secrets management agent. Keeps your secrets safe, but out of sight.

1. Overview
2. Supported Providers
3. Full Configuration
4. Roadmap

Overview

locket is a small CLI tool, packaged as a tiny rootless and distroless Docker image, designed to orchestrate secrets for dependent applications and services. locket is designed to work with most secrets providers, and it will orchestrate the retrieval of secrets and injection of them into dependent services. locket can help keep sensitive files off disk completely in tmpfs, or just somewhere out of revision control.

Currently, locket supports the following modes

1. Sidecar: Inject secrets into configuration files stored in a shared, ephemeral tmpfs volume. locket will render files with secret references replaced with actual secrets so that dependent services can use them.
2. Provider: locket can be installed as a Docker CLI plugin, and it will inject secrets directly into the dependent process enviornment before it starts.
3. Orchestrator: locket can be installed on the host, and locket exec is able to manage a specified subcommand, injecting secrets into its process environment. It can also watch for changes to environment files, and restart the dependent service automatically.

Providers

1. 1password Connect
2. 1password Service Accounts
3. Bitwarden Secrets Manager

[!TIP] Each provider has its own docker image for sidecar mode, if a slim version is preferred. The latest tag bundles all providers and their respective dependencies. But a provider specific tag like locket:connect is only about 4MB and has no extra dependencies besides what is needed for the connect provider.

Sidecar Mode

The basic premise of locket as a sidecar service is:

1. Move your sensitive data to a dedicated secret manager (Supported Providers)
2. Adjust your config files to carry secret references instead of raw sensitive data, which are safe to commit directly to revision control (i.e {{ op://vault/keys/privatekey?ssh-format=openssh }})
3. Configure locket to use your secrets provider --provider=bws or with env: SECRETS_PROVIDER=bws. Or just use the docker image tag locket:bws
4. Mount your templates containing secret references for locket to read, i.e. ./templates:/templates:ro, and mount an output directory for the secrets to be placed (usually a named tmpfs volume, or some secure location) secrets-store:/run/secrets/locket
5. Finally, map the template->output for each required mapping. You can map arbitrarily many directories->directories or files->files. --map /templates:/run/secrets/locket

Your secrets will all be injected according to the provided configuration, and any dependant applications will have materialized secrets available.

[!TIP] By default, locket will also watch for changes to your secret reference files, and will reflect those changes immediately to the configured output. So if you have an application which supports a dynamic config file with hot-reloading, you can manage this with locket directly without downtime. If you dont want files watched, simply use --mode=park to inject once and then hang out (to keep the process alive for healthchecks). Or use --mode=one-shot to do a single inject and exit.

A full configuration reference for all available options is provided in docs/run.md

services:
  locket:
    image: ghcr.io/bpbradley/locket:latest
    user: "65532:65532" # The default user is 65532:65532 (nonroot) when not specified
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    # Configurations can be supplied via command like below, or via env variables.
    command:
        - "--provider=op-connect"
        - "--op.token-file=/run/secrets/op_token"
        - "--map=/templates:/run/secrets/locket" # Supports multiple maps, if needed.
        - "--secret=db_pass={{ op://vault/db/pass }}"
        - "--secret=db_host={{ op://vault/db/host }}"
        - "--secret=key={{ op://vault/keys/privatekey?ssh-format=openssh }}"
    secrets:
      - op_token
    volumes:
        # Mount in your actual secret templates, with secret references
      - ./config/templates:/templates:ro
        # Mount in your output directory, where you want secrets materialized
      - secrets-store:/run/secrets/locket
  app:
    image: my-app:latest
    depends_on:
        locket:
            condition: healthy # locket is healthy once all secrets are injected
    volumes:
      # Mount the shared volume wherever you want the secrets in the container
      - secrets-store:/run/secrets/locket:ro
    environment:
        # We can directly reference the materialized secrets as files
        DB_PASSWORD_FILE: /run/secrets/locket/db_pass
        DB_HOST_FILE: /run/secrets/locket/db_host
        SECRET_KEY: /run/secrets/locket/key

secrets:
  op_token:
    file: /etc/op/token # Must have read permissions by locket user

# We can create a shared tmpfs volume that locket will write to, and our app will
# read from
volumes:
  secrets-store:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs

Security

The sidecar image runs as user 65532 (nonroot) by default. This was adopted from the standards set in Google's popular rootless/distroless images. In addition, locket does not serve inbound requests and requires no elevated privilege. So it is safe to add any additional security measures to docker compose configuration.

It may be useful to explicitly set permissions on the tmpfs driver, to avoid any ambiguity. However, docker will typically set this up correctly when the volume is created, depending on what services depend on it.

services:
  locket:
    image: ghcr.io/bpbradley/locket
    user: "1000:1000"
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    volumes:
      - secrets-store:/run/secrets/locket:ro

volumes:
  secrets-store:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs
      o: uid=1000,gid=1000,mode=700

Provider mode

locket can be installed as a docker CLI plugin, and be used as a Docker Compose provider service. In this mode, locket manages the compose up lifecycle. Every time docker compose up is called, locket compose up is first called by Docker, where locket will take provided secret references and set them as environment variables in the dependent container.

A full configuration reference for all available options is provided in docs/compose.md

---
name: provider
services:
  locket:
    provider:
      type: locket
      options:
        provider: op-connect
        connect.token-file: /etc/connect/token
        connect.host: $OP_CONNECT_HOST
        secrets:
          - "secret1={{ op://Mordin/SecretPassword/Test Section/text }}"
          - "secret2={{ op://Mordin/SecretPassword/Test Section/date }}"
  demo:
    image: busybox
    user: "1000:1000"
    command: 
      - sh
      - -c
      - "env | grep LOCKET"
    depends_on:
      - locket

[!NOTE] The environment variables are injected with the providers service name prefixed. This is behavior managed by Docker directly, and cannot be changed. So in some cases it may be necessary to expand the environment variable in the container like $$APPLICATION_SECRET.

In order to use the Provider mode, locket must be installed on the host system directly as a Docker CLI plugin. The simplest way to do this is to install the binary directly from GitHub, and symlink it to the appropriate directory for docker to access it as a cli-plugin.

Install prebuilt binaries

The install script will install locket to your user home directory, as well as a locket-update script.

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/bpbradley/locket/releases/latest/download/locket-installer.sh | sh

Otherwise, install the prebuilt binary directly for your architecture. The script above will install for the correct architecture automatically.

Symlink locket binary to docker-locket as a Docker CLI Plugin

1. Confirm locket is installed with locket --version
2. Make sure a cli-plugins directory exists mkdir -p ~/.docker/cli-plugins
3. Symlink locket -> cli-plugins/locket ln -sf $(which locket) ~/.docker/cli-plugins/docker-locket
4. Confirm docker sees it. docker info | grep locket

Orchestration

Process orchestration is achievable via the locket exec command, which allows locket to act as a parent process / supervisor for a specified subcommand. It resolves secrets from your templates or .env files and injects them directly into the environment of a subprocess.

Optionally, the --watch flag can be provided so that locket will watch for changes to any .env files provided, and restart the child process or process group.

Full configuration reference available at docs/exec.md

[!IMPORTANT] locket must be installed on the host system to use this mode. Follow the steps here

Basic Usage

Simply wrap your command with locket exec. You can supply secrets via individual files, .env files, or inline arguments.

locket exec \
    --provider bws \
    --bws.token-file /path/to/token \
    --env .env \
    --env .env.override \
    --env MY_SECRET={{reference}}\
    -- docker compose up -d

Now, any provided env variables will be available to docker, so your compose can reference $MY_SECRET for example, and it will have the resolved secret available, without ever needing it on disk or in host environment.

Interactive Example

locket exec \
  --provider bws \
  --bws.token-file /etc/tokens/bws \
  -e MY_SECRET={{3832b656-a93b-45ad-bdfa-b267016802c3}} \
  -- python3

2025-12-14T19:29:10.126886Z  INFO Starting locket v0.14.0 `exec` service 
2025-12-14T19:29:10.708684Z  INFO resolving environment and starting process...
2025-12-14T19:29:10.709115Z  INFO batch fetching secrets count=1
2025-12-14T19:29:10.839831Z  INFO Spawning child process cmd=["python3"]
Python 3.11.2 (main, Apr 28 2025, 14:11:48) [GCC 12.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.environ["MY_SECRET"]
'ABB80C10E50A96B3CE9480D880B2CAED1A7D205A'
>>> 

Example: Hot-Reloading Traefik configurations with Secrets

Traefik supports Dynamic Configuration via files, which it watches for changes. By pairing Traefik with locket, you can inject secrets (like Dashboard credentials, TLS certificates, or middleware auth) into your configuration files and have Traefik hot-reload them automatically without a restart.

1. locket watches a local templates/ directory containing your Traefik config with {{ op://... }} placeholders.
2. When a template changes, locket atomically updates the file in the shared secrets-store volume.
3. Traefik detects the change in the shared volume and reloads its configuration without a restart.

So a snippet from ./templates/dynamic_conf.yaml might look like

http:
  middlewares:
    auth:
      basicAuth:
        users:
          - "{{ op://DevOps/Traefik/basic_auth_user }}"

  routers:
    dashboard:
      rule: "Host(`traefik.localhost`)"
      service: "api@internal"
      middlewares: ["auth"]
# Any other secrets can be included here too....

---
services:
  locket:
    image: ghcr.io/bpbradley/locket:op # Can use the 1pass specific tag
    container_name: locket
    user: "65532:65532" 
    environment:
      OP_SERVICE_ACCOUNT_TOKEN_FILE: /run/secrets/op_token
    secrets:
      - op_token
    command:
      - "--map=/templates:/run/secrets/locket"
      - "--mode=watch"
    volumes:
      - ./templates:/templates:ro
      - secrets-store:/run/secrets/locket

  traefik:
    image: traefik:v3
    container_name: traefik
    depends_on:
      locket:
        condition: service_healthy
    command:
      # Tell Traefik to watch the directory where locket writes
      - "--providers.file.directory=/etc/traefik/dynamic"
      - "--providers.file.watch=true"
      - "--api.dashboard=true"
    ports:
      - 80:80
      - 443:443
      - 8080:8080
    volumes:
      # Mount the SHARED volume where locket writes the 'real' config
      - secrets-store:/etc/traefik/dynamic:ro 
      - /var/run/docker.sock:/var/run/docker.sock:ro

secrets:
  op_token:
    file: /etc/op/token

volumes:
  # The bridge between locket and Traefik.
  # Using tmpfs ensures secrets never touch the disk.
  secrets-store:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs

Roadmap

Before v1.0.0

1. Have support for at least 4 providers
2. Templating Engine: Adding attributes to the secret reference which can transform secrets before injection. For example {{ secret_reference | base64 }} to encode the secret as base64, or {{ secret_reference | totp }} to interpret the secret as a totp code.

Beyond

1. Docker Engine Plugin: Support for locket as a native Docker Engine plugin will allow direct creation of Docker volumes using locket.
2. Swarm Operator: Native integration for Docker Swarm secrets.