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 from a non-default secret name

When resolving the Cachix auth token from secretspec, devenv looks up a secret named CACHIX_AUTH_TOKEN by default. If your provider's policy (e.g. an OpenBao/Vault policy) only grants you access to a secret under a different name, set secretspec.cachix_auth_token to that name:

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

The value is a secret name declared in secretspec.toml, not the token itself. Only the secretspec lookup is overridable: the environment variable and the cachix push daemon still use CACHIX_AUTH_TOKEN (that is what the Cachix CLI reads).

Learn More