Skip to main content
Last Reviewed: 2026-06-15

Local Development Usage

Developing locally presents some unique challenges once Pantheon Secrets are built into your workflow. These are some tips to help you get past struggling with trying to reproduce secret behavior while developing locally.

Discuss in Slack
Edit this page on GitHub Report an issue with this doc

Local Environment Usage

The Pantheon Secrets SDK includes a CustomerSecretsFakeClient implementation that is used when the SDK runs outside of Pantheon infrastructure. This client uses a secrets JSON file to build the secrets information emulating what happens on the platform using the Secrets service.

To get this file, use the terminus secret:site:local-generate command and then set an environment variable in your local environment (or Docker container) named CUSTOMER_SECRETS_FAKE_FILE with the absolute path to the file as the value.

  1. To generate this file, run terminus secret:site:local-generate in your terminal in your project root:

    Replace <site> with your Pantheon site name. The secrets.json file will be generated in your project root.

  2. Once you have the secrets.json, add it to your .gitignore so you do not accidentally commit it to your repository.

Lando configuration

  1. Modify your .lando.yml:

  2. Rebuild your Lando application:

DDEV configuration

  1. Navigate to your DDEV root directory.

  2. Add to your .ddev/config.yml:

  3. Restart your DDEV environment:

Verifying Secrets Access

Local Development Function

The pantheon_get_secret() function only works on Pantheon's infrastructure, not in local development. For local development, you can create a helper function that mimics the pantheon_get_secret() function. To do this, you can use the Pantheon Customer Secrets SDK. This SDK mirrors the code that is already integrated into the platform. The easiest way to install the Customer Secrets SDK locally is via Composer:

Once you have the SDK locally, you can create a local version of pantheon_get_secret using the SDK:

This approach allows your code to work seamlessly both on Pantheon (where pantheon_get_secret() is natively available) and in local development (where you provide your own implementation).

Drupal-Specific

If using Drupal with the Key module and Pantheon Secrets module:

  1. Go to the Key module configuration.
  2. Click the Sync Pantheon Secrets tab.
  3. Click Sync Keys.
  4. Your secrets from the JSON file should appear in the available list of keys.

Restrictions

For secrets without "user" scope, the secret:site:local-generate command will set the value of the secret to "null". You must manually set test values in your local secrets.json file.