Skip to content

SecretSpec

SecretSpec separates secret declaration from secret provisioning. You define the secrets that your application needs in a secretspec.toml file and each developer, CI system, and production environment can provide those secrets from their preferred secure provider.

Quick Start

Follow the SecretSpec quickstart guide.

Runtime Loading (Best Practice)

While you can enable SecretSpec in devenv to load secrets into the secretspec.secrets option, we recommend that you:

a) Use the Rust SDK to load secrets in your application code

b) Load secrets at runtime and expose them only to the processes that need them

$ devenv shell
$ secretspec run -- npm start

This approach:

  • Keeps secrets out of your shell environment
  • Reduces exposure of sensitive data
  • Makes secret rotation easier
  • Follows the principle of least privilege

Configuration (Optional)

If you do need secrets in your devenv environment, you can configure via devenv.yaml or CLI flags.

Via CLI flags (devenv 2.0+)

Override the provider and profile directly from the command line:

$ devenv --secretspec-provider dotenv --secretspec-profile dev shell

This automatically enables secretspec. You can also use environment variables:

$ SECRETSPEC_PROVIDER=dotenv SECRETSPEC_PROFILE=dev devenv shell

Via devenv.yaml

devenv.yaml
secretspec:
  enable: true
  provider: keyring  # keyring, dotenv, env, 1password, lastpass
  profile: default   # profile from secretspec.toml

CLI flags take precedence over devenv.yaml values.

Then access in devenv.nix:

devenv.nix
{ config, ... }:

{
  env.DATABASE_URL = config.secretspec.secrets.DATABASE_URL or "";
}

Cachix auth token

New in version 2.2

To make the Cachix auth token a built-in required secret, without declaring it in secretspec.toml, set secretspec.cachix_auth_token to true:

devenv.yaml
secretspec:
  enable: true
  provider: keyring
  cachix_auth_token: true

This uses the secret name CACHIX_AUTH_TOKEN. If your provider's policy (e.g. an OpenBao/Vault policy) only grants access to a secret under a different name, set the option to that name:

devenv.yaml
secretspec:
  enable: true
  provider: openbao
  cachix_auth_token: MY_TEAM_CACHIX_TOKEN

The string is the secret name, not the token itself. Set the option to false or omit it to disable the built-in requirement. Only the SecretSpec lookup is renamed: the environment variable and the Cachix push daemon still use CACHIX_AUTH_TOKEN, which is what the Cachix CLI reads.

Learn More