@lockzero/docker

Inject LockZero vault secrets into Docker commands at runtime. Secrets are fetched live from the LockZero API and passed to Docker subprocesses — never written to disk or committed to source control.

Installation

npm install -g @lockzero/docker
# or run without installing:
npx @lockzero/docker <command>

Authentication

Set your LockZero API key as an environment variable:

export LOCKZERO_API_KEY=lz_live_...

Or pass it directly with --api-key.

Commands

run — Inject secrets into a container at runtime

lockzero-docker run --namespace openai,stripe -- docker run myimage
lockzero-docker run -n openai -n stripe -- docker run -it ubuntu bash

Secrets are injected as -e KEY=VALUE flags. They live only in the container's environment — never written to disk.

build — Inject secrets as build args

lockzero-docker build --namespace openai -- docker build -t myimage .

Warning: Build args appear in image layer metadata. Use --no-warn to suppress the warning. Prefer run for production secrets.

compose — Inject secrets into docker compose

lockzero-docker compose --namespace openai,stripe -- docker compose up -d
lockzero-docker compose -n db -- docker compose run --rm migrate

Secrets are exported into the child process environment. Reference them in docker-compose.yml via ${MY_SECRET} substitution or environment: mappings.

export — Print secrets to stdout

lockzero-docker export --namespace openai --format dotenv > .env
lockzero-docker export --namespace openai,stripe --format json
lockzero-docker export --namespace db --format env | source /dev/stdin

Available formats: dotenv (default), env (export KEY=VALUE), json.

Warning: Output contains plaintext secrets. Never commit to source control.

Options

All commands accept:

| Option | Default | Description | |--------|---------|-------------| | -n, --namespace <ns> | required | Namespace(s) to fetch. Repeat flag or comma-separate. | | --api-key <key> | $LOCKZERO_API_KEY | LockZero API key | | --base-url <url> | https://api.lockzero.io | API base URL | | --verbose | false | Print fetch progress to stderr |

Examples

See examples/ for:

• docker-compose.yml — compose file referencing LockZero-injected variables
• Dockerfile.example — multi-stage build using build args safely

Security Notes

• Secrets are fetched from LockZero at command invocation time and passed directly to the subprocess. They are not written to disk.
• With run, secrets live only in the container's environment. They are not in the image layers.
• With build, secrets appear in image layer metadata. Use multi-stage builds and avoid embedding build args in the final stage.
• The export command outputs plaintext — treat output files like passwords.