🔐 fnox

Fort Knox for your secrets.

What is fnox?

Secrets are done in 2 ways:

In git, encrypted (hopefully)
Remote, typically a cloud provider like AWS KMS

fnox works with either—or both! They've got their pros and cons. Either way, fnox gives you a nice front-end to manage secrets and make them easy to work with in dev/ci/prod.

fnox's config file, fnox.toml, will either contain the encrypted secrets, or a reference to a secret in a cloud provider. You can either use fnox exec -- <command> to run a command with the secrets, or you can use the shell integration to automatically load the secrets into your shell environment when you cd into a directory with a fnox.toml file.

Supported Providers

fnox works with all the things:

🔐 Encryption (secrets in git, encrypted)

age - Modern encryption (works with SSH keys!)
aws-kms - AWS Key Management Service
azure-kms - Azure Key Vault encryption
gcp-kms - Google Cloud KMS

☁️ Cloud Secret Storage (remote, centralized)

aws-sm - AWS Secrets Manager
azure-sm - Azure Key Vault Secrets
gcp-sm - Google Cloud Secret Manager
vault - HashiCorp Vault

🔑 Password Managers

1password - 1Password CLI
bitwarden - Bitwarden/Vaultwarden

💻 Local Storage

keychain - OS Keychain (macOS/Windows/Linux)
plain - Plain text (for defaults only!)

Installation

Using mise (recommended)

The easiest way to install fnox is with mise:

mise use -g fnox

Using Cargo

cargo install fnox

From Source

git clone https://github.com/jdx/fnox
cd fnox
cargo install --path .

Quick Start

# Initialize fnox in your project
fnox init

# Set a secret (stores it encrypted in fnox.toml)
fnox set DATABASE_URL

# Get a secret
fnox get DATABASE_URL

# Run commands with secrets loaded as env vars
fnox exec -- npm start

# Enable shell integration (auto-load secrets on cd)
eval "$(fnox activate bash)"  # or zsh, fish

How It Works

fnox uses a simple TOML config file (fnox.toml) that you check into git. Secrets are either:

Encrypted inline - The encrypted ciphertext lives in the config file
Remote references - The config contains a reference (like "my-db-password") that points to a secret in AWS/1Password/etc.

You configure providers (encryption methods or cloud services), 7F9 then assign each secret to a provider. fnox handles the rest.

# fnox.toml
[providers.age]
type = "age"
recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]

[secrets.DATABASE_URL]
provider = "age"
value = "YWdlLWVuY3J5cHRpb24uLi4="  # ← encrypted ciphertext, safe to commit

[secrets.API_KEY]
default = "dev-key-12345"  # ← plain default value for local dev

When you run fnox get DATABASE_URL, it decrypts the value using your age key. When you run fnox exec, all secrets are loaded as environment variables.

Shell Integration

fnox can automatically load secrets when you cd into directories with a fnox.toml file:

# Enable it once
eval "$(fnox activate bash)"  # or zsh, fish

# Add to your shell config for persistence
echo 'eval "$(fnox activate bash)"' >> ~/.bashrc

Now secrets auto-load on directory changes:

~/projects $ cd my-app
fnox: +3 DATABASE_URL, API_KEY, JWT_SECRET
~/projects/my-app $ cd ..
fnox: -3 DATABASE_URL, API_KEY, JWT_SECRET

Control the output with FNOX_SHELL_OUTPUT:

export FNOX_SHELL_OUTPUT=none - Silent mode
export FNOX_SHELL_OUTPUT=normal - Show count and keys (default)
export FNOX_SHELL_OUTPUT=debug - Verbose debugging

Use profiles for different environments:

export FNOX_PROFILE=production
cd my-app  # Loads production secrets

Why is this a standalone CLI and not part of mise?

mise has support for encrypted secrets but mise's design makes it a poor fit for remote secrets. mise reloads its environment too frequently—whenever a directory is changed, mise x is run, a shim is called, etc. Any other use-case like this mise leverages caching but secrets are an area where caching is a bad idea for obvious reasons. It might be possible to change mise's design to retain its environment in part to better support something like this but that's a huge challenge.

Basically it's just too hard to get remote secrets to work effectively with mise so I made this a standalone tool.

Providers: Complete Getting Started Guides

Each provider below is a complete standalone guide. Choose the ones that fit your workflow.

Age Encryption

Use age when: You want secrets in git, encrypted, with minimal setup. Perfect for development secrets, open source projects, or teams that want secrets in version control.

What is age? A modern encryption tool by @FiloSottile. It's simple, secure, and works beautifully with SSH keys you already have.

Setup

Generate an age key (or use your existing SSH key):

# Option 1: Generate a new age key
age-keygen -o ~/.config/fnox/age.txt

# Option 2: Use your existing SSH key (recommended!)
# age can encrypt to SSH keys directly, no conversion needed

Get your public key (for encrypting secrets):

# If you generated an age key:
grep "public key:" ~/.config/fnox/age.txt
# Output: age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# If using SSH key:
ssh-keygen -Y find-principals -s ~/.ssh/id_ed25519.pub
# Or just use the SSH public key directly!

Configure fnox:

fnox init

# Add the age provider (use your public key)
cat >> fnox.toml << 'EOF'
[providers.age]
type = "age"
recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]
# Or for SSH key:
# recipients = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA..."]
EOF

Set the decryption key (your private key):

# If using age key:
export FNOX_AGE_KEY=$(cat ~/.config/fnox/age.txt | grep "AGE-SECRET-KEY")

# If using SSH key:
export FNOX_AGE_KEY_FILE=~/.ssh/id_ed25519

# Add to your shell profile for persistence:
echo 'export FNOX_AGE_KEY_FILE=~/.ssh/id_ed25519' >> ~/.bashrc

Usage

# Encrypt and store a secret (automatically uses age provider)
fnox set DATABASE_URL "postgresql://localhost/mydb" --provider age

# The resulting fnox.toml looks like:
# [secrets.DATABASE_URL]
# provider = "age"
# value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+I..."  # ← encrypted, safe to commit!

# Retrieve and decrypt
fnox get DATABASE_URL

# Run commands with decrypted secrets
fnox exec -- npm run dev

SSH Key Support

age has first-class support for SSH keys! Instead of managing separate age keys, just use your existing SSH keys:

# Encrypt to your SSH public key
[providers.age]
type = "age"
recipients = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGQs..."]

# Decrypt with your SSH private key
export FNOX_AGE_KEY_FILE=~/.ssh/id_ed25519

Works with ssh-ed25519 and ssh-rsa keys. For teams, add multiple recipients:

[providers.age]
type = "age"
recipients = [
  "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGQs... # alice",
  "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBws... # bob",
  "age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2el... # ci-bot"
]

Now Alice, Bob, and your CI system can all decrypt the secrets!

Team Workflow

Everyone generates/shares public keys (age or SSH)
Add all public keys to recipients array in fnox.toml
Commit fnox.toml to git (contains encrypted secrets)
Each person sets their private key via FNOX_AGE_KEY or FNOX_AGE_KEY_FILE
Everyone can decrypt secrets ✨

Pros:

Secrets live in git (version control, code review)
Works offline
Zero runtime dependencies
Free forever

Cons:

Key rotation requires re-encrypting all secrets
No audit logs
No centralized access control

1Password

Use 1Password when: Your team already uses 1Password, or you want a polished password manager experience with great audit logs and access control.

Prerequisites

1Password account
1Password CLI installed: brew install 1password-cli

Setup

Create a service account in 1Password:
- Go to your 1Password account settings
- Create a service account with read access to your vault
- Copy the OP_SERVICE_ACCOUNT_TOKEN
Store the token (bootstrap with age!):

# First, set up age encryption (see age section above)
fnox init
# ... configure age provider ...

# Store the 1Password token encrypted in fnox
fnox set OP_SERVICE_ACCOUNT_TOKEN "ops_YOUR_TOKEN_HERE" --provider age

# Now you can bootstrap the token from fnox itself:
export OP_SERVICE_ACCOUNT_TOKEN=$(fnox get OP_SERVICE_ACCOUNT_TOKEN)

Configure 1Password provider:

cat >> fnox.toml << 'EOF'
[providers.onepass]
type = "1password"
vault = "Development"  # Your vault name
account = "my.1password.com"  # Optional
EOF

Add secrets to 1Password (via 1Password app or CLI):

# Create an item in 1Password
op item create --category=login \
  --title="Database" \
  --vault="Development" \
  password="super-secret-password"

Reference secrets in fnox:

cat >> fnox.toml << 'EOF'
[secrets.DATABASE_URL]
provider = "onepass"
value = "Database"  # ← Item name in 1Password (fetches 'password' field)

[secrets.DB_USERNAME]
provider = "onepass"
value = "Database/username"  # ← Specific field

[secrets.API_KEY]
provider = "onepass"
value = "op://Development/API Keys/credential"  # ← Full op:// URI
EOF

Usage

# Export the token (one-time per session)
export OP_SERVICE_ACCOUNT_TOKEN=$(fnox get OP_SERVICE_ACCOUNT_TOKEN)

# Get secrets from 1Password
fnox get DATABASE_URL

# Run commands with 1Password secrets
fnox exec -- ./deploy.sh

Reference Formats

"item-name" → Gets the password field
"item-name/field" → Gets a specific field (username, password, etc.)
"op://vault/item/field" → Full 1Password reference URI

Pros:

Beautiful UI, great mobile apps
Excellent audit logs and access control
No encryption key management
Team-friendly

Cons:

Requires 1Password subscription
Requires network access
Service account token management

Bitwarden

Use Bitwarden when: You want an open-source password manager, or you're already using Bitwarden/Vaultwarden.

Prerequisites

Bitwarden account (or self-hosted Vaultwarden)
Bitwarden CLI (automatically installed via mise)

Setup

Login to Bitwarden:

# Login
bw login

# Unlock and get session token
export BW_SESSION=$(bw unlock --raw)

Store the session token (optional, for bootstrap):

# Store encrypted with age
fnox set BW_SESSION "$(bw unlock --raw)" --provider age

# Next time, bootstrap from fnox:
export BW_SESSION=$(fnox get BW_SESSION)

Configure Bitwarden provider:

cat >> fnox.toml << 'EOF'
[providers.bitwarden]
type = "bitwarden"
collection = "my-collection-id"  # Optional
organization_id = "my-org-id"    # Optional
EOF

Add secrets to Bitwarden (via Bitwarden app or CLI):

# Create an item
bw create item --name "Database" --username "admin" --password "secret"

Reference secrets in fnox:

cat >> fnox.toml << 'EOF'
[secrets.DATABASE_URL]
provider = "bitwarden"
value = "Database"  # ← Item name (fetches 'password' field)

[secrets.DB_USERNAME]
provider = "bitwarden"
value = "Database/username"  # ← Specific field
EOF

Usage

# Unlock Bitwarden (once per session)
export BW_SESSION=$(bw unlock --raw)
# Or bootstrap: export BW_SESSION=$(fnox get BW_SESSION)

# Get secrets
fnox get DATABASE_URL

# Run commands
fnox exec -- npm start

Reference Formats

"item-name" → Gets the password field
"item-name/field" → Gets specific field (username, password, notes, uri, totp)

Testing with Vaultwarden

For local development without a Bitwarden account:

# Start local vaultwarden server
source ./test/setup-bitwarden-test.sh

# Follow on-screen instructions to create account and login

Pros:

Open source
Free for personal use
Self-hosting option (Vaultwarden)
Good audit logs

Cons:

UI less polished than 1Password
Session token expires (need to unlock regularly)

AWS Secrets Manager

Use AWS Secrets Manager when: You're running on AWS infrastructure and want centralized secret management with IAM access control, audit logs, and automatic rotation.

Note: This is remote storage - secrets live in AWS, not in your config file. Your fnox.toml only contains references to the secret names.

Prerequisites

AWS account
AWS credentials configured (CLI, environment variables, or IAM role)
IAM permissions (see below)

Setup

Create IAM policy for secret access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListSecrets",
      "Effect": "Allow",
      "Action": "secretsmanager:ListSecrets",
      "Resource": "*"
    },
    {
      "Sid": "ReadSecrets",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:REGION:ACCOUNT:secret:myapp/*"
    }
  ]
}

Configure AWS credentials:

# Option 1: Environment variables
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

# Option 2: AWS CLI profile
aws configure

# Option 3: IAM role (if running on EC2/ECS/Lambda)
# Credentials are automatic!

Configure fnox provider:

cat >> fnox.toml << 'EOF'
[providers.aws]
type = "aws-sm"
region = "us-east-1"
prefix = "myapp/"  # Optional: prepended to all secret names
EOF

Create secrets in AWS Secrets Manager:

# Via AWS CLI
aws secretsmanager create-secret \
  --name "myapp/database-url" \
  --secret-string "postgresql://prod.db.example.com/mydb"

aws secretsmanager create-secret \
  --name "myapp/api-key" \
  --secret-string "sk_live_abc123xyz789"

Reference secrets in fnox:

cat >> fnox.toml << 'EOF'
[secrets.DATABASE_URL]
provider = "aws"
value = "database-url"  # ← With prefix, becomes "myapp/database-url"

[secrets.API_KEY]
provider = "aws"
value = "api-key"  # ← With prefix, becomes "myapp/api-key"
EOF

Usage

# Secrets are fetched from AWS on-demand
fnox get DATABASE_URL

# Run commands (fetches all secrets from AWS)
fnox exec -- ./start-server.sh

# Use different profiles for different environments
fnox exec --profile production -- ./deploy.sh

How It Works

Storage: Secrets live in AWS Secrets Manager (NOT in fnox.toml)
Config: fnox.toml contains only the secret name/reference
Retrieval: Running fnox get calls AWS API to fetch the current value
Prefix: If configured, the prefix is prepended (e.g., value = "db-url" → fetches myapp/db-url)

Pros:

Centralized secret management
IAM access control
CloudTrail audit logs
Automatic rotation support
Secrets never in git

Cons:

Requires AWS account and network access
Costs money ($0.40/secret/month + $0.05/10k API calls)
More complex setup than encryption

AWS KMS

Use AWS KMS when: You want secrets in git (encrypted), but with AWS-managed encryption keys and IAM access control. Different from Secrets Manager - this stores encrypted ciphertext in fnox.toml.

Note: This is local encryption - the encrypted ciphertext lives in your fnox.toml file. AWS KMS is only called to encrypt/decrypt.

Prerequisites

AWS account
AWS credentials configured
KMS key created
IAM permissions (see below)

Setup

Create KMS key:

# Via AWS CLI
aws kms create-key \
  --description "fnox secrets encryption" \
  --key-usage ENCRYPT_DECRYPT

# Note the KeyId from output

Or use AWS Console → KMS → Create Key.

Create IAM policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["kms:Decrypt", "kms:Encrypt", "kms:DescribeKey"],
      "Resource": "arn:aws:kms:REGION:ACCOUNT:key/KEY-ID"
    }
  ]
}

Configure AWS credentials (same as Secrets Manager above)
Configure fnox provider:

cat >> fnox.toml << 'EOF'
[providers.kms]
type = "aws-kms"
key_id = "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
region = "us-east-1"
EOF

Encrypt and store secrets:

# fnox calls AWS KMS to encrypt, then stores ciphertext in config
fnox set DATABASE_URL "postgresql://prod.example.com/db" --provider kms

# The resulting fnox.toml contains encrypted ciphertext:
# [secrets.DATABASE_URL]
# provider = "kms"
# value = "AQICAHhw...base64...ciphertext..."  # ← Encrypted, safe to commit!

Usage

# Decrypt (calls AWS KMS)
fnox get DATABASE_URL

# Run commands (decrypts all secrets)
fnox exec -- npm start

How It Works

Encryption (fnox set): Calls AWS KMS Encrypt API, stores base64 ciphertext in fnox.toml
Decryption (fnox get): Calls AWS KMS Decrypt API to recover plaintext
IAM Control: Access controlled via KMS key policies and IAM permissions

Pros:

Secrets in git (version control)
AWS-managed encryption keys
IAM access control and CloudTrail audit logs
No monthly per-secret charges

Cons:

Requires AWS account and network access
Costs money ($1/key/month + $0.03/10k operations)
More complex than age encryption

AWS KMS vs AWS Secrets Manager:

KMS: Encrypted secrets IN your fnox.toml (like age, but with AWS keys)
Secrets Manager: Secrets stored IN AWS, fnox.toml has references only

Azure Key Vault

Use Azure Key Vault when: You're on Azure and want centralized secret management.

Azure provides two services: Key Vault Secrets (remote storage) and Key Vault Keys (encryption). fnox supports both.

Azure Key Vault Secrets (Remote Storage)

Use when: You want secrets stored in Azure, not in git.

Prerequisites

Azure subscription
Key Vault created
Azure credentials configured
Permissions (see below)

Setup

Create Key Vault:

# Via Azure CLI
az keyvault create \
  --name "myapp-vault" \
  --resource-group "myapp-rg" \
  --location "eastus"

Assign permissions:

# Assign yourself access (for testing)
az keyvault set-policy \
  --name "myapp-vault" \
  --upn "your-email@example.com" \
  --secret-permissions get list

# Or use RBAC (recommended):
az role assignment create \
  --role "Key Vault Secrets User" \
  --assignee "user@example.com" \
  --scope "/subscriptions/SUB-ID/resourceGroups/myapp-rg/providers/Microsoft.KeyVault/vaults/myapp-vault"

Configure Azure authentication:

# Option 1: Azure CLI (for development)
az login

# Option 2: Service Principal (for CI/CD)
export AZURE_CLIENT_ID="..."
export AZURE_CLIENT_SECRET="..."
export AZURE_TENANT_ID="..."

# Option 3: Managed Identity (automatic on Azure VMs/Functions)
# No configuration needed!

Configure fnox provider:

cat >> fnox.toml << 'EOF'
[providers.azure]
type = "azure-sm"
vault_url = "https://myapp-vault.vault.azure.net/"
prefix = "myapp/"  # Optional
EOF

Create secrets in Key Vault:

# Via Azure CLI
az keyvault secret set \
  --vault-name "myapp-vault" \
  --name "myapp-database-url" \
  --value "postgresql://prod.example.com/db"

Reference secrets in fnox:

cat >> fnox.toml << 'EOF'
[secrets.DATABASE_URL]
provider = "azure"
value = "database-url"  # ← With prefix, becomes "myapp-database-url"
EOF

Usage

# Fetch from Azure Key Vault
fnox get DATABASE_URL

# Run commands
fnox exec -- ./app

Pros:

Centralized management
Azure RBAC integration
Audit logs
Managed rotation

Cons:

Requires Azure subscription
Costs money
Requires network access

Azure Key Vault Keys (Encryption)

Use when: You want secrets in git (encrypted), but with Azure-managed keys.

Setup

Create Key Vault with key:

az keyvault key create \
  --vault-name "myapp-vault" \
  --name "encryption-key" \
  --protection software

Assign crypto permissions:

az role assignment create \
  --role "Key Vault Crypto User" \
  --assignee "user@example.com" \
  --scope "/subscriptions/.../vaults/myapp-vault"

Configure fnox:

cat >> fnox.toml << 'EOF'
[providers.azurekms]
type = "azure-kms"
vault_url = "https://myapp-vault.vault.azure.net/"
key_name = "encryption-key"
EOF

Encrypt secrets:

# Encrypts with Azure Key Vault, stores ciphertext in fnox.toml
fnox set DATABASE_URL "secret-value" --provider azurekms

How it works: Similar to AWS KMS - ciphertext stored in config, Azure Key Vault only called for encrypt/decrypt operations.

Google Cloud Secret Manager

Use GCP Secret Manager when: You're on Google Cloud and want centralized secret management.

Like AWS, Google provides Secret Manager (remote storage) and Cloud KMS (encryption). fnox supports both.

GCP Secret Manager (Remote Storage)

Use when: You want secrets stored in GCP, not in git.

Prerequisites

GCP project
gcloud CLI or service account
IAM permissions (see below)

Setup

Enable Secret Manager API:

gcloud services enable secretmanager.googleapis.com

Configure authentication:

# Option 1: gcloud CLI (for development)
gcloud auth application-default login

# Option 2: Service Account (for CI/CD)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

# Option 3: Workload Identity (automatic on GKE)
# No configuration needed!

Grant IAM permissions:

# Grant yourself access
gcloud projects add-iam-policy-binding PROJECT-ID \
  --member="user:your-email@example.com" \
  --role="roles/secretmanager.secretAccessor"

Configure fnox provider:

cat >> fnox.toml << 'EOF'
[providers.gcp]
type = "gcp-sm"
project = "my-project-id"
prefix = "myapp/"  # Optional
EOF

Create secrets in Secret Manager:

# Via gcloud CLI
echo -n "postgresql://prod.example.com/db" | \
  gcloud secrets create myapp-database-url \
    --data-file=-

# Or via Console: https://console.cloud.google.com/security/secret-manager

Reference secrets in fnox:

cat >> fnox.toml << 'EOF'
[secrets.DATABASE_URL]
provider = "gcp"
value = "database-url"  # ← With prefix, becomes "myapp-database-url"
EOF

Usage

# Fetch from GCP
fnox get DATABASE_URL

# Run commands
fnox exec -- ./app

Pros:

Integrated with GCP IAM
Audit logs
Automatic replication
Versioning

Cons:

Requires GCP project
Costs money
Requires network access

Google Cloud KMS (Encryption)

Use when: You want secrets in git (encrypted), but with GCP-managed keys.

Setup

Create keyring and key:

# Enable Cloud KMS
gcloud services enable cloudkms.googleapis.com

# Create keyring
gcloud kms keyrings create "fnox-keyring" \
  --location="us-central1"

# Create key
gcloud kms keys create "fnox-key" \
  --keyring="fnox-keyring" \
  --location="us-central1" \
  --purpose="encryption"

Grant permissions:

gcloud kms keys add-iam-policy-binding "fnox-key" \
  --keyring="fnox-keyring" \
  --location="us-central1" \
  --member="user:your-email@example.com" \
  --role="roles/cloudkms.cryptoKeyEncrypterDecrypter"

Configure fnox:

cat >> fnox.toml << 'EOF'
[providers.gcpkms]
type = "gcp-kms"
project = "my-project-id"
location = "us-central1"
keyring = "fnox-keyring"
key = "fnox-key"
EOF

Encrypt secrets:

# Encrypts with GCP KMS, stores ciphertext in fnox.toml
fnox set DATABASE_URL "secret-value" --provider gcpkms

How it works: Similar to AWS KMS - ciphertext in config, KMS only for encrypt/decrypt.

HashiCorp Vault

Use Vault when: You're already running Vault, or you need advanced features like dynamic secrets, secret leasing, or complex access policies.

Prerequisites

Vault server running (self-hosted or HCP Vault)
Vault CLI installed: brew install vault
Vault token with appropriate policies

Setup

Configure Vault access:

# Set Vault address
export VAULT_ADDR="https://vault.example.com:8200"

# Login and get token
vault login -method=userpass username=myuser

# Export token
export VAULT_TOKEN="hvs.CAESIJ..."

Create Vault policy:

# policy.hcl
path "secret/data/myapp/*" {
  capabilities = ["read"]
}

path "secret/metadata/myapp/*" {
  capabilities = ["list"]
}

vault policy write fnox-policy policy.hcl

Configure fnox provider:

cat >> fnox.toml << 'EOF'
[providers.vault]
type = "vault"
address = "https://vault.example.com:8200"
path = "secret/myapp"  # KV v2 mount path
# token = "hvs.CAESIJ..."  # Optional, can use VAULT_TOKEN env var instead
EOF

Store secrets in Vault:

# Via Vault CLI (KV v2 engine)
vault kv put secret/myapp/database url="postgresql://prod.example.com/db"
vault kv put secret/myapp/api-key value="sk_live_abc123"

Reference secrets in fnox:

cat >> fnox.toml << 'EOF'
[secrets.DATABASE_URL]
provider = "vault"
value = "database/url"  # ← Vault path + field

[secrets.API_KEY]
provider = "vault"
value = "api-key/value"
EOF

Usage

# Set token (once per session, or use VAULT_TOKEN env var)
export VAULT_TOKEN="hvs.CAESIJ..."

# Get secrets from Vault
fnox get DATABASE_URL

# Run commands
fnox exec -- ./app

Pros:

Advanced features (dynamic secrets, leasing, rotation)
Fine-grained access policies
Audit logging
Multi-cloud support
Self-hosted option

Cons:

Complex to set up and operate
Requires running Vault infrastructure
Token management

OS Keychain

Use Keychain when: You want secrets stored securely on your local machine using the OS native credential store. Perfect for personal projects, local development, or storing tokens that bootstrap other providers.

What is it?

fnox can store secrets in your operating system's native secure storage:

macOS: Keychain Access
Windows: Credential Manager
Linux: Secret Service (GNOME Keyring, KWallet, etc.)

Secrets are stored outside fnox.toml, encrypted by the OS.

Setup

Linux only: Install libsecret:

# Ubuntu/Debian
sudo apt-get install libsecret-1-0 libsecret-1-dev

# Fedora/RHEL
sudo dnf install libsecret libsecret-devel

# Arch
sudo pacman -S libsecret

All platforms:

# Configure provider
cat >> fnox.toml << 'EOF'
[providers.keychain]
type = "keychain"
service = "fnox"  # Namespace for fnox secrets
prefix = "myapp/"  # Optional
EOF

Usage

# Store a secret in OS keychain
fnox set DATABASE_URL "postgresql://localhost/mydb" --provider keychain

# The fnox.toml only contains a reference:
# [secrets.DATABASE_URL]
# provider = "keychain"
# value = "database-url"  # ← Keychain entry name, not the actual secret

# Retrieve from keychain
fnox get DATABASE_URL

# Run commands
fnox exec -- npm run dev

How It Works

Storage: Secrets stored in OS credential manager (encrypted by OS)
Config: fnox.toml contains only the secret name, not the value
Retrieval: fnox queries the OS keychain API
Service: Acts as a namespace (isolates fnox secrets from other apps)
Prefix: Additional namespacing within the service

Pros:

OS-managed encryption
Cross-platform
No external dependencies
Free

Cons:

Requires GUI/interactive session (doesn't work in headless CI)
Not suitable for teams (secrets are per-machine)
Keyring must be unlocked

Use case example: Store your OP_SERVICE_ACCOUNT_TOKEN in keychain, then bootstrap it for 1Password access:

[providers.keychain]
type = "keychain"
service = "fnox"

[secrets.OP_SERVICE_ACCOUNT_TOKEN]
provider = "keychain"
value = "op-token"

Getting Started: A Real Example

Let's build a complete setup for a typical web app with development and production environments.

The Scenario

You're building an API that needs:

Database URL
API keys
JWT secret

Requirements:

Development secrets: In git, encrypted (so team can clone and run)
Production secrets: In AWS Secrets Manager (never in git)

Step 1: Initialize

cd my-api
fnox init

This creates a fnox.toml file.

Step 2: Set Up Age Encryption (for dev secrets)

# Generate age key
age-keygen -o ~/.config/fnox/age.txt

# Get your public key
grep "public key:" ~/.config/fnox/age.txt
# age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p

# Configure age provider
cat >> fnox.toml << 'EOF'
[providers.age]
type = "age"
recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]
EOF

# Set your private key in shell profile
echo 'export FNOX_AGE_KEY=$(cat ~/.config/fnox/age.txt | grep "AGE-SECRET-KEY")' >> ~/.bashrc
source ~/.bashrc

Step 3: Add Dev Secrets

# Encrypt development secrets
fnox set DATABASE_URL "postgresql://localhost/mydb" --provider age
fnox set JWT_SECRET "dev-jwt-secret-$(openssl rand -hex 32)" --provider age
fnox set STRIPE_KEY "sk_test_abc123" --provider age

Your fnox.toml now looks like:

[providers.age]
type = "age"
recipients = ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]

[secrets.DATABASE_URL]
provider = "age"
value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdC..."  # encrypted

[secrets.JWT_SECRET]
provider = "age"
value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdC..."  # encrypted

[secrets.STRIPE_KEY]
provider = "age"
value = "YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdC..."  # encrypted

Commit this! It's encrypted, so it's safe to push to git.

Step 4: Set Up Production (AWS Secrets Manager)

# Add production profile
cat >> fnox.toml << 'EOF'

[profiles.production]

[profiles.production.providers.aws]
type = "aws-sm"
region = "us-east-1"
prefix = "myapi/"

[profiles.production.secrets.DATABASE_URL]
provider = "aws"
value = "database-url"

[profiles.production.secrets.JWT_SECRET]
provider = "aws"
value = "jwt-secret"

[profiles.production.secrets.STRIPE_KEY]
provider = "aws"
value = "stripe-key"
EOF

Now create the secrets in AWS:

aws secretsmanager create-secret \
  --name "myapi/database-url" \
  --secret-string "postgresql://prod.rds.amazonaws.com/mydb"

aws secretsmanager create-secret \
  --name "myapi/jwt-secret" \
  --secret-string "$(openssl rand -base64 64)"

aws secretsmanager create-secret \
  --name "myapi/stripe-key" \
  --secret-string "sk_live_REAL_KEY_HERE"

Step 5: Use It

Development:

# Enable shell integration (one time)
eval "$(fnox activate bash)"
echo 'eval "$(fnox activate bash)"' >> ~/.bashrc

# Now just cd into the project
cd my-api
# fnox: +3 DATABASE_URL, JWT_SECRET, STRIPE_KEY

# Run your app (secrets are already loaded!)
npm run dev

# Or explicitly:
fnox exec -- npm run dev

Production:

# Set AWS credentials (IAM role, or env vars)
export AWS_REGION=us-east-1

# Run with production profile
fnox exec --profile production -- node server.js

CI/CD:

# .github/workflows/deploy.yml
name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jdx/mise-action@v3 # you'll need a mise.toml with fnox configured

      - name: Setup age key
        env:
          FNOX_AGE_KEY: ${{ secrets.FNOX_AGE_KEY }}
        run: |
          mkdir -p ~/.config/fnox
          echo "$FNOX_AGE_KEY" > ~/.config/fnox/age.txt
          chmod 600 ~/.config/fnox/age.txt

      - name: Deploy to production
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          fnox exec --profile production -- ./deploy.sh

What Just Happened?

✅ Dev secrets are encrypted in git → Team can clone and run immediately
✅ Prod secrets are in AWS → Never in git, centrally managed
✅ Shell integration → Secrets auto-load on cd
✅ CI/CD ready → GitHub Actions can decrypt dev secrets and access AWS for prod
✅ Profiles → Same fnox.toml, different environments

Advanced Features

Profiles

Organize secrets by environment:

# Default profile (dev)
[secrets.API_URL]
default = "http://localhost:3000"

# Staging profile
[profiles.staging.secrets.API_URL]
default = "https://staging.example.com"

# Production profile
[profiles.production.secrets.API_URL]
provider = "aws"
value = "api-url"

fnox get API_URL                           # dev
fnox get API_URL --profile staging         # staging
fnox get API_URL --profile production      # production

Hierarchical Configuration

fnox searches parent directories for fnox.toml files and merges them:

project/
├── fnox.toml              # Root: age encryption, common secrets
└── services/
    └── api/
        └── fnox.toml      # API-specific secrets, inherits age config

Child configs override parent values. Great for monorepos!

Configuration Imports

Split configs across files:

# fnox.toml
imports = ["./secrets/dev.toml", "./secrets/prod.toml"]

[providers.age]
type = "age"
recipients = ["age1..."]

# secrets/dev.toml
[secrets.DATABASE_URL]
provider = "age"
value = "encrypted..."

Secret Resolution

fnox resolves secrets in this order:

Encrypted value (provider = "age", value = "encrypted...")
Provider reference (provider = "aws", value = "secret-name")
Environment variable (if $ENV_VAR exists)
Default value (default = "fallback")

First match wins!

Default Values

Set fallbacks for optional secrets:

[secrets.NODE_ENV]
default = "development"  # Used if not found elsewhere

[secrets.LOG_LEVEL]
default = "info"
if_missing = "warn"  # "error", "warn", or "ignore"

Import/Export

Migrate from .env files:

# Import from .env
fnox import --format env --source .env

# Export to various formats
fnox export --format json > secrets.json
fnox export --format yaml > secrets.yaml
fnox export --format toml > secrets.toml

Commands Reference

Core Commands

fnox init - Initialize fnox.toml
fnox get <KEY> - Get a secret value
fnox set <KEY> [VALUE] - Set a secret (encrypts if provider supports it)
fnox list - List all secrets
fnox remove <KEY> - Remove a secret
fnox exec -- <COMMAND> - Run command with secrets as env vars
fnox export - Export secrets in various formats
fnox import - Import secrets from files

Management Commands

fnox provider list - List all providers
fnox provider test <NAME> - Test provider connection
fnox profiles - List all profiles
fnox edit - Open config in editor

Diagnostic Commands

fnox doctor - Show diagnostic info
fnox check - Verify all secrets are configured
fnox scan - Scan for plaintext secrets in code

Shell Integration

fnox activate <SHELL> - Generate shell activation code
fnox hook-env - Internal command for shell hooks
fnox completion <SHELL> - Generate completions

Developer Tools

fnox ci-redact - Mask secrets in CI logs

Environment Variables

FNOX_PROFILE - Active profile (default: default)
FNOX_CONFIG_DIR - Config directory (default: ~/.config/fnox)
FNOX_AGE_KEY - Age encryption key (alternative to file)
FNOX_AGE_KEY_FILE - Path to age key file
FNOX_SHELL_OUTPUT - Shell integration output (none, normal, debug)

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.github		.github
.vscode		.vscode
build		build
mise-tasks		mise-tasks
src		src
test		test
tmp		tmp
.gitignore		.gitignore
.gitmodules		.gitmodules
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CRUSH.md		CRUSH.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
ONEPASSWORD.md		ONEPASSWORD.md
README.md		README.md
build.rs		build.rs
cliff.toml		cliff.toml
example.fnox.toml		example.fnox.toml
fnox.toml		fnox.toml
fnox.usage.kdl		fnox.usage.kdl
hk.pkl		hk.pkl
mise.toml		mise.toml
settings.toml		settings.toml

License

jdx/fnox

Folders and files

Latest commit

History

Repository files navigation

🔐 fnox

What is fnox?

Supported Providers

🔐 Encryption (secrets in git, encrypted)

☁️ Cloud Secret Storage (remote, centralized)

🔑 Password Managers

💻 Local Storage

Installation

Using mise (recommended)

Using Cargo

From Source

Quick Start

How It Works

Shell Integration

Why is this a standalone CLI and not part of mise?

Providers: Complete Getting Started Guides

Age Encryption

Setup

Usage

SSH Key Support

Team Workflow

1Password

Prerequisites

Setup

Usage

Reference Formats

Bitwarden

Prerequisites

Setup

Usage

Reference Formats

Testing with Vaultwarden

AWS Secrets Manager

Prerequisites

Setup

Usage

How It Works

AWS KMS

Prerequisites

Setup

Usage

How It Works

Azure Key Vault

Azure Key Vault Secrets (Remote Storage)

Prerequisites

Setup

Usage

Azure Key Vault Keys (Encryption)

Setup

Google Cloud Secret Manager

GCP Secret Manager (Remote Storage)

Prerequisites

Setup

Usage

Google Cloud KMS (Encryption)

Setup

HashiCorp Vault

Prerequisites

Setup

Usage

OS Keychain

What is it?

Setup

Usage

How It Works

Getting Started: A Real Example

The Scenario

Step 1: Initialize

Step 2: Set Up Age Encryption (for dev secrets)

Step 3: Add Dev Secrets

Step 4: Set Up Production (AWS Secrets Manager)

Step 5: Use It

What Just Happened?

Advanced Features

Packages