Skip to content
Hush

Getting Started

Get up and running with Hush in just a few minutes.

Prerequisites

Hush requires Node.js 18+ and delegates encryption to standard tools.

  1. SOPS - The standard for secret operations
  2. age - Modern, simple key management
  3. direnv - Automatic environment loading (for per-project keys)
Terminal window
brew install sops age direnv


# Add direnv hook to your shell (add to ~/.zshrc or ~/.bashrc)
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc   # for zsh
# or: echo 'eval "$(direnv hook bash)"' >> ~/.bashrc   # for bash


# Reload your shell
source ~/.zshrc

Installation

Terminal window
pnpm add -D @chriscode/hush

Setup

  1. Generate an age key

    Create a key pair for encrypting your secrets:

    Terminal window
    mkdir -p ~/.config/sops/age
    age-keygen -o ~/.config/sops/age/key.txt

    This creates a private key at ~/.config/sops/age/key.txt. The public key is printed to the console.

  2. Create .sops.yaml

    In your repository root, create a SOPS configuration file:

    .sops.yaml
    creation_rules:
      - encrypted_regex: '.*'
        age: age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    Replace the age: value with your public key from step 1.

  3. Initialize Hush

    Run the init command to create hush.yaml:

    Terminal window
    npx hush init

    This auto-detects packages in your monorepo and creates a configuration file.

  4. Create your source files

    Terminal window
    # .hush (shared across environments)
    DATABASE_URL=postgres://localhost/mydb
    STRIPE_SECRET_KEY=sk_test_xxx
    EXPO_PUBLIC_API_URL=${API_BASE}/v1
    

    # .hush.development
    API_BASE=http://localhost:8787
    

    # .hush.production
    API_BASE=https://api.example.com

  5. Encrypt

    Terminal window
    npx hush encrypt

    This creates encrypted versions of your source files (.hush.encrypted, etc.) that are safe to commit.

  6. Set up direnv for key loading

    Create a .envrc file in your project root:

    .envrc
    export SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys/YOUR_PROJECT.txt"

    Replace YOUR_PROJECT with your project identifier (visible in npx hush status under “Local key”).

    Then allow direnv to load it:

    Terminal window
    direnv allow

  7. Run with secrets

    Terminal window
    npx hush run -- npm start

    This decrypts secrets to memory and runs your command with them as environment variables. Secrets never touch the disk!

Verify Your Setup

Check that everything is configured correctly:

Terminal window
npx hush status

This shows your configuration, encrypted files, and target distribution.

Troubleshooting

”no identity matched any of the recipients”

This is the most common error. It means SOPS can’t find your decryption key.

Most likely cause: direnv isn’t loaded.

Terminal window
# 1. Check that direnv is allowed
direnv allow


# 2. Verify the environment variable is set
echo $SOPS_AGE_KEY_FILE   # Should show the path to your key file


# 3. Test decryption
npx hush status
npx hush inspect

If SOPS_AGE_KEY_FILE is empty, make sure you’ve:

  1. Installed direnv and added the hook to your shell
  2. Reloaded your shell (source ~/.zshrc or open a new terminal)
  3. Run direnv allow in the project directory

”age key not found”

The key file doesn’t exist. Either:

  • Run npx hush keys setup to pull from 1Password
  • Get the key from a team member and save it to the path shown in npx hush status

Next Steps