Headless: WSL, Docker, CI
How to open a SourceOrrery vault where this machine's key is not available or there is no terminal, using the vault's recovery key from a file and the SOURCEORRERY_HOME directory.
On a desktop, the OS credential store keeps this machine’s key to the vault and opens it without a prompt. Linux programs in WSL cannot use Windows Credential Manager, and containers and CI runners usually have no usable credential store, or not the one that holds this machine’s key. There the vault opens with its recovery key, shown once when the vault was made, supplied from a restricted file.
Project setup options
Section titled “Project setup options”- Option 1: Set up with the CLI. Follow the CLI installation guide, then create the vault and set its secret values in your own terminal.
- Option 2: Set up with an AI coding agent. Run
sourceorrery init --integration all, then ask your agent to set up SourceOrrery for the project without showing values. You keep vault keys and new values private. The agent setup guide works with an existing CLI installation.
For either route, provision the vault and recovery-key file through your existing deployment controls. The agent does not handle the key or values.
How a vault opens
Section titled “How a vault opens”The CLI opens a vault with:
- this machine’s key in the OS credential store (Windows Credential Manager, macOS Keychain, Secret Service), with no prompt;
- otherwise the recovery key:
SOURCEORRERY_RECOVERY_KEYif set, else the file named by--recovery-key-fileorSOURCEORRERY_RECOVERY_KEY_FILE; - otherwise a hidden prompt on stderr when stdin is a terminal, up to three attempts.
Failed attempts are recorded in the audit log as vault_open / denied;
giving up is recorded as vault_open / failure. Nothing ever falls back to
an unprotected vault.
Both keys wrap the same vault key (see
Vault format), so a vault made on
Windows opens with its recovery key from WSL, Docker or CI. The vault’s
view check (a password, perhaps with an authenticator code) is asked
only when a person views the vault or reveals a value; run, check and
the SDKs never ask it, and a vault opened with its recovery key has passed
it.
The recovery key
Section titled “The recovery key”sourceorrery setup shows the recovery key once, behind a “written down”
tick; vault create prints it once, or writes it to a new file readable by
you only:
sourceorrery vault create development --recovery-key-out ~/.config/development.recovery-keyA vault for a pipeline only, with no key for this machine:
sourceorrery vault create ci --no-keyring --recovery-key-out ci.recovery-keyA lost recovery key is replaced on a machine that still opens the vault,
on the setup screens (sourceorrery vault create development, or c in
sourceorrery ui); the old one stops working in this file at once. A new
recovery key is not a new vault key, though: an old copy of the vault still
opens with the old key. If a key or a copy may be compromised, rotate the
exposed credentials and move to a new vault (threat model).
The Windows home directory is reachable from WSL, so point SOURCEORRERY_HOME
at it and give the recovery key from a file only you can read:
mkdir -p ~/.configinstall -m 600 /dev/null ~/.config/development.recovery-key# write the recovery key into it with your editor, thenexport SOURCEORRERY_HOME=/mnt/c/Users/me/AppData/Local/sourceorreryexport SOURCEORRERY_RECOVERY_KEY_FILE=~/.config/development.recovery-keysourceorrery checksourceorrery run --vault development -- ./appWithout the variable, each command prompts for the recovery key. Use a
Linux build of sourceorrery to launch Linux applications inside WSL. A
build with --no-default-features is enough for that; it omits the OS
credential store, the screens (ui, setup, init’s) and the providers.
Docker
Section titled “Docker”Build the CLI without the credential store, since a container has no Secret Service, and give the container two things: the home directory that holds the vault file, and the recovery key as a file.
FROM rust:1.91.1-bookworm AS buildWORKDIR /srcCOPY . .RUN cargo build --release --locked -p sourceorrery-cli --no-default-features
FROM debian:bookworm-slimCOPY --from=build /src/target/release/sourceorrery /usr/local/bin/sourceorreryENV SOURCEORRERY_HOME=/var/lib/sourceorreryFor secrets the vault keeps at HashiCorp Vault, AWS Secrets Manager or
Azure Key Vault, build with --no-default-features --features remote
instead.
Mount the vault directory read-write (every access appends an audit row) and pass the recovery key through a file rather than an environment variable:
docker run --rm \ -v "$HOME/.local/share/sourceorrery:/var/lib/sourceorrery" \ -v "$PWD/sourceorrery.toml:/app/sourceorrery.toml:ro" \ -v "$HOME/.config/development.recovery-key:/run/secrets/recovery-key:ro" \ -w /app my-image \ sourceorrery --recovery-key-file /run/secrets/recovery-key checkBuild my-image from the Dockerfile above in the SourceOrrery repository.
The final image contains the CLI only. To run an application, add that
application and its runtime to the image, then replace check with
run -- <your application's command>. Keep build and runtime images on the
same Debian release so the compiled binary has compatible system libraries.
With Docker Compose or Swarm, declare the recovery key under secrets: and
it appears at /run/secrets/<name> in the container, which is exactly what
--recovery-key-file expects.
SOURCEORRERY_RECOVERY_KEY works but environment variables are visible to
process inspection, so prefer a file. In GitHub Actions, store the recovery
key as a repository secret and write it to the runner’s temporary directory
for the length of the job:
- name: Provide the vault's recovery key shell: bash run: | umask 077 printf '%s' "$VAULT_RECOVERY_KEY" > "$RUNNER_TEMP/recovery-key" env: VAULT_RECOVERY_KEY: ${{ secrets.VAULT_RECOVERY_KEY }}
- name: Check the manifest resolves shell: bash run: sourceorrery --recovery-key-file "$RUNNER_TEMP/recovery-key" check
- name: Deploy with secrets in the environment shell: bash run: sourceorrery --recovery-key-file "$RUNNER_TEMP/recovery-key" run -- ./deploy.sh
- name: Remove the recovery key file if: always() shell: bash run: rm -f -- "$RUNNER_TEMP/recovery-key"These steps assume the CLI is installed, the repository is checked out and
the runner can access a provisioned vault. check reads metadata only and
writes no secret_get audit rows, but its open and inspection operations
are still audited. run resolves every entry and starts the command with
the values in its environment; a missing required secret aborts before the
command starts.
For a local vault, the file itself has to reach the runner. *.sorvault
is gitignored on purpose; do not commit one. Use a self-hosted runner with
a persistent home directory, or a container image or volume provisioned
with a copy of the vault: sourceorrery vault export --out FILE writes
one that opens with the recovery key only, and vault import FILE brings
it onto a machine. A secret the vault keeps at a provider
(providers) is read there through the vault’s connection,
with the credentials the connection stores or the provider’s own sign-in
on the runner, so only the vault’s catalog travels with the file.