Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cachix/devenv/llms.txt

Use this file to discover all available pages before exploring further.

SecretSpec separates secret declaration from secret provisioning. You define the secrets your application needs in a secretspec.toml file, and each developer, CI system, and production environment can supply those secrets from their own preferred secure provider — keyring, 1Password, dotenv, environment variables, and more — without any changes to your application code.

​
Quick start

Follow the SecretSpec quickstart guide to create your first secretspec.toml and connect a provider.

​
Runtime loading (best practice)

The recommended way to use SecretSpec with devenv is to load secrets at runtime, scoped only to the processes that need them: 
$ devenv shell
$ secretspec run -- npm start
Running secretspec run inside the devenv shell keeps secrets out of your broader shell environment and limits exposure to only the processes that actually require them.
This approach:
  • Keeps secrets out of your shell environment
  • Reduces exposure of sensitive data
  • Makes secret rotation easier
  • Follows the principle of least privilege
You can also load secrets directly in your application using the Rust SDK for type-safe secret access.

​
Configuration (optional)

If you need secrets available in the devenv shell environment itself, you can enable SecretSpec via CLI flags or devenv.yaml.

​
Via CLI flags (devenv 2.0+)

Override the provider and profile directly on the command line: 
$ devenv --secretspec-provider dotenv --secretspec-profile dev shell
Passing either flag automatically enables SecretSpec. You can also use environment variables: 
$ SECRETSPEC_PROVIDER=dotenv SECRETSPEC_PROFILE=dev devenv shell

​
Via 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.

​
Accessing secrets in devenv.nix

Once SecretSpec is enabled, loaded secrets are available under config.secretspec.secrets: 
{ 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 access to a secret under a different name, set secretspec.cachix_auth_token to that name: 
secretspec:
  enable: true
  provider: openbao
  cachix_auth_token: MY_TEAM_CACHIX_TOKEN
cachix_auth_token is a secret name declared in secretspec.toml, not the token value itself. The environment variable and the cachix push daemon still use CACHIX_AUTH_TOKEN — that is what the Cachix CLI reads.

​
Learn more

Build docs developers (and LLMs) love

Get started for freeTalk to us