Skip to main content
For a container you control, choose the token-and-instructions path in capy deploy. It emits SECRETS_BLOB and PROJECT_KEY. Put both in the container environment and make capy run the entrypoint.

Install Capy in the image

The npm package is the simplest choice for a Node application:
For an image that does not otherwise need Node, install the released native binary in a build stage. Each release publishes its own installer with that version’s checksums. It selects the binary for the platform and checks its SHA-256 before installing. It never falls back to npm.
Only the executable is copied into the final image. Exclude .env, .env.pre-capy.old, and local Capy state from the image with .dockerignore. Build the image without the runtime pair. Supply it when the container starts:
/etc/my-app/capy-runtime.env should contain only deployment configuration and be readable by the account that starts the container:

Laravel and other PHP apps

The setup is the same for any app: install Capy in the image, give the container the deploy values when it starts, and start the app with capy run --. A PHP image needs no Node. Install Capy with the standalone installer:
capy run sets the values in the environment of the command it starts.

What the container needs

Run capy deploy --platform docker on a machine where you are signed in. It gives you SECRETS_BLOB and PROJECT_KEY. Put both in the container environment, as in the docker run --env-file example above. capy run also reads _SECRETS_BLOB and _PROJECT_KEY. Set both values of a pair, or neither. Deployed mode needs no sign-in on the container. capy info, a capy run without a runtime pair, and the comparison in capy status need a Capy sign-in on that machine.

If the Capy service cannot be reached

capy run contacts the Capy service once when the container starts. If it cannot reach the service within 30 seconds, it prints capy run: Cannot reach Capy service for deploy decrypt at <service URL>. and exits with code 1. It does not retry, and your app does not start. If the service answers with an error instead, capy run prints capy run: Deploy decrypt failed (<HTTP status>), or capy run: Deploy token not found when the status is 404. Both exit with code 1 and your app does not start.

Compose and Kubernetes

Keep the pair outside the application repository. For Compose, point at an externally managed env file:
For Kubernetes, create or update a cluster secret through your normal secret-management workflow and inject it into the container:
The image entrypoint decrypts at container startup, then starts the child process. It contacts the Capy service once at that point and does not read local .env in deployed mode. With the emitted SECRETS_BLOB / PROJECT_KEY names, any same-named variable already present in the container takes precedence; remove stale plaintext duplicates when the Capy value must be used.

Start a Compose stack only through capy run

capy run sets CAPY_RUN=1 for the command it starts. Require it in the Compose file:
Start the stack with capy run -- docker compose up. Started any other way, Compose stops and prints the message after :?.

Updates and revocation

Create a distinct pair for each environment. When values change, mint a new pair from the correct Capy branch, update the external secret store, and restart the workload. Revoke unused pairs with capy deploy revoke <deploy-id>; already-running containers retain their environment until they restart.

Running your app

Runtime-pair mode detection and precedence.
Last modified on November 20, 2026