Runtime configuration without committing .env files, Kimen

Start with the interface the receiving program expects.

Kimen can project a vault value as an environment variable, a temporary file, command stdin or persistent rendered output. Choose the narrowest form the receiving software already understands.

The projection changes delivery, not trust. Whichever process receives the value can read and copy it.

Use environment variables for ordinary application config.

Declare the names expected by the application:

# .kimen/profiles/dev.kmap
env DATABASE_URL=dev.database_url
env PORT=const:8080

kimen run --profile dev -- ./app

Kimen starts ./app with both names in its environment. DATABASE_URL comes from the vault and PORT is a safe project-owned constant. The parent shell does not receive either export.

Use a temporary file when the program expects a path.

file materializes a value inside Kimen's private temporary directory. envpath gives the child process the resulting path:

# .kimen/profiles/provider.kmap
file credentials.json=provider.credentials_json
envpath PROVIDER_CREDENTIALS=credentials.json

kimen run --profile provider -- ./worker

The worker reads PROVIDER_CREDENTIALS and opens the file. Kimen removes the temporary directory after the child process exits.

Use stdin when the command consumes one private payload.

# .kimen/profiles/request.kmap
stdin request.body

kimen run --profile request -- \
  curl --data-binary @- https://example.internal/import

The selected value becomes the child's standard input. It is not added to the command arguments or parent environment.

Persistent output has a different lifecycle.

Some process managers and deployment systems require a file which outlives the Kimen command. Render it explicitly:

kimen envfile --out ./runtime/worker.env \
  --env DATABASE_URL=worker.database_url

kimen render --dir ./runtime/provider \
  --file credentials.json=provider.credentials_json

These files contain plaintext by necessity. Restrict their directory, keep it outside Git and remove or replace the files when the receiving service no longer needs them. Kimen does not automatically clean persistent output created by envfile or render.

Inspect the contract before running the program.

kimen map lint --profile dev --strict
kimen plan --profile dev
kimen doctor --profile dev

map lint checks the map structure. plan shows what will be projected without revealing the values. doctor also opens the vault and verifies that every referenced key exists.

Use short sessions for several invocations.

A Kimen session avoids typing the vault passphrase for every command:

kimen session start --ttl 15m
kimen run --profile dev -- ./app
kimen session lock

An active session widens the local boundary. A process running as the same operating-system user may be able to use the session. Prefer a short lifetime and keep the vault locked while untrusted same-user tools have unrestricted access.

For the storage problem behind this model, read why .env files are not a complete secrets strategy.

For the product choice, compare Kimen with 1Password and cloud secret managers. Kimen's reason to exist is local, open-source and account-free operation with project-declared projection, not that other secret systems cannot start a process.

Runtime configuration without committing `.env` files